base/callback.h

   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
  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
  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
  82   bool Equals(const OnceCallback& other) const { return EqualsInternal(other); }
  83
  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
  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
 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
 122   bool Equals(const RepeatingCallback& other) const {
 123     return EqualsInternal(other);
 124   }
 125
 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
 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_