base/cancelable_callback.h

   1 // Copyright 2011 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4 //
   5 // CancelableOnceCallback is a wrapper around OnceCallback that allows
   6 // cancellation of the callback. CanacelableRepeatingCallback is the same sort
   7 // of wrapper around RepeatingCallback. The wrapper takes a reference on the
   8 // wrapped callback until this object is destroyed or Reset()/Cancel() are
   9 // called.
  10 //
  11 // NOTE:
  12 //
  13 // Calling Cancel() brings the object back to its natural, default-constructed
  14 // state, i.e., callback() will return a null callback.
  15 //
  16 // THREAD-SAFETY:
  17 //
  18 // Cancelable callback objects must be created on, posted to, cancelled on, and
  19 // destroyed on the same SequencedTaskRunner.
  20 //
  21 //
  22 // EXAMPLE USAGE:
  23 //
  24 // In the following example, the test is verifying that RunIntensiveTest()
  25 // Quit()s the message loop within 4 seconds. The cancelable callback is posted
  26 // to the message loop, the intensive test runs, the message loop is run,
  27 // then the callback is cancelled.
  28 //
  29 // RunLoop run_loop;
  30 //
  31 // void TimeoutCallback(const std::string& timeout_message) {
  32 //   FAIL() << timeout_message;
  33 //   run_loop.QuitWhenIdle();
  34 // }
  35 //
  36 // CancelableOnceClosure timeout(
  37 //     base::BindOnce(&TimeoutCallback, "Test timed out."));
  38 // SingleThreadTaskRunner::GetCurrentDefault()->PostDelayedTask(
  39 //     FROM_HERE, timeout.callback(), Seconds(4));
  40 // RunIntensiveTest();
  41 // run_loop.Run();
  42 // timeout.Cancel();  // Hopefully this is hit before the timeout callback runs.
  43 //
  44
  45 #ifndef BASE_CANCELABLE_CALLBACK_H_
  46 #define BASE_CANCELABLE_CALLBACK_H_
  47
  48 #include <utility>
  49
  50 #include "base/check.h"
  51 #include "base/compiler_specific.h"
  52 #include "base/functional/bind.h"
  53 #include "base/functional/callback.h"
  54 #include "base/functional/callback_internal.h"
  55 #include "base/memory/weak_ptr.h"
  56
  57 namespace base {
  58 namespace internal {
  59
  60 template <typename CallbackType>
  61 class CancelableCallbackImpl {
  62  public:
  63   CancelableCallbackImpl() = default;
  64   CancelableCallbackImpl(const CancelableCallbackImpl&) = delete;
  65   CancelableCallbackImpl& operator=(const CancelableCallbackImpl&) = delete;
  66
  67   // |callback| must not be null.
  68   explicit CancelableCallbackImpl(CallbackType callback)
  69       : callback_(std::move(callback)) {
  70     DCHECK(callback_);
  71   }
  72
  73   ~CancelableCallbackImpl() = default;
  74
  75   // Cancels and drops the reference to the wrapped callback.
  76   void Cancel() {
  77     weak_ptr_factory_.InvalidateWeakPtrs();
  78     callback_.Reset();
  79   }
  80
  81   // Returns true if the wrapped callback has been cancelled.
  82   bool IsCancelled() const {
  83     return callback_.is_null();
  84   }
  85
  86   // Sets |callback| as the closure that may be cancelled. |callback| may not
  87   // be null. Outstanding and any previously wrapped callbacks are cancelled.
  88   void Reset(CallbackType callback) {
  89     DCHECK(callback);
  90     // Outstanding tasks (e.g., posted to a message loop) must not be called.
  91     Cancel();
  92     callback_ = std::move(callback);
  93   }
  94
  95   // Returns a callback that can be disabled by calling Cancel().
  96   CallbackType callback() const {
  97     if (!callback_)
  98       return CallbackType();
  99     CallbackType forwarder;
 100     MakeForwarder(&forwarder);
 101     return forwarder;
 102   }
 103
 104  private:
 105   template <typename... Args>
 106   void MakeForwarder(RepeatingCallback<void(Args...)>* out) const {
 107     using ForwarderType = void (CancelableCallbackImpl::*)(Args...);
 108     ForwarderType forwarder = &CancelableCallbackImpl::ForwardRepeating;
 109     *out = BindRepeating(forwarder, weak_ptr_factory_.GetWeakPtr());
 110   }
 111
 112   template <typename... Args>
 113   void MakeForwarder(OnceCallback<void(Args...)>* out) const {
 114     using ForwarderType = void (CancelableCallbackImpl::*)(Args...);
 115     ForwarderType forwarder = &CancelableCallbackImpl::ForwardOnce;
 116     *out = BindOnce(forwarder, weak_ptr_factory_.GetWeakPtr());
 117   }
 118
 119   template <typename... Args>
 120   void ForwardRepeating(Args... args) {
 121     callback_.Run(std::forward<Args>(args)...);
 122   }
 123
 124   template <typename... Args>
 125   void ForwardOnce(Args... args) {
 126     weak_ptr_factory_.InvalidateWeakPtrs();
 127     std::move(callback_).Run(std::forward<Args>(args)...);
 128   }
 129
 130   // The stored closure that may be cancelled.
 131   CallbackType callback_;
 132   mutable base::WeakPtrFactory<CancelableCallbackImpl> weak_ptr_factory_{this};
 133 };
 134
 135 }  // namespace internal
 136
 137 // Consider using base::WeakPtr directly instead of base::CancelableOnceCallback
 138 // for task cancellation.
 139 template <typename Signature>
 140 using CancelableOnceCallback =
 141     internal::CancelableCallbackImpl<OnceCallback<Signature>>;
 142 using CancelableOnceClosure = CancelableOnceCallback<void()>;
 143
 144 template <typename Signature>
 145 using CancelableRepeatingCallback =
 146     internal::CancelableCallbackImpl<RepeatingCallback<Signature>>;
 147 using CancelableRepeatingClosure = CancelableRepeatingCallback<void()>;
 148
 149 }  // namespace base
 150
 151 #endif  // BASE_CANCELABLE_CALLBACK_H_