Home | History | Annotate | Download | only in task 
      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 
    130   TaskId next_id_;
    131   base::ThreadChecker thread_checker_;
    132 
    133   base::WeakPtrFactory<CancelableTaskTracker> weak_factory_;
    134 
    135   DISALLOW_COPY_AND_ASSIGN(CancelableTaskTracker);
    136 };
    137 
    138 }  // namespace base
    139 
    140 #endif  // BASE_TASK_CANCELABLE_TASK_TRACKER_H_
    141