| // Copyright 2022 The Chromium Authors |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| #ifndef BASE_FUNCTIONAL_DISALLOW_UNRETAINED_H_ |
| #define BASE_FUNCTIONAL_DISALLOW_UNRETAINED_H_ |
| |
| // IMPORTANT: this is currently experimental. Use with caution, as the |
| // interaction with various base APIs is still unstable and subject to change. |
| // |
| // Types can opt to forbid use of `Unretained()`, et cetera by using this macro |
| // to annotate their class definition: |
| // |
| // class Dangerous { |
| // DISALLOW_UNRETAINED(); |
| // public: |
| // |
| // ... |
| // |
| // void PostAsyncWork() { |
| // // Will not compile. |
| // task_runner_->PostTask( |
| // FROM_HERE, |
| // base::BindOnce(&Dangerous::OnAsyncWorkDone, base::Unretained(this))); |
| // } |
| // |
| // void OnAsyncWorkDone() { |
| // ... |
| // } |
| // }; |
| // |
| // A type that disallows use of base::Unretained() can still be used with |
| // callback: |
| // |
| // - If a type is only used on one sequence (e.g. `content::RenderFrameHostImpl` |
| // may only be used on the UI thread), embed a `base::WeakPtrFactory<T>` and |
| // either use: |
| // |
| // - `GetSafeRef()` to bind a `SafeRef<T>` if `this` must *always* still be |
| // alive when the callback is invoked, e.g. binding Mojo reply callbacks |
| // when making Mojo calls through a `mojo::Remote` owned by `this`. |
| // |
| // - `GetWeakPtr()` to bind a `WeakPtr<T>` if the lifetimes are unclear, e.g. |
| // a task posted to main UI task runner, and a strong lifetime assertion is |
| // not possible. |
| // |
| // - Note 1: use `WeakPtr<T>` only when appropriate. `WeakPtr<T>` makes it |
| // harder to reason about lifetimes; while it is necessary and appropriate |
| // in many places, using it unnecessarily makes it hard to understand when |
| // one object is guaranteed to outlive another. |
| // |
| // - Note 2: whether `GetSafeRef()` or `GetWeakPtr()` is used, include |
| // comments to explain the assumptions behind the selection. Though these |
| // comments may become inaccurate over time, they are still valuable |
| // to helping when reading unfamiliar code. |
| // |
| // - If a type is used on multiple sequences, make it refcounted and either bind |
| // a `scoped_refptr<t>` or use `base::RetainedRef()`. |
| // |
| // - Consider if callbacks are needed at all; using abstractions like |
| // `base::SequenceBound<T>` make it much easier to manage cross-sequence |
| // lifetimes and avoid the need to write `base::Unretained()` at all. |
| #define DISALLOW_UNRETAINED() \ |
| public: \ |
| using DisallowBaseUnretainedMarker [[maybe_unused]] = void; \ |
| \ |
| private: \ |
| /* No-op statement so use of this macro can be followed by `;`. */ \ |
| static_assert(true) |
| |
| #endif // BASE_FUNCTIONAL_DISALLOW_UNRETAINED_H_ |
