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_MESSAGE_LOOP_PROXY_H_
-#define BASE_MESSAGE_LOOP_PROXY_H_
+#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"
-#include "base/message_loop_helpers.h"
 
 namespace tracked_objects {
 class Location;
 } // namespace tracked_objects
 
 namespace base {
 
-struct MessageLoopProxyTraits;
+struct ExecutorTraits;
 
-// This class provides a thread-safe refcounted interface to the Post* methods
-// of a message loop. This class can outlive the target message loop.
-// MessageLoopProxy objects are constructed automatically for all MessageLoops.
-// So, to access them, you can use any of the following:
-//   Thread::message_loop_proxy()
-//   MessageLoop::current()->message_loop_proxy()
-//   MessageLoopProxy::current()
-class BASE_EXPORT MessageLoopProxy
-    : public base::RefCountedThreadSafe<MessageLoopProxy,
-                                        MessageLoopProxyTraits> {
+// 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 no guarantees as to how submitted tasks
+// are run (or if they're run at all), and in particular the order in
+// which the tasks are run and whether they're run on a particular
+// thread.
+//
+// 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.
+class BASE_EXPORT Executor
+    : public RefCountedThreadSafe<Executor, ExecutorTraits> {
  public:
-  // These methods are the same as in message_loop.h, but are guaranteed to
-  // either post the Task to the MessageLoop (if it's still alive), or the task
-  // is discarded.
-  // They return true iff the thread existed and the task was posted.  Note that
-  // even if the task is posted, there's no guarantee that it will run; for
-  // example the target loop may already be quitting, or in the case of a
-  // delayed task a Quit message may preempt it in the message loop queue.
-  // Conversely, a return value of false is a guarantee the task will not run.
+  // Submits the given task for execution.  Returns true if the task
+  // may be executed immediately or 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 base::Closure& task) = 0;
+                        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.
   virtual bool PostDelayedTask(const tracked_objects::Location& from_here,
-                               const base::Closure& task,
+                               const Closure& task,
                                int64 delay_ms) = 0;
+
+  // Like PostTask, but guarantees that the submitted task will not
+  // execute nested within an already-executing task.
   virtual bool PostNonNestableTask(const tracked_objects::Location& from_here,
-                                   const base::Closure& task) = 0;
+                                   const Closure& task) = 0;
+
+  // Like PostNonNestableTask, but tries to run the submitted task
+  // only after |delay_ms| has passed.
   virtual bool PostNonNestableDelayedTask(
       const tracked_objects::Location& from_here,
-      const base::Closure& task,
+      const Closure& task,
       int64 delay_ms) = 0;
 
-  // A method which checks if the caller is currently running in the thread that
-  // this proxy represents.
-  virtual bool BelongsToCurrentThread() = 0;
-
-  // Executes |task| on the given MessageLoopProxy.  On completion, |reply|
-  // is passed back to the MessageLoopProxy for 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:
+  // 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> {
@@ skipping 17 matching lines @@
   //   * 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 task to delete the given object.  Returns true if the
+  // object may be deleted immediately or 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>::DeleteOnMessageLoop(
+    return subtle::DeleteHelperInternal<T, bool>::DeleteOnExecutor(
         this, from_here, object);
   }
+
+  // Submits a task to release the given object.  Returns true if the
+  // object may be released immediately or 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>::ReleaseOnMessageLoop(
+    return subtle::ReleaseHelperInternal<T, bool>::ReleaseOnExecutor(
         this, from_here, object);
   }
 
-  // Gets the MessageLoopProxy for the current message loop, creating one if
-  // needed.
-  static scoped_refptr<MessageLoopProxy> current();
+ protected:
+  friend struct ExecutorTraits;
 
- protected:
-  friend class RefCountedThreadSafe<MessageLoopProxy, MessageLoopProxyTraits>;
-  friend struct MessageLoopProxyTraits;
+  Executor();
+  virtual ~Executor();
 
-  MessageLoopProxy();
-  virtual ~MessageLoopProxy();
-
-  // Called when the proxy is about to be deleted. Subclasses can override this
-  // to provide deletion on specific threads.
+  // 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:
+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 MessageLoopProxyTraits {
-  static void Destruct(const MessageLoopProxy* proxy) {
-    proxy->OnDestruct();
-  }
+struct BASE_EXPORT ExecutorTraits {
+  static void Destruct(const Executor* executor);
 };
 
 }  // namespace base
 
-#endif  // BASE_MESSAGE_LOOP_PROXY_H_
+#endif  // BASE_EXECUTOR_H_