base/task/cancelable_task_tracker.h

   1 // Copyright 2014 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 // CancelableTaskTracker posts tasks (in the form of a Closure) to a
   6 // TaskRunner, and is able to cancel the task later if it's not needed
   7 // anymore.  On destruction, CancelableTaskTracker will cancel all
   8 // tracked tasks.
   9 //
  10 // Each cancelable task can be associated with a reply (also a Closure). After
  11 // the task is run on the TaskRunner, |reply| will be posted back to
  12 // originating TaskRunner.
  13 //
  14 // NOTE:
  15 //
  16 // CancelableCallback (base/cancelable_callback.h) and WeakPtr binding are
  17 // preferred solutions for canceling a task. However, they don't support
  18 // cancelation from another thread. This is sometimes a performance critical
  19 // requirement. E.g. We need to cancel database lookup task on DB thread when
  20 // user changes inputed text. If it is performance critical to do a best effort
  21 // cancelation of a task, then CancelableTaskTracker is appropriate,
  22 // otherwise use one of the other mechanisms.
  23 //
  24 // THREAD-SAFETY:
  25 //
  26 // 1. CancelableTaskTracker objects are not thread safe. They must
  27 // be created, used, and destroyed on the originating thread that posts the
  28 // task. It's safe to destroy a CancelableTaskTracker while there
  29 // are outstanding tasks. This is commonly used to cancel all outstanding
  30 // tasks.
  31 //
  32 // 2. Both task and reply are deleted on the originating thread.
  33 //
  34 // 3. IsCanceledCallback is thread safe and can be run or deleted on any
  35 // thread.
  36 #ifndef BASE_TASK_CANCELABLE_TASK_TRACKER_H_
  37 #define BASE_TASK_CANCELABLE_TASK_TRACKER_H_
  38
  39 #include "base/base_export.h"
  40 #include "base/basictypes.h"
  41 #include "base/callback.h"
  42 #include "base/containers/hash_tables.h"
  43 #include "base/memory/weak_ptr.h"
  44 #include "base/task_runner_util.h"
  45 #include "base/threading/thread_checker.h"
  46
  47 namespace tracked_objects {
  48 class Location;
  49 }  // namespace tracked_objects
  50
  51 namespace base {
  52
  53 class CancellationFlag;
  54 class TaskRunner;
  55
  56 class BASE_EXPORT CancelableTaskTracker {
  57  public:
  58   // All values except kBadTaskId are valid.
  59   typedef int64 TaskId;
  60   static const TaskId kBadTaskId;
  61
  62   typedef base::Callback<bool()> IsCanceledCallback;
  63
  64   CancelableTaskTracker();
  65
  66   // Cancels all tracked tasks.
  67   ~CancelableTaskTracker();
  68
  69   TaskId PostTask(base::TaskRunner* task_runner,
  70                   const tracked_objects::Location& from_here,
  71                   const base::Closure& task);
  72
  73   TaskId PostTaskAndReply(base::TaskRunner* task_runner,
  74                           const tracked_objects::Location& from_here,
  75                           const base::Closure& task,
  76                           const base::Closure& reply);
  77
  78   template <typename TaskReturnType, typename ReplyArgType>
  79   TaskId PostTaskAndReplyWithResult(
  80       base::TaskRunner* task_runner,
  81       const tracked_objects::Location& from_here,
  82       const base::Callback<TaskReturnType(void)>& task,
  83       const base::Callback<void(ReplyArgType)>& reply) {
  84     TaskReturnType* result = new TaskReturnType();
  85     return PostTaskAndReply(
  86         task_runner,
  87         from_here,
  88         base::Bind(&base::internal::ReturnAsParamAdapter<TaskReturnType>,
  89                    task,
  90                    base::Unretained(result)),
  91         base::Bind(&base::internal::ReplyAdapter<TaskReturnType, ReplyArgType>,
  92                    reply,
  93                    base::Owned(result)));
  94   }
  95
  96   // Creates a tracked TaskId and an associated IsCanceledCallback. Client can
  97   // later call TryCancel() with the returned TaskId, and run |is_canceled_cb|
  98   // from any thread to check whether the TaskId is canceled.
  99   //
 100   // The returned task ID is tracked until the last copy of
 101   // |is_canceled_cb| is destroyed.
 102   //
 103   // Note. This function is used to address some special cancelation requirement
 104   // in existing code. You SHOULD NOT need this function in new code.
 105   TaskId NewTrackedTaskId(IsCanceledCallback* is_canceled_cb);
 106
 107   // After calling this function, |task| and |reply| will not run. If the
 108   // cancelation happens when |task| is running or has finished running, |reply|
 109   // will not run. If |reply| is running or has finished running, cancellation
 110   // is a noop.
 111   //
 112   // Note. It's OK to cancel a |task| for more than once. The later calls are
 113   // noops.
 114   void TryCancel(TaskId id);
 115
 116   // It's OK to call this function for more than once. The later calls are
 117   // noops.
 118   void TryCancelAll();
 119
 120   // Returns true iff there are in-flight tasks that are still being
 121   // tracked.
 122   bool HasTrackedTasks() const;
 123
 124  private:
 125   void Track(TaskId id, base::CancellationFlag* flag);
 126   void Untrack(TaskId id);
 127
 128   base::hash_map<TaskId, base::CancellationFlag*> task_flags_;
 129   base::WeakPtrFactory<CancelableTaskTracker> weak_factory_;
 130
 131   TaskId next_id_;
 132   base::ThreadChecker thread_checker_;
 133
 134   DISALLOW_COPY_AND_ASSIGN(CancelableTaskTracker);
 135 };
 136
 137 }  // namespace base
 138
 139 #endif  // BASE_TASK_CANCELABLE_TASK_TRACKER_H_