Index: base/executor.h |
diff --git a/base/executor.h b/base/executor.h |
new file mode 100644 |
index 0000000000000000000000000000000000000000..c60b9907ea3b04118b3e4ee5c3cee7475ef4bf4d |
--- /dev/null |
+++ b/base/executor.h |
@@ -0,0 +1,195 @@ |
+// 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 nothin
|
+// |
+// 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 exe
akalin
2012/01/31 23:57:29
I'm a bit hesitant to do that, because people may
|
+// - 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
akalin
2012/01/31 23:57:29
These are just theoretical implementations for cli
|
+// 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
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_ |