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
15namespace 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.
99class 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>
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>
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.
135 //
136 // ReleaseSoon makes sure that the object it the scoped_refptr points to gets
137 // properly released on the correct thread.
138 // We apply ReleaseSoon to the rvalue as the side-effects can be unclear to
139 // the caller if an lvalue is used. That being so, the scoped_refptr should
140 // always be std::move'd.
141 // Example use:
142 //
143 // scoped_refptr<T> foo_scoped_refptr;
144 // ...
145 // task_runner->ReleaseSoon(std::move(foo_scoped_refptr));
146 template <class T>
147 void ReleaseSoon(const Location& from_here, scoped_refptr<T>&& object) {
148 if (!object)
149 return;
150
151 DeleteOrReleaseSoonInternal(from_here, &ReleaseHelper<T>::DoRelease,
152 object.release());
153 }
154
155 protected:
156 ~SequencedTaskRunner() override = default;
157
158 private:
159 bool DeleteOrReleaseSoonInternal(const Location& from_here,
160 void (*deleter)(const void*),
161 const void* object);
162};
163
164// Sample usage with std::unique_ptr :
165// std::unique_ptr<Foo, base::OnTaskRunnerDeleter> ptr(
166// new Foo, base::OnTaskRunnerDeleter(my_task_runner));
167//
168// For RefCounted see base::RefCountedDeleteOnSequence.
169struct BASE_EXPORT OnTaskRunnerDeleter {
170 explicit OnTaskRunnerDeleter(scoped_refptr<SequencedTaskRunner> task_runner);
171 ~OnTaskRunnerDeleter();
172
173 OnTaskRunnerDeleter(OnTaskRunnerDeleter&&);
174 OnTaskRunnerDeleter& operator=(OnTaskRunnerDeleter&&);
175
176 // For compatibility with std:: deleters.
177 template <typename T>
178 void operator()(const T* ptr) {
179 if (ptr)
180 task_runner_->DeleteSoon(FROM_HERE, ptr);
181 }
182
183 scoped_refptr<SequencedTaskRunner> task_runner_;
184};
185
186} // namespace base
187
188#endif // BASE_SEQUENCED_TASK_RUNNER_H_
189