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