Make new TaskRunner, SequencedTaskRunner, and SingleThreadTaskRunner interfaces

base/sequenced_task_runner.h

+// 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 / derived class instead of
extension.

[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 somewhere early on for people who
don't want/need to read the rules below. Something like,

Barring delayed/non-nestable-tasks, tasks will execute one by one in FIFO order.

[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, right?

[akalin, 2012/02/10 22:48:59]

Well, are there cases where we care about the ordering of tasks posted from
different threads?  I can't think of one, and talking about it would mandate
implementations to essentially have a shared queue, which I don't think is
really necessary.

[willchan no longer on Chromium, 2012/02/14 05:59:07]

I need to reflect on this further. What happens in the case where you have
thread 1 where the SequenecedTaskRunner is actually running (in the single
threaded task runner case). You have threads 2 and 3. Thread 2 posts task A to
the SequencedTaskRunner (thread 1), then posts task B to thread 3, which posts
task C to the SequencedTaskRunner.

We need to guarantee that task A will execute on SequencedTaskRunner before task
C. This is important.

+//     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 concise wording. I'm fine as is. It
is imprecise because "delay" is imprecise, it's actually the post time + delay
time that matters, not just the absolute value of the delay. I'm being pedantic
again by nitting here. Feel free to ignore me.

[akalin, 2012/02/10 22:48:59]

It's not imprecise, if you assume they're posted from the same thread and T2 is
posted after T1 (which implies that T1's post time < T2's post time).

+//       * 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 style guide.

[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_