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. (This is implied by the definition of "non-nestable";
+//     see comment above PostNonNestable*Task.)
+//
+//   - Increasing the delay can only delay execution of the task.

[darin (slow to review), 2012/01/31 07:11:48]

what does this mean?

[akalin, 2012/01/31 23:57:29]

If you increase the delay, it can either do nothing, or make the task run later
than it normally would, but not make it run earlier.  Added these details into
the comments.

+//
+// 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 possible implementations of Executor:
+//

[darin (slow to review), 2012/01/31 07:11:48]

you don't want to mention the simplest form of executor?  the message loop?

[akalin, 2012/01/31 23:57:29]

I'm a bit hesitant to do that, because people may assume that Executor ==
MessageLoop, when it's not (since ML is single threaded, etc.)  However, added
the Message Loop example to SingleThreadedExecutor.

+//   - An Executor that uses a worker pool to run submitted tasks.
+//
+//   - An Executor that, for each task, spawns a non-joinable thread to

[darin (slow to review), 2012/01/31 07:11:48]

Hmm... such an implementation carries with it the risk that the task may run
_after_ AtExitManager has already destroyed stuff.  We don't generally use
non-joinable threads in Chromium (except for calling getaddrinfo because it can
hang).

[akalin, 2012/01/31 23:57:29]

These are just theoretical implementations for clients to get an idea of what
can be a 'valid' Executor.  Changed 'possible' to 'theoretical'.

+//     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:
+  // 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,
+                               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 IsCompatibleWithCurrentThread() const = 0;

[darin (slow to review), 2012/01/31 07:11:48]

Compatible is such a vague term.  It somehow keeps bugging me.  Maybe a more
explicit "MayRunTasksOnCurrentThread" would work better?

[akalin, 2012/01/31 23:57:29]

Done.

+
+  // Posts |task| on the current Executor.  On completion, |reply| is
+  // 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;
+
+  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_