Make new TaskRunner, SequencedTaskRunner, and SingleThreadTaskRunner interfaces

base/executor.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_EXECUTOR_H_
+#define BASE_EXECUTOR_H_
+#pragma once
+
+#include "base/base_export.h"
+#include "base/basictypes.h"
+#include "base/callback_forward.h"
+#include "base/executor_helpers.h"
+#include "base/memory/ref_counted.h"
+
+namespace tracked_objects {
+class Location;
+} // namespace tracked_objects
+
+namespace base {
+
+struct ExecutorTraits;
+
+// An Executor is an object that executes submitted tasks (in the form
+// of Closure objects).  The Executor interface provides a way of
+// decoupling task submission from the mechanics of how each task will
+// be run.  Executor provides very weak guarantees as to how submitted
+// tasks are run (or if they're run at all).  In particular, it only
+// guarantees:
+//
+//   - Submitting a task will not run it synchronously.  That is, no
+//     Post*Task method will call task.Run() directly.
+//
+//   - 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.  (This is implied by the definition of
+//     "non-nestable"; see comment above PostNonNestable*Task.)
+//
+//   - Increasing the delay can only delay execution of the task.
+//     That is, increasing the delay 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.
+//
+// Executor does not guarantee the order in which submitted tasks are
+// run or whether they're run on a particular thread.  Also it does
+// not guarantee a memory model for shared data between tasks.  (In
+// other words, you should use your own synchronization/locking
+// primitives if you need to share data between tasks.)
+//
+// Implementations of Executor should be thread-safe in that all
+// methods must be safe to call on any thread.  Ownership semantics
+// for Executors are in general not clear, which is why the interface
+// itself is RefCountedThreadSafe.
+//
+// Some theoretical implementations of Executor:
+//
+//   - An Executor that uses a worker pool to run submitted tasks.
+//
+//   - An Executor that, for each task, spawns a non-joinable thread to
+//     execute that task and immediately quit.
+//
+//   - An Executor that stores the list of submitted tasks and has a
+//     method Run() that executes each runnable task in random order.
+class BASE_EXPORT Executor
+    : public RefCountedThreadSafe<Executor, ExecutorTraits> {
+ public:
+  // TODO(akalin): Get rid of the boolean return value for the
+  // Post*Task methods.
+
+  // Submits the given task for execution.  Returns true if the task
+  // may be executed at some point in the future, and false if the
+  // task definitely will not be executed.
+  virtual bool PostTask(const tracked_objects::Location& from_here,
+                        const Closure& task) = 0;
+
+  // TODO(akalin): Make Post*DelayedTask use TimeDelta instead.
+
+  // Like PostTask, but tries to run the submitted task only after
+  // |delay_ms| has passed.  PostDelayedTask with zero delay should be
+  // equivalent to PostTask.
+  //
+  // It is valid for an implementation to ignore |delay_ms|; that is,
+  // to have PostDelayedTask behave the same as PostTask.
+  virtual bool PostDelayedTask(const tracked_objects::Location& from_here,

[willchan no longer on Chromium, 2012/02/01 10:34:11]

Why are all these other PostTask() variants in here? WorkerPool and
SequencedWorkerPool do not use them. Do they not belong in SerialExecutor
instead?

Now that I say that though, it's interesting to imagine what an Executor shim in
front of SequencedWorkerPool would look like. My initial thoughts were that, if
you grabbed a SequenceToken from SequencedWorkerPool, then you could hold that
and the SequencedWorkerPool pointer within a Executor shim, that probably should
be a SerialExecutor actually to imply the FIFO ordering. Yet, it's not clear to
me that we would want these other PostTask() variants implemented in that
SerialExecutor shim class. I need to think a bit more about this, but perhaps
others have thoughts here.

+                               const Closure& task,
+                               int64 delay_ms) = 0;
+
+  // The two methods below are like the two methods above, but they
+  // guarantee that the submitted task will not execute nested within
+  // an already-executing task.
+
+  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;
+
+  // Returns true if the current thread is a thread on which a task
+  // may be executed, and false if no task will be executed on the
+  // current thread.
+  //
+  // It is valid for an implementation to always return true, or in
+  // general to use 'true' as a default value.
+  virtual bool MayRunTasksOnCurrentThread() const = 0;

[willchan no longer on Chromium, 2012/02/01 10:34:11]

I need to think this member over some more. I think this is the replacement for
BelongsToCurrentThread(), yes? "May" sounds very vague here. Anyway, I'll come
back to this later.

+
+  // Posts |task| on the current Executor.  On completion, |reply| is

[willchan no longer on Chromium, 2012/02/01 10:34:11]

Is this comment accurate? "current" is misleading since it may be read as the
current thread. It's really the target Executor, more accurately called |this|.

Also a lot of the terminology here assumes individual threads. What if the
executor you're currently running on is the WorkerPool? It's wrong to say that
|reply| will run on the same thread. Of course, it may be weird to call
PostTaskAndReply() from WorkerPool, since the current implementation relies on
MessageLoop::current() to return a valid MessageLoop. I need to think a bit
later on about whether or not we need a Executor::current() thing.

+  // posted to the thread that called PostTaskAndReply().  Both |task|
+  // and |reply| are guaranteed to be deleted on the thread from which
+  // PostTaskAndReply() is invoked.  This allows objects that must be
+  // deleted on the originating thread to be bound into the |task| and
+  // |reply| Closures.  In particular, it can be useful to use
+  // WeakPtr<> in the |reply| Closure so that the reply operation can
+  // be canceled. See the following pseudo-code:
+  //
+  // class DataBuffer : public RefCountedThreadSafe<DataBuffer> {
+  //  public:
+  //   // Called to add data into a buffer.
+  //   void AddData(void* buf, size_t length);
+  //   ...
+  // };
+  //
+  //
+  // class DataLoader : public SupportsWeakPtr<DataLoader> {
+  //  public:
+  //    void GetData() {
+  //      scoped_refptr<DataBuffer> buffer = new DataBuffer();
+  //      target_thread_.message_loop_proxy()->PostTaskAndReply(
+  //          FROM_HERE,
+  //          base::Bind(&DataBuffer::AddData, buffer),
+  //          base::Bind(&DataLoader::OnDataReceived, AsWeakPtr(), buffer));
+  //    }
+  //
+  //  private:
+  //    void OnDataReceived(scoped_refptr<DataBuffer> buffer) {
+  //      // Do something with buffer.
+  //    }
+  // };
+  //
+  //
+  // Things to notice:
+  //   * Results of |task| are shared with |reply| by binding a shared argument
+  //     (a DataBuffer instance).
+  //   * The DataLoader object has no special thread safety.
+  //   * The DataLoader object can be deleted while |task| is still running,
+  //     and the reply will cancel itself safely because it is bound to a
+  //     WeakPtr<>.
+  bool PostTaskAndReply(const tracked_objects::Location& from_here,
+                        const Closure& task,
+                        const Closure& reply);
+
+  // 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>::DeleteViaExecutor(
+        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>::ReleaseViaExecutor(
+        this, from_here, object);
+  }
+
+ protected:
+  friend struct ExecutorTraits;
+
+  // Only the Windows debug build seems to need this: see
+  // http://crbug.com/112250.
+  friend class RefCountedThreadSafe<Executor, ExecutorTraits>;
+
+  Executor();
+  virtual ~Executor();
+
+  // Called when this object should be destroyed.  By default simply
+  // deletes |this|, but can be overridden to do something else, like
+  // delete on a certain thread.
+  virtual void OnDestruct() const;
+
+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);
+};
+
+struct BASE_EXPORT ExecutorTraits {
+  static void Destruct(const Executor* executor);
+};
+
+}  // namespace base
+
+#endif  // BASE_EXECUTOR_H_