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