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