1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 // 5 // NOTE: Header files that do not require the full definition of Callback or 6 // Closure should #include "base/callback_forward.h" instead of this file. 7 8 #ifndef BASE_CALLBACK_H_ 9 #define BASE_CALLBACK_H_ 10 11 #include <stddef.h> 12 13 #include "base/callback_forward.h" 14 #include "base/callback_internal.h" 15 16 // ----------------------------------------------------------------------------- 17 // Usage documentation 18 // ----------------------------------------------------------------------------- 19 // 20 // Overview: 21 // A callback is similar in concept to a function pointer: it wraps a runnable 22 // object such as a function, method, lambda, or even another callback, allowing 23 // the runnable object to be invoked later via the callback object. 24 // 25 // Unlike function pointers, callbacks are created with base::BindOnce() or 26 // base::BindRepeating() and support partial function application. 27 // 28 // A base::OnceCallback may be Run() at most once; a base::RepeatingCallback may 29 // be Run() any number of times. |is_null()| is guaranteed to return true for a 30 // moved-from callback. 31 // 32 // // The lambda takes two arguments, but the first argument |x| is bound at 33 // // callback creation. 34 // base::OnceCallback<int(int)> cb = base::BindOnce([] (int x, int y) { 35 // return x + y; 36 // }, 1); 37 // // Run() only needs the remaining unbound argument |y|. 38 // printf("1 + 2 = %d\n", std::move(cb).Run(2)); // Prints 3 39 // printf("cb is null? %s\n", 40 // cb.is_null() ? "true" : "false"); // Prints true 41 // std::move(cb).Run(2); // Crashes since |cb| has already run. 42 // 43 // Callbacks also support cancellation. A common use is binding the receiver 44 // object as a WeakPtr<T>. If that weak pointer is invalidated, calling Run() 45 // will be a no-op. Note that |is_cancelled()| and |is_null()| are distinct: 46 // simply cancelling a callback will not also make it null. 47 // 48 // base::Callback is currently a type alias for base::RepeatingCallback. In the 49 // future, we expect to flip this to default to base::OnceCallback. 50 // 51 // See //docs/callback.md for the full documentation. 52 53 namespace base { 54 55 template <typename R, typename... Args> 56 class OnceCallback<R(Args...)> : public internal::CallbackBase { 57 public: 58 using RunType = R(Args...); 59 using PolymorphicInvoke = R (*)(internal::BindStateBase*, 60 internal::PassingType<Args>...); 61 62 constexpr OnceCallback() = default; 63 OnceCallback(std::nullptr_t) = delete; 64 OnceCallback(internal::BindStateBase * bind_state)65 explicit OnceCallback(internal::BindStateBase* bind_state) 66 : internal::CallbackBase(bind_state) {} 67 68 OnceCallback(const OnceCallback&) = delete; 69 OnceCallback& operator=(const OnceCallback&) = delete; 70 71 OnceCallback(OnceCallback&&) noexcept = default; 72 OnceCallback& operator=(OnceCallback&&) noexcept = default; 73 OnceCallback(RepeatingCallback<RunType> other)74 OnceCallback(RepeatingCallback<RunType> other) 75 : internal::CallbackBase(std::move(other)) {} 76 77 OnceCallback& operator=(RepeatingCallback<RunType> other) { 78 static_cast<internal::CallbackBase&>(*this) = std::move(other); 79 return *this; 80 } 81 Equals(const OnceCallback & other)82 bool Equals(const OnceCallback& other) const { return EqualsInternal(other); } 83 Run(Args...args)84 R Run(Args... args) const & { 85 static_assert(!sizeof(*this), 86 "OnceCallback::Run() may only be invoked on a non-const " 87 "rvalue, i.e. std::move(callback).Run()."); 88 NOTREACHED(); 89 } 90 Run(Args...args)91 R Run(Args... args) && { 92 // Move the callback instance into a local variable before the invocation, 93 // that ensures the internal state is cleared after the invocation. 94 // It's not safe to touch |this| after the invocation, since running the 95 // bound function may destroy |this|. 96 OnceCallback cb = std::move(*this); 97 PolymorphicInvoke f = 98 reinterpret_cast<PolymorphicInvoke>(cb.polymorphic_invoke()); 99 return f(cb.bind_state_.get(), std::forward<Args>(args)...); 100 } 101 }; 102 103 template <typename R, typename... Args> 104 class RepeatingCallback<R(Args...)> : public internal::CallbackBaseCopyable { 105 public: 106 using RunType = R(Args...); 107 using PolymorphicInvoke = R (*)(internal::BindStateBase*, 108 internal::PassingType<Args>...); 109 110 constexpr RepeatingCallback() = default; 111 RepeatingCallback(std::nullptr_t) = delete; 112 RepeatingCallback(internal::BindStateBase * bind_state)113 explicit RepeatingCallback(internal::BindStateBase* bind_state) 114 : internal::CallbackBaseCopyable(bind_state) {} 115 116 // Copyable and movable. 117 RepeatingCallback(const RepeatingCallback&) = default; 118 RepeatingCallback& operator=(const RepeatingCallback&) = default; 119 RepeatingCallback(RepeatingCallback&&) noexcept = default; 120 RepeatingCallback& operator=(RepeatingCallback&&) noexcept = default; 121 Equals(const RepeatingCallback & other)122 bool Equals(const RepeatingCallback& other) const { 123 return EqualsInternal(other); 124 } 125 Run(Args...args)126 R Run(Args... args) const & { 127 PolymorphicInvoke f = 128 reinterpret_cast<PolymorphicInvoke>(this->polymorphic_invoke()); 129 return f(this->bind_state_.get(), std::forward<Args>(args)...); 130 } 131 Run(Args...args)132 R Run(Args... args) && { 133 // Move the callback instance into a local variable before the invocation, 134 // that ensures the internal state is cleared after the invocation. 135 // It's not safe to touch |this| after the invocation, since running the 136 // bound function may destroy |this|. 137 RepeatingCallback cb = std::move(*this); 138 PolymorphicInvoke f = 139 reinterpret_cast<PolymorphicInvoke>(cb.polymorphic_invoke()); 140 return f(cb.bind_state_.get(), std::forward<Args>(args)...); 141 } 142 }; 143 144 } // namespace base 145 146 #endif // BASE_CALLBACK_H_ 147