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 // 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 // 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/memory/weak_ptr.h"
  57
  58 namespace base {
  59 namespace internal {
  60
  61 template <typename CallbackType>
  62 class CancelableCallbackImpl {
  63  public:
  64   CancelableCallbackImpl() = default;
  65   CancelableCallbackImpl(const CancelableCallbackImpl&) = delete;
  66   CancelableCallbackImpl& operator=(const CancelableCallbackImpl&) = delete;
  67
  68   // |callback| must not be null.
  69   explicit CancelableCallbackImpl(CallbackType callback)
  70       : callback_(std::move(callback)) {
  71     DCHECK(callback_);
  72   }
  73
  74   ~CancelableCallbackImpl() = default;
  75
  76   // Cancels and drops the reference to the wrapped callback.
  77   void Cancel() {
  78     weak_ptr_factory_.InvalidateWeakPtrs();
  79     callback_.Reset();
  80   }
  81
  82   // Returns true if the wrapped callback has been cancelled.
  83   bool IsCancelled() const {
  84     return callback_.is_null();
  85   }
  86
  87   // Sets |callback| as the closure that may be cancelled. |callback| may not
  88   // be null. Outstanding and any previously wrapped callbacks are cancelled.
  89   void Reset(CallbackType callback) {
  90     DCHECK(callback);
  91     // Outstanding tasks (e.g., posted to a message loop) must not be called.
  92     Cancel();
  93     callback_ = std::move(callback);
  94   }
  95
  96   // Returns a callback that can be disabled by calling Cancel().
  97   CallbackType callback() const {
  98     if (!callback_)
  99       return CallbackType();
 100     CallbackType forwarder;
 101     MakeForwarder(&forwarder);
 102     return forwarder;
 103   }
 104
 105  private:
 106   template <typename... Args>
 107   void MakeForwarder(RepeatingCallback<void(Args...)>* out) const {
 108     using ForwarderType = void (CancelableCallbackImpl::*)(Args...);
 109     ForwarderType forwarder = &CancelableCallbackImpl::ForwardRepeating;
 110     *out = BindRepeating(forwarder, weak_ptr_factory_.GetWeakPtr());
 111   }
 112
 113   template <typename... Args>
 114   void MakeForwarder(OnceCallback<void(Args...)>* out) const {
 115     using ForwarderType = void (CancelableCallbackImpl::*)(Args...);
 116     ForwarderType forwarder = &CancelableCallbackImpl::ForwardOnce;
 117     *out = BindOnce(forwarder, weak_ptr_factory_.GetWeakPtr());
 118   }
 119
 120   template <typename... Args>
 121   void ForwardRepeating(Args... args) {
 122     callback_.Run(std::forward<Args>(args)...);
 123   }
 124
 125   template <typename... Args>
 126   void ForwardOnce(Args... args) {
 127     weak_ptr_factory_.InvalidateWeakPtrs();
 128     std::move(callback_).Run(std::forward<Args>(args)...);
 129   }
 130
 131   // The stored closure that may be cancelled.
 132   CallbackType callback_;
 133   mutable base::WeakPtrFactory<CancelableCallbackImpl> weak_ptr_factory_{this};
 134 };
 135
 136 }  // namespace internal
 137
 138 // Consider using base::WeakPtr directly instead of base::CancelableOnceCallback
 139 // for task cancellation.
 140 template <typename Signature>
 141 using CancelableOnceCallback =
 142     internal::CancelableCallbackImpl<OnceCallback<Signature>>;
 143 using CancelableOnceClosure = CancelableOnceCallback<void()>;
 144
 145 template <typename Signature>
 146 using CancelableRepeatingCallback =
 147     internal::CancelableCallbackImpl<RepeatingCallback<Signature>>;
 148 using CancelableRepeatingClosure = CancelableRepeatingCallback<void()>;
 149
 150 }  // namespace base
 151
 152 #endif  // BASE_CANCELABLE_CALLBACK_H_