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