Index: base/sequenced_task_runner.h |
diff --git a/base/sequenced_task_runner.h b/base/sequenced_task_runner.h |
new file mode 100644 |
index 0000000000000000000000000000000000000000..4e4e837f7a302c568e88241c07f1a3bff1b8e76a |
--- /dev/null |
+++ b/base/sequenced_task_runner.h |
@@ -0,0 +1,153 @@ |
+// Copyright (c) 2012 The Chromium Authors. All rights reserved. |
+// Use of this source code is governed by a BSD-style license that can be |
+// found in the LICENSE file. |
+ |
+#ifndef BASE_SEQUENCED_TASKRUNNER_H_ |
+#define BASE_SEQUENCED_TASKRUNNER_H_ |
+#pragma once |
+ |
+#include "base/base_export.h" |
+#include "base/sequenced_task_runner_helpers.h" |
+#include "base/task_runner.h" |
+ |
+namespace base { |
+ |
+// 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.
|
+// additional guarantees on the order that tasks are started, as well |
+// as guarantees on when tasks are in sequence, i.e. one task finishes |
+// before the other one starts. |
+// |
+// SequencedTaskRunner also adds additional methods for posting |
+// non-nestable tasks. In general, an implementation of TaskRunner |
+// may expose task-running methods which are themselves callable from |
+// within tasks. A non-nestable task is one that is guaranteed to not |
+// be run from within an already-running task. Conversely, a nestable |
+// task (the default) is a task that can be run from within an |
+// 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.
|
+// |
+// The guarantees of SequencedTaskRunner are as follows: |
+// |
+// - 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
|
+// T2 will start after T1 starts if: |
+// |
+// * T2 is posted after T1; |
+// * 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
|
+// * T2 is non-nestable or T1 is nestable. |
+// |
+// - If T2 will start after T1 starts by the above guarantee, then |
+// T2 will start after T1 finishes if: |
+// |
+// * T2 is non-nestable, or |
+// * 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.
|
+// |
+// - If T2 will start after T1 finishes by the above guarantee, then |
+// all memory changes in T1 will be visible to T2. |
+// |
+// - If T2 runs nested within T1 via a call to the task-running |
+// method M, then all memory changes in T1 up to the call to M |
+// will be visible to T2, and all memory changes in T2 will be |
+// visible to T1 from the return from M. |
+// |
+// Note that SequencedTaskRunner does not guarantee execution on a |
+// single dedicated thread, although the above guarantees provide most |
+// (but not all) of the same guarantees. If you do need to guarantee |
+// that tasks are run on a single dedicated thread, see |
+// SingleThreadTaskRunner (in single_thread_task_runner.h). |
+// |
+// Some corollaries to the above guarantees, assuming the tasks in |
+// question don't call any task-running methods: |
+// |
+// - Tasks submitted via PostTask are run in FIFO order. |
+// |
+// - Tasks submitted via PostNonNestableTask are run in FIFO order. |
+// |
+// - Tasks submitted with the same delay and the same nestable state |
+// are run in FIFO order. |
+// |
+// - A list of tasks with the same nestable state submitted in order |
+// of non-decreasing delay is run in FIFO order. |
+// |
+// - A list of tasks submitted in order of non-decreasing delay with |
+// at most a single change in nestable state from nestable to |
+// non-nestable is run in FIFO order. (This is equivalent to |
+// the statement of the first guarantee above.) |
+// |
+// Some theoretical implementations of SequencedTaskRunner: |
+// |
+// - A SequencedTaskRunner that wraps a regular TaskRunner but makes |
+// sure that only one task at a time is posted to the TaskRunner, |
+// with appropriate memory barriers in between tasks. |
+// |
+// - A SequencedTaskRunner that, for each task, spawns a joinable |
+// thread to execute that task and immediately quit, and then |
+// immediately joins that thread. |
+// |
+// - A SequencedTaskRunner that stores the list of submitted tasks |
+// and has a method Run() that executes each runnable task in FIFO |
+// order that can be called from any thread, but only if another |
+// (non-nested) Run() call isn't already happening. |
+class BASE_EXPORT SequencedTaskRunner : public TaskRunner { |
+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.
|
+ |
+ // The two PostNonNestable*Task methods below are like their |
+ // nestable equivalents in TaskRunner, but they guarantee that the |
+ // submitted task will not execute nested within an |
+ // already-executing task. |
+ // |
+ // A simple corollary is that submitting a task as non-nestable can |
+ // only delay execution of the task. That is, submitting a task as |
+ // non-nestable may not affect when the task gets executed, or it |
+ // could make it run later than it normally would, but it won't make |
+ // it run earlier than it normally would. |
+ |
+ // TODO(akalin): Get rid of the boolean return value for the methods |
+ // below. |
+ |
+ // TODO(akalin): Consider forwarding this to |
+ // PostNonNestableDelayedTask(_, _, 0). |
+ virtual bool PostNonNestableTask(const tracked_objects::Location& from_here, |
+ const Closure& task) = 0; |
+ |
+ virtual bool PostNonNestableDelayedTask( |
+ const tracked_objects::Location& from_here, |
+ const Closure& task, |
+ int64 delay_ms) = 0; |
+ |
+ // Submits a non-nestable task to delete the given object. Returns |
+ // true if the object may be deleted at some point in the future, |
+ // and false if the object definitely will not be deleted. |
+ template <class T> |
+ bool DeleteSoon(const tracked_objects::Location& from_here, |
+ const T* object) { |
+ return |
+ subtle::DeleteHelperInternal<T, bool>::DeleteViaSequencedTaskRunner( |
+ this, from_here, object); |
+ } |
+ |
+ // Submits a non-nestable task to release the given object. Returns |
+ // true if the object may be released at some point in the future, |
+ // and false if the object definitely will not be released. |
+ template <class T> |
+ bool ReleaseSoon(const tracked_objects::Location& from_here, |
+ T* object) { |
+ return |
+ subtle::ReleaseHelperInternal<T, bool>::ReleaseViaSequencedTaskRunner( |
+ this, from_here, object); |
+ } |
+ |
+private: |
+ template <class T, class R> friend class subtle::DeleteHelperInternal; |
+ template <class T, class R> friend class subtle::ReleaseHelperInternal; |
+ |
+ bool DeleteSoonInternal(const tracked_objects::Location& from_here, |
+ void(*deleter)(const void*), |
+ const void* object); |
+ |
+ bool ReleaseSoonInternal(const tracked_objects::Location& from_here, |
+ void(*releaser)(const void*), |
+ const void* object); |
+}; |
+ |
+} // namespace base |
+ |
+#endif // BASE_SEQUENCED_TASKRUNNER_H_ |