OLD | NEW |
---|---|
(Empty) | |
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_TASKRUNNER_H_ | |
6 #define BASE_SEQUENCED_TASKRUNNER_H_ | |
7 #pragma once | |
8 | |
9 #include "base/base_export.h" | |
10 #include "base/sequenced_task_runner_helpers.h" | |
11 #include "base/task_runner.h" | |
12 | |
13 namespace base { | |
14 | |
15 // A SequencedTaskRunner is an extension of TaskRunner that provides | |
willchan no longer on Chromium
2012/02/09 20:50:50
Sorry to be pedantic, but let's use subclass / der
akalin
2012/02/10 22:48:59
Done.
| |
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 // SequencedTaskRunner also adds additional methods for posting | |
21 // non-nestable tasks. In general, an implementation of TaskRunner | |
22 // may expose task-running methods which are themselves callable from | |
23 // within tasks. A non-nestable task is one that is guaranteed to not | |
24 // be run from within an already-running task. Conversely, a nestable | |
25 // task (the default) is a task that can be run from within an | |
26 // already-running task. | |
willchan no longer on Chromium
2012/02/09 20:50:50
Please add a rough oversimplified explanation some
akalin
2012/02/10 22:48:59
Done.
| |
27 // | |
28 // The guarantees of SequencedTaskRunner are as follows: | |
29 // | |
30 // - Given two tasks T2 and T1 that are posted from the same thread, | |
willchan no longer on Chromium
2012/02/09 20:50:50
They don't have to be posted from the same thread,
akalin
2012/02/10 22:48:59
Well, are there cases where we care about the orde
willchan no longer on Chromium
2012/02/14 05:59:07
I need to reflect on this further. What happens in
| |
31 // T2 will start after T1 starts if: | |
32 // | |
33 // * T2 is posted after T1; | |
34 // * T2 has equal or higher delay than T1; and | |
willchan no longer on Chromium
2012/02/09 20:50:50
This is imprecise, but I don't have a better conci
akalin
2012/02/10 22:48:59
It's not imprecise, if you assume they're posted f
| |
35 // * T2 is non-nestable or T1 is nestable. | |
36 // | |
37 // - If T2 will start after T1 starts by the above guarantee, then | |
38 // T2 will start after T1 finishes if: | |
39 // | |
40 // * T2 is non-nestable, or | |
41 // * T1 doesn't call any task-running methods of S. | |
willchan no longer on Chromium
2012/02/09 20:50:50
S has not been defined
akalin
2012/02/10 22:48:59
Fixed.
| |
42 // | |
43 // - If T2 will start after T1 finishes by the above guarantee, then | |
44 // all memory changes in T1 will be visible to T2. | |
45 // | |
46 // - If T2 runs nested within T1 via a call to the task-running | |
47 // method M, then all memory changes in T1 up to the call to M | |
48 // will be visible to T2, and all memory changes in T2 will be | |
49 // visible to T1 from the return from M. | |
50 // | |
51 // Note that SequencedTaskRunner does not guarantee execution on a | |
52 // single dedicated thread, although the above guarantees provide most | |
53 // (but not all) of the same guarantees. If you do need to guarantee | |
54 // that tasks are run on a single dedicated thread, see | |
55 // SingleThreadTaskRunner (in single_thread_task_runner.h). | |
56 // | |
57 // Some corollaries to the above guarantees, assuming the tasks in | |
58 // question don't call any task-running methods: | |
59 // | |
60 // - Tasks submitted via PostTask are run in FIFO order. | |
61 // | |
62 // - Tasks submitted via PostNonNestableTask are run in FIFO order. | |
63 // | |
64 // - Tasks submitted with the same delay and the same nestable state | |
65 // are run in FIFO order. | |
66 // | |
67 // - A list of tasks with the same nestable state submitted in order | |
68 // of non-decreasing delay is run in FIFO order. | |
69 // | |
70 // - A list of tasks submitted in order of non-decreasing delay with | |
71 // at most a single change in nestable state from nestable to | |
72 // non-nestable is run in FIFO order. (This is equivalent to | |
73 // the statement of the first guarantee above.) | |
74 // | |
75 // Some theoretical implementations of SequencedTaskRunner: | |
76 // | |
77 // - A SequencedTaskRunner that wraps a regular TaskRunner but makes | |
78 // sure that only one task at a time is posted to the TaskRunner, | |
79 // with appropriate memory barriers in between tasks. | |
80 // | |
81 // - A SequencedTaskRunner that, for each task, spawns a joinable | |
82 // thread to execute that task and immediately quit, and then | |
83 // immediately joins that thread. | |
84 // | |
85 // - A SequencedTaskRunner that stores the list of submitted tasks | |
86 // and has a method Run() that executes each runnable task in FIFO | |
87 // order that can be called from any thread, but only if another | |
88 // (non-nested) Run() call isn't already happening. | |
89 class BASE_EXPORT SequencedTaskRunner : public TaskRunner { | |
90 public: | |
willchan no longer on Chromium
2012/02/09 20:50:50
Shift 1 column, ditch the extra newline as per sty
akalin
2012/02/10 22:48:59
Done.
| |
91 | |
92 // The two PostNonNestable*Task methods below are like their | |
93 // nestable equivalents in TaskRunner, but they guarantee that the | |
94 // submitted task will not execute nested within an | |
95 // already-executing task. | |
96 // | |
97 // A simple corollary is that submitting a task as non-nestable can | |
98 // only delay execution of the task. That is, submitting a task as | |
99 // non-nestable may not affect when the task gets executed, or it | |
100 // could make it run later than it normally would, but it won't make | |
101 // it run earlier than it normally would. | |
102 | |
103 // TODO(akalin): Get rid of the boolean return value for the methods | |
104 // below. | |
105 | |
106 // TODO(akalin): Consider forwarding this to | |
107 // PostNonNestableDelayedTask(_, _, 0). | |
108 virtual bool PostNonNestableTask(const tracked_objects::Location& from_here, | |
109 const Closure& task) = 0; | |
110 | |
111 virtual bool PostNonNestableDelayedTask( | |
112 const tracked_objects::Location& from_here, | |
113 const Closure& task, | |
114 int64 delay_ms) = 0; | |
115 | |
116 // Submits a non-nestable task to delete the given object. Returns | |
117 // true if the object may be deleted at some point in the future, | |
118 // and false if the object definitely will not be deleted. | |
119 template <class T> | |
120 bool DeleteSoon(const tracked_objects::Location& from_here, | |
121 const T* object) { | |
122 return | |
123 subtle::DeleteHelperInternal<T, bool>::DeleteViaSequencedTaskRunner( | |
124 this, from_here, object); | |
125 } | |
126 | |
127 // Submits a non-nestable task to release the given object. Returns | |
128 // true if the object may be released at some point in the future, | |
129 // and false if the object definitely will not be released. | |
130 template <class T> | |
131 bool ReleaseSoon(const tracked_objects::Location& from_here, | |
132 T* object) { | |
133 return | |
134 subtle::ReleaseHelperInternal<T, bool>::ReleaseViaSequencedTaskRunner( | |
135 this, from_here, object); | |
136 } | |
137 | |
138 private: | |
139 template <class T, class R> friend class subtle::DeleteHelperInternal; | |
140 template <class T, class R> friend class subtle::ReleaseHelperInternal; | |
141 | |
142 bool DeleteSoonInternal(const tracked_objects::Location& from_here, | |
143 void(*deleter)(const void*), | |
144 const void* object); | |
145 | |
146 bool ReleaseSoonInternal(const tracked_objects::Location& from_here, | |
147 void(*releaser)(const void*), | |
148 const void* object); | |
149 }; | |
150 | |
151 } // namespace base | |
152 | |
153 #endif // BASE_SEQUENCED_TASKRUNNER_H_ | |
OLD | NEW |