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