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
49namespace tracked_objects {
50class Location;
51}  // namespace tracked_objects
52
53namespace base {
54
55class CancellationFlag;
56class TaskRunner;
57
58class 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>
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