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 <stdint.h>
40 
41 #include "base/base_export.h"
42 #include "base/callback.h"
43 #include "base/containers/hash_tables.h"
44 #include "base/macros.h"
45 #include "base/memory/weak_ptr.h"
46 #include "base/task_runner_util.h"
47 #include "base/threading/thread_checker.h"
48 
49 namespace tracked_objects {
50 class Location;
51 }  // namespace tracked_objects
52 
53 namespace base {
54 
55 class CancellationFlag;
56 class TaskRunner;
57 
58 class BASE_EXPORT CancelableTaskTracker {
59  public:
60   // All values except kBadTaskId are valid.
61   typedef int64_t TaskId;
62   static const TaskId kBadTaskId;
63 
64   typedef base::Callback<bool()> IsCanceledCallback;
65 
66   CancelableTaskTracker();
67 
68   // Cancels all tracked tasks.
69   ~CancelableTaskTracker();
70 
71   TaskId PostTask(base::TaskRunner* task_runner,
72                   const tracked_objects::Location& from_here,
73                   const base::Closure& task);
74 
75   TaskId PostTaskAndReply(base::TaskRunner* task_runner,
76                           const tracked_objects::Location& from_here,
77                           const base::Closure& task,
78                           const base::Closure& reply);
79 
80   template <typename TaskReturnType, typename ReplyArgType>
PostTaskAndReplyWithResult(base::TaskRunner * task_runner,const tracked_objects::Location & from_here,const base::Callback<TaskReturnType (void)> & task,const base::Callback<void (ReplyArgType)> & reply)81   TaskId PostTaskAndReplyWithResult(
82       base::TaskRunner* task_runner,
83       const tracked_objects::Location& from_here,
84       const base::Callback<TaskReturnType(void)>& task,
85       const base::Callback<void(ReplyArgType)>& reply) {
86     TaskReturnType* result = new TaskReturnType();
87     return PostTaskAndReply(
88         task_runner,
89         from_here,
90         base::Bind(&base::internal::ReturnAsParamAdapter<TaskReturnType>,
91                    task,
92                    base::Unretained(result)),
93         base::Bind(&base::internal::ReplyAdapter<TaskReturnType, ReplyArgType>,
94                    reply,
95                    base::Owned(result)));
96   }
97 
98   // Creates a tracked TaskId and an associated IsCanceledCallback. Client can
99   // later call TryCancel() with the returned TaskId, and run |is_canceled_cb|
100   // from any thread to check whether the TaskId is canceled.
101   //
102   // The returned task ID is tracked until the last copy of
103   // |is_canceled_cb| is destroyed.
104   //
105   // Note. This function is used to address some special cancelation requirement
106   // in existing code. You SHOULD NOT need this function in new code.
107   TaskId NewTrackedTaskId(IsCanceledCallback* is_canceled_cb);
108 
109   // After calling this function, |task| and |reply| will not run. If the
110   // cancelation happens when |task| is running or has finished running, |reply|
111   // will not run. If |reply| is running or has finished running, cancellation
112   // is a noop.
113   //
114   // Note. It's OK to cancel a |task| for more than once. The later calls are
115   // noops.
116   void TryCancel(TaskId id);
117 
118   // It's OK to call this function for more than once. The later calls are
119   // noops.
120   void TryCancelAll();
121 
122   // Returns true iff there are in-flight tasks that are still being
123   // tracked.
124   bool HasTrackedTasks() const;
125 
126  private:
127   void Track(TaskId id, base::CancellationFlag* flag);
128   void Untrack(TaskId id);
129 
130   base::hash_map<TaskId, base::CancellationFlag*> task_flags_;
131 
132   TaskId next_id_;
133   base::ThreadChecker thread_checker_;
134 
135   base::WeakPtrFactory<CancelableTaskTracker> weak_factory_;
136 
137   DISALLOW_COPY_AND_ASSIGN(CancelableTaskTracker);
138 };
139 
140 }  // namespace base
141 
142 #endif  // BASE_TASK_CANCELABLE_TASK_TRACKER_H_
143