1 // Copyright 2012 The Chromium Authors
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 // This file contains utility functions and classes that help the
6 // implementation, and management of the Callback objects.
8 #ifndef BASE_FUNCTIONAL_CALLBACK_INTERNAL_H_
9 #define BASE_FUNCTIONAL_CALLBACK_INTERNAL_H_
13 #include "base/base_export.h"
14 #include "base/compiler_specific.h"
15 #include "base/functional/callback_forward.h"
16 #include "base/memory/ref_counted.h"
26 template <typename Functor, typename... BoundArgs>
29 struct BASE_EXPORT BindStateBaseRefCountTraits {
30 static void Destruct(const BindStateBase*);
34 using PassingType = std::conditional_t<std::is_scalar_v<T>, T, T&&>;
36 // BindStateBase is used to provide an opaque handle that the Callback
37 // class can use to represent a function object with bound arguments. It
38 // behaves as an existential type that is used by a corresponding
39 // DoInvoke function to perform the function execution. This allows
40 // us to shield the Callback class from the types of the bound argument via
42 // At the base level, the only task is to add reference counting data. Avoid
43 // using or inheriting any virtual functions. Creating a vtable for every
44 // BindState template instantiation results in a lot of bloat. Its only task is
45 // to call the destructor which can be done with a function pointer.
46 class BASE_EXPORT BindStateBase
47 : public RefCountedThreadSafe<BindStateBase, BindStateBaseRefCountTraits> {
49 REQUIRE_ADOPTION_FOR_REFCOUNTED_TYPE();
51 enum CancellationQueryMode {
56 using InvokeFuncStorage = void (*)();
58 BindStateBase(const BindStateBase&) = delete;
59 BindStateBase& operator=(const BindStateBase&) = delete;
62 BindStateBase(InvokeFuncStorage polymorphic_invoke,
63 void (*destructor)(const BindStateBase*));
64 BindStateBase(InvokeFuncStorage polymorphic_invoke,
65 void (*destructor)(const BindStateBase*),
66 bool (*query_cancellation_traits)(const BindStateBase*,
67 CancellationQueryMode mode));
69 ~BindStateBase() = default;
71 friend struct BindStateBaseRefCountTraits;
72 friend class RefCountedThreadSafe<BindStateBase, BindStateBaseRefCountTraits>;
74 friend class BindStateHolder;
76 // Allowlist subclasses that access the destructor of BindStateBase.
77 template <typename Functor, typename... BoundArgs>
78 friend struct BindState;
79 friend struct ::base::FakeBindState;
81 bool IsCancelled() const {
82 return query_cancellation_traits_(this, IS_CANCELLED);
85 bool MaybeValid() const {
86 return query_cancellation_traits_(this, MAYBE_VALID);
89 // In C++, it is safe to cast function pointers to function pointers of
90 // another type. It is not okay to use void*. We create a InvokeFuncStorage
91 // that that can store our function pointer, and then cast it back to
92 // the original type on usage.
93 InvokeFuncStorage polymorphic_invoke_;
95 // Pointer to a function that will properly destroy |this|.
96 void (*destructor_)(const BindStateBase*);
97 bool (*query_cancellation_traits_)(const BindStateBase*,
98 CancellationQueryMode mode);
101 // Minimal wrapper around a `scoped_refptr<BindStateBase>`. It allows more
102 // expensive operations (such as ones that destroy `BindStateBase` or manipulate
103 // refcounts) to be defined out-of-line to reduce binary size.
104 class BASE_EXPORT TRIVIAL_ABI BindStateHolder {
106 using InvokeFuncStorage = BindStateBase::InvokeFuncStorage;
108 // Used to construct a null callback.
109 inline constexpr BindStateHolder() noexcept;
111 // Used to construct a callback by `base::BindOnce()`/`base::BindRepeating().
112 inline explicit BindStateHolder(BindStateBase* bind_state);
114 // BindStateHolder is always copyable so it can be used by `OnceCallback` and
115 // `RepeatingCallback`. `OnceCallback` restricts copies so a `BindStateHolder`
116 // used with a `OnceCallback will never be copied.
117 BindStateHolder(const BindStateHolder&);
118 BindStateHolder& operator=(const BindStateHolder&);
120 // Subtle: since `this` is marked as TRIVIAL_ABI, the move operations must
121 // leave a moved-from `BindStateHolder` in a trivially destructible state.
122 inline BindStateHolder(BindStateHolder&&) noexcept;
123 BindStateHolder& operator=(BindStateHolder&&) noexcept;
127 bool is_null() const { return !bind_state_; }
128 explicit operator bool() const { return !is_null(); }
130 bool IsCancelled() const;
131 bool MaybeValid() const;
135 bool operator==(const BindStateHolder& other) const {
136 return bind_state_ == other.bind_state_;
139 const scoped_refptr<BindStateBase>& bind_state() const { return bind_state_; }
141 InvokeFuncStorage polymorphic_invoke() const {
142 return bind_state_->polymorphic_invoke_;
146 scoped_refptr<BindStateBase> bind_state_;
149 constexpr BindStateHolder::BindStateHolder() noexcept = default;
151 // TODO(dcheng): Try plumbing a scoped_refptr all the way through, since
152 // scoped_refptr is marked as TRIVIAL_ABI.
153 BindStateHolder::BindStateHolder(BindStateBase* bind_state)
154 : bind_state_(AdoptRef(bind_state)) {}
156 // Unlike the copy constructor, copy assignment operator, and move assignment
157 // operator, the move constructor is defaulted in the header because it
158 // generates minimal code: move construction does not change any refcounts, nor
159 // does it potentially destroy `BindStateBase`.
160 BindStateHolder::BindStateHolder(BindStateHolder&&) noexcept = default;
162 // Helpers for the `Then()` implementation.
163 template <typename OriginalCallback, typename ThenCallback>
166 // Specialization when original callback returns `void`.
167 template <template <typename> class OriginalCallback,
170 typename... OriginalArgs,
172 typename... ThenArgs>
173 struct ThenHelper<OriginalCallback<void(OriginalArgs...)>,
174 ThenCallback<ThenR(ThenArgs...)>> {
175 static_assert(sizeof...(ThenArgs) == 0,
176 "|then| callback cannot accept parameters if |this| has a "
177 "void return type.");
179 static auto CreateTrampoline() {
180 return [](OriginalCallback<void(OriginalArgs...)> c1,
181 ThenCallback<ThenR(ThenArgs...)> c2, OriginalArgs... c1_args) {
182 std::move(c1).Run(std::forward<OriginalArgs>(c1_args)...);
183 return std::move(c2).Run();
188 // Specialization when original callback returns a non-void type.
189 template <template <typename> class OriginalCallback,
193 typename... OriginalArgs,
195 typename... ThenArgs>
196 struct ThenHelper<OriginalCallback<OriginalR(OriginalArgs...)>,
197 ThenCallback<ThenR(ThenArgs...)>> {
198 static_assert(sizeof...(ThenArgs) == 1,
199 "|then| callback must accept exactly one parameter if |this| "
200 "has a non-void return type.");
201 // TODO(dcheng): This should probably check is_convertible as well (same with
202 // `AssertBindArgsValidity`).
203 static_assert(std::is_constructible_v<ThenArgs..., OriginalR&&>,
204 "|then| callback's parameter must be constructible from "
205 "return type of |this|.");
207 static auto CreateTrampoline() {
208 return [](OriginalCallback<OriginalR(OriginalArgs...)> c1,
209 ThenCallback<ThenR(ThenArgs...)> c2, OriginalArgs... c1_args) {
210 return std::move(c2).Run(
211 std::move(c1).Run(std::forward<OriginalArgs>(c1_args)...));
216 } // namespace internal
219 #endif // BASE_FUNCTIONAL_CALLBACK_INTERNAL_H_