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 //
IsPowerOfTwo(T value)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
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
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
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
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
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
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
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