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 #ifndef BASE_SEQUENCED_TASK_RUNNER_H_ 6 #define BASE_SEQUENCED_TASK_RUNNER_H_ 7 8 #include "base/base_export.h" 9 #include "base/callback.h" 10 #include "base/sequenced_task_runner_helpers.h" 11 #include "base/task_runner.h" 12 13 namespace base { 14 15 // A SequencedTaskRunner is a subclass of TaskRunner that provides 16 // additional guarantees on the order that tasks are started, as well 17 // as guarantees on when tasks are in sequence, i.e. one task finishes 18 // before the other one starts. 19 // 20 // Summary 21 // ------- 22 // Non-nested tasks with the same delay will run one by one in FIFO 23 // order. 24 // 25 // Detailed guarantees 26 // ------------------- 27 // 28 // SequencedTaskRunner also adds additional methods for posting 29 // non-nestable tasks. In general, an implementation of TaskRunner 30 // may expose task-running methods which are themselves callable from 31 // within tasks. A non-nestable task is one that is guaranteed to not 32 // be run from within an already-running task. Conversely, a nestable 33 // task (the default) is a task that can be run from within an 34 // already-running task. 35 // 36 // The guarantees of SequencedTaskRunner are as follows: 37 // 38 // - Given two tasks T2 and T1, T2 will start after T1 starts if: 39 // 40 // * T2 is posted after T1; and 41 // * T2 has equal or higher delay than T1; and 42 // * T2 is non-nestable or T1 is nestable. 43 // 44 // - If T2 will start after T1 starts by the above guarantee, then 45 // T2 will start after T1 finishes and is destroyed if: 46 // 47 // * T2 is non-nestable, or 48 // * T1 doesn't call any task-running methods. 49 // 50 // - If T2 will start after T1 finishes by the above guarantee, then 51 // all memory changes in T1 and T1's destruction will be visible 52 // to T2. 53 // 54 // - If T2 runs nested within T1 via a call to the task-running 55 // method M, then all memory changes in T1 up to the call to M 56 // will be visible to T2, and all memory changes in T2 will be 57 // visible to T1 from the return from M. 58 // 59 // Note that SequencedTaskRunner does not guarantee that tasks are run 60 // on a single dedicated thread, although the above guarantees provide 61 // most (but not all) of the same guarantees. If you do need to 62 // guarantee that tasks are run on a single dedicated thread, see 63 // SingleThreadTaskRunner (in single_thread_task_runner.h). 64 // 65 // Some corollaries to the above guarantees, assuming the tasks in 66 // question don't call any task-running methods: 67 // 68 // - Tasks posted via PostTask are run in FIFO order. 69 // 70 // - Tasks posted via PostNonNestableTask are run in FIFO order. 71 // 72 // - Tasks posted with the same delay and the same nestable state 73 // are run in FIFO order. 74 // 75 // - A list of tasks with the same nestable state posted in order of 76 // non-decreasing delay is run in FIFO order. 77 // 78 // - A list of tasks posted in order of non-decreasing delay with at 79 // most a single change in nestable state from nestable to 80 // non-nestable is run in FIFO order. (This is equivalent to the 81 // statement of the first guarantee above.) 82 // 83 // Some theoretical implementations of SequencedTaskRunner: 84 // 85 // - A SequencedTaskRunner that wraps a regular TaskRunner but makes 86 // sure that only one task at a time is posted to the TaskRunner, 87 // with appropriate memory barriers in between tasks. 88 // 89 // - A SequencedTaskRunner that, for each task, spawns a joinable 90 // thread to run that task and immediately quit, and then 91 // immediately joins that thread. 92 // 93 // - A SequencedTaskRunner that stores the list of posted tasks and 94 // has a method Run() that runs each runnable task in FIFO order 95 // that can be called from any thread, but only if another 96 // (non-nested) Run() call isn't already happening. 97 class BASE_EXPORT SequencedTaskRunner : public TaskRunner { 98 public: 99 // The two PostNonNestable*Task methods below are like their 100 // nestable equivalents in TaskRunner, but they guarantee that the 101 // posted task will not run nested within an already-running task. 102 // 103 // A simple corollary is that posting a task as non-nestable can 104 // only delay when the task gets run. That is, posting a task as 105 // non-nestable may not affect when the task gets run, or it could 106 // make it run later than it normally would, but it won't make it 107 // run earlier than it normally would. 108 109 // TODO(akalin): Get rid of the boolean return value for the methods 110 // below. 111 112 bool PostNonNestableTask(const tracked_objects::Location& from_here, 113 OnceClosure task); 114 115 virtual bool PostNonNestableDelayedTask( 116 const tracked_objects::Location& from_here, 117 OnceClosure task, 118 base::TimeDelta delay) = 0; 119 120 // Submits a non-nestable task to delete the given object. Returns 121 // true if the object may be deleted at some point in the future, 122 // and false if the object definitely will not be deleted. 123 template <class T> 124 bool DeleteSoon(const tracked_objects::Location& from_here, 125 const T* object) { 126 return DeleteOrReleaseSoonInternal(from_here, &DeleteHelper<T>::DoDelete, 127 object); 128 } 129 130 // Submits a non-nestable task to release the given object. Returns 131 // true if the object may be released at some point in the future, 132 // and false if the object definitely will not be released. 133 template <class T> 134 bool ReleaseSoon(const tracked_objects::Location& from_here, 135 const T* object) { 136 return DeleteOrReleaseSoonInternal(from_here, &ReleaseHelper<T>::DoRelease, 137 object); 138 } 139 140 protected: 141 ~SequencedTaskRunner() override {} 142 143 private: 144 bool DeleteOrReleaseSoonInternal(const tracked_objects::Location& from_here, 145 void (*deleter)(const void*), 146 const void* object); 147 }; 148 149 struct BASE_EXPORT OnTaskRunnerDeleter { 150 explicit OnTaskRunnerDeleter(scoped_refptr<SequencedTaskRunner> task_runner); 151 ~OnTaskRunnerDeleter(); 152 153 OnTaskRunnerDeleter(OnTaskRunnerDeleter&&); 154 OnTaskRunnerDeleter& operator=(OnTaskRunnerDeleter&&); 155 156 template <typename T> 157 void operator()(const T* ptr) { 158 if (ptr) 159 task_runner_->DeleteSoon(FROM_HERE, ptr); 160 } 161 162 scoped_refptr<SequencedTaskRunner> task_runner_; 163 }; 164 165 } // namespace base 166 167 #endif // BASE_SEQUENCED_TASK_RUNNER_H_ 168
