base/cancelable_callback.h

   1 // Copyright (c) 2011 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 // CancelableCallback is a wrapper around base::Callback that allows
   6 // cancellation of a callback. CancelableCallback takes a reference on the
   7 // wrapped callback until this object is destroyed or Reset()/Cancel() are
   8 // called.
   9 //
  10 // NOTE:
  11 //
  12 // Calling CancelableCallback::Cancel() brings the object back to its natural,
  13 // default-constructed state, i.e., CancelableCallback::callback() will return
  14 // a null callback.
  15 //
  16 // THREAD-SAFETY:
  17 //
  18 // CancelableCallback objects must be created on, posted to, cancelled on, and
  19 // destroyed on the same thread.
  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 // ThreadTaskRunnerHandle::Get()->PostDelayedTask(FROM_HERE, timeout.callback(),
  39 //                                                TimeDelta::FromSeconds(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/base_export.h"
  51 #include "base/bind.h"
  52 #include "base/callback.h"
  53 #include "base/callback_internal.h"
  54 #include "base/check.h"
  55 #include "base/compiler_specific.h"
  56 #include "base/macros.h"
  57 #include "base/memory/weak_ptr.h"
  58
  59 namespace base {
  60 namespace internal {
  61
  62 template <typename CallbackType>
  63 class CancelableCallbackImpl {
  64  public:
  65   CancelableCallbackImpl() {}
  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   DISALLOW_COPY_AND_ASSIGN(CancelableCallbackImpl);
 135 };
 136
 137 }  // namespace internal
 138
 139 // Consider using base::WeakPtr directly instead of base::CancelableCallback for
 140 // the task cancellation.
 141 template <typename Signature>
 142 using CancelableOnceCallback =
 143     internal::CancelableCallbackImpl<OnceCallback<Signature>>;
 144 using CancelableOnceClosure = CancelableOnceCallback<void()>;
 145
 146 template <typename Signature>
 147 using CancelableRepeatingCallback =
 148     internal::CancelableCallbackImpl<RepeatingCallback<Signature>>;
 149 using CancelableRepeatingClosure = CancelableRepeatingCallback<void()>;
 150
 151 template <typename Signature>
 152 using CancelableCallback = CancelableRepeatingCallback<Signature>;
 153 using CancelableClosure = CancelableCallback<void()>;
 154
 155 }  // namespace base
 156
 157 #endif  // BASE_CANCELABLE_CALLBACK_H_