Run ImageLoaderTest.DeleteExtensionWhileWaitingForCache from memory tests.
[chromium-blink-merge.git] / base / sequenced_task_runner.h
blobf6ca64678185e83ae46170a0450fb906cabb7b8e
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.
5 #ifndef BASE_SEQUENCED_TASKRUNNER_H_
6 #define BASE_SEQUENCED_TASKRUNNER_H_
8 #include "base/base_export.h"
9 #include "base/sequenced_task_runner_helpers.h"
10 #include "base/task_runner.h"
12 namespace base {
14 // A SequencedTaskRunner is a subclass of TaskRunner that provides
15 // additional guarantees on the order that tasks are started, as well
16 // as guarantees on when tasks are in sequence, i.e. one task finishes
17 // before the other one starts.
19 // Summary
20 // -------
21 // Non-nested tasks with the same delay will run one by one in FIFO
22 // order.
24 // Detailed guarantees
25 // -------------------
27 // SequencedTaskRunner also adds additional methods for posting
28 // non-nestable tasks. In general, an implementation of TaskRunner
29 // may expose task-running methods which are themselves callable from
30 // within tasks. A non-nestable task is one that is guaranteed to not
31 // be run from within an already-running task. Conversely, a nestable
32 // task (the default) is a task that can be run from within an
33 // already-running task.
35 // The guarantees of SequencedTaskRunner are as follows:
37 // - Given two tasks T2 and T1, T2 will start after T1 starts if:
39 // * T2 is posted after T1; and
40 // * T2 has equal or higher delay than T1; and
41 // * T2 is non-nestable or T1 is nestable.
43 // - If T2 will start after T1 starts by the above guarantee, then
44 // T2 will start after T1 finishes and is destroyed if:
46 // * T2 is non-nestable, or
47 // * T1 doesn't call any task-running methods.
49 // - If T2 will start after T1 finishes by the above guarantee, then
50 // all memory changes in T1 and T1's destruction will be visible
51 // to T2.
53 // - If T2 runs nested within T1 via a call to the task-running
54 // method M, then all memory changes in T1 up to the call to M
55 // will be visible to T2, and all memory changes in T2 will be
56 // visible to T1 from the return from M.
58 // Note that SequencedTaskRunner does not guarantee that tasks are run
59 // on a single dedicated thread, although the above guarantees provide
60 // most (but not all) of the same guarantees. If you do need to
61 // guarantee that tasks are run on a single dedicated thread, see
62 // SingleThreadTaskRunner (in single_thread_task_runner.h).
64 // Some corollaries to the above guarantees, assuming the tasks in
65 // question don't call any task-running methods:
67 // - Tasks posted via PostTask are run in FIFO order.
69 // - Tasks posted via PostNonNestableTask are run in FIFO order.
71 // - Tasks posted with the same delay and the same nestable state
72 // are run in FIFO order.
74 // - A list of tasks with the same nestable state posted in order of
75 // non-decreasing delay is run in FIFO order.
77 // - A list of tasks posted in order of non-decreasing delay with at
78 // most a single change in nestable state from nestable to
79 // non-nestable is run in FIFO order. (This is equivalent to the
80 // statement of the first guarantee above.)
82 // Some theoretical implementations of SequencedTaskRunner:
84 // - A SequencedTaskRunner that wraps a regular TaskRunner but makes
85 // sure that only one task at a time is posted to the TaskRunner,
86 // with appropriate memory barriers in between tasks.
88 // - A SequencedTaskRunner that, for each task, spawns a joinable
89 // thread to run that task and immediately quit, and then
90 // immediately joins that thread.
92 // - A SequencedTaskRunner that stores the list of posted tasks and
93 // has a method Run() that runs each runnable task in FIFO order
94 // that can be called from any thread, but only if another
95 // (non-nested) Run() call isn't already happening.
96 class BASE_EXPORT SequencedTaskRunner : public TaskRunner {
97 public:
98 // The two PostNonNestable*Task methods below are like their
99 // nestable equivalents in TaskRunner, but they guarantee that the
100 // posted task will not run nested within an already-running task.
102 // A simple corollary is that posting a task as non-nestable can
103 // only delay when the task gets run. That is, posting a task as
104 // non-nestable may not affect when the task gets run, or it could
105 // make it run later than it normally would, but it won't make it
106 // run earlier than it normally would.
108 // TODO(akalin): Get rid of the boolean return value for the methods
109 // below.
111 bool PostNonNestableTask(const tracked_objects::Location& from_here,
112 const Closure& task);
114 virtual bool PostNonNestableDelayedTask(
115 const tracked_objects::Location& from_here,
116 const Closure& task,
117 base::TimeDelta delay) = 0;
119 // Submits a non-nestable task to delete the given object. Returns
120 // true if the object may be deleted at some point in the future,
121 // and false if the object definitely will not be deleted.
122 template <class T>
123 bool DeleteSoon(const tracked_objects::Location& from_here,
124 const T* object) {
125 return
126 subtle::DeleteHelperInternal<T, bool>::DeleteViaSequencedTaskRunner(
127 this, from_here, object);
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 T* object) {
136 return
137 subtle::ReleaseHelperInternal<T, bool>::ReleaseViaSequencedTaskRunner(
138 this, from_here, object);
141 protected:
142 virtual ~SequencedTaskRunner() {}
144 private:
145 template <class T, class R> friend class subtle::DeleteHelperInternal;
146 template <class T, class R> friend class subtle::ReleaseHelperInternal;
148 bool DeleteSoonInternal(const tracked_objects::Location& from_here,
149 void(*deleter)(const void*),
150 const void* object);
152 bool ReleaseSoonInternal(const tracked_objects::Location& from_here,
153 void(*releaser)(const void*),
154 const void* object);
157 } // namespace base
159 #endif // BASE_SEQUENCED_TASKRUNNER_H_