1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
// 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_
|
