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