OLD | NEW |
---|---|
(Empty) | |
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. | |
2 // Use of this source code is governed by a BSD-style license that can be | |
3 // found in the LICENSE file. | |
4 | |
5 #ifndef BASE_EXECUTOR_H_ | |
6 #define BASE_EXECUTOR_H_ | |
7 #pragma once | |
8 | |
9 #include "base/base_export.h" | |
10 #include "base/basictypes.h" | |
11 #include "base/callback_forward.h" | |
12 #include "base/executor_helpers.h" | |
13 #include "base/memory/ref_counted.h" | |
14 | |
15 namespace tracked_objects { | |
16 class Location; | |
17 } // namespace tracked_objects | |
18 | |
19 namespace base { | |
20 | |
21 struct ExecutorTraits; | |
22 | |
23 // An Executor is an object that executes submitted tasks (in the form | |
24 // of Closure objects). The Executor interface provides a way of | |
25 // decoupling task submission from the mechanics of how each task will | |
26 // be run. Executor provides very weak guarantees as to how submitted | |
27 // tasks are run (or if they're run at all). In particular, it only | |
28 // guarantees: | |
29 // | |
30 // - Submitting a task will not run it synchronously. That is, no | |
31 // Post*Task method will call task.Run() directly. | |
32 // | |
33 // - Submitting a task as non-nestable can only delay execution of | |
34 // the task. (This is implied by the definition of "non-nestable"; | |
35 // see comment above PostNonNestable*Task.) | |
36 // | |
37 // - 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
| |
38 // | |
39 // Executor does not guarantee the order in which submitted tasks are | |
40 // run or whether they're run on a particular thread. Also it does | |
41 // not guarantee a memory model for shared data between tasks. (In | |
42 // other words, you should use your own synchronization/locking | |
43 // primitives if you need to share data between tasks.) | |
44 // | |
45 // Implementations of Executor should be thread-safe in that all | |
46 // methods must be safe to call on any thread. Ownership semantics | |
47 // for Executors are in general not clear, which is why the interface | |
48 // itself is RefCountedThreadSafe. | |
49 // | |
50 // Some possible implementations of Executor: | |
51 // | |
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
| |
52 // - An Executor that uses a worker pool to run submitted tasks. | |
53 // | |
54 // - 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
| |
55 // execute that task and immediately quit. | |
56 // | |
57 // - An Executor that stores the list of submitted tasks and has a | |
58 // method Run() that executes each runnable task in random order. | |
59 class BASE_EXPORT Executor | |
60 : public RefCountedThreadSafe<Executor, ExecutorTraits> { | |
61 public: | |
62 // Submits the given task for execution. Returns true if the task | |
63 // may be executed at some point in the future, and false if the | |
64 // task definitely will not be executed. | |
65 virtual bool PostTask(const tracked_objects::Location& from_here, | |
66 const Closure& task) = 0; | |
67 | |
68 // TODO(akalin): Make Post*DelayedTask use TimeDelta instead. | |
69 | |
70 // Like PostTask, but tries to run the submitted task only after | |
71 // |delay_ms| has passed. PostDelayedTask with zero delay should be | |
72 // equivalent to PostTask. | |
73 // | |
74 // It is valid for an implementation to ignore |delay_ms|; that is, | |
75 // to have PostDelayedTask behave the same as PostTask. | |
76 virtual bool PostDelayedTask(const tracked_objects::Location& from_here, | |
77 const Closure& task, | |
78 int64 delay_ms) = 0; | |
79 | |
80 // The two methods below are like the two methods above, but they | |
81 // guarantee that the submitted task will not execute nested within | |
82 // an already-executing task. | |
83 | |
84 virtual bool PostNonNestableTask(const tracked_objects::Location& from_here, | |
85 const Closure& task) = 0; | |
86 | |
87 virtual bool PostNonNestableDelayedTask( | |
88 const tracked_objects::Location& from_here, | |
89 const Closure& task, | |
90 int64 delay_ms) = 0; | |
91 | |
92 // Returns true if the current thread is a thread on which a task | |
93 // may be executed, and false if no task will be executed on the | |
94 // current thread. | |
95 // | |
96 // It is valid for an implementation to always return true, or in | |
97 // general to use 'true' as a default value. | |
98 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.
| |
99 | |
100 // Posts |task| on the current Executor. On completion, |reply| is | |
101 // posted to the thread that called PostTaskAndReply(). Both |task| | |
102 // and |reply| are guaranteed to be deleted on the thread from which | |
103 // PostTaskAndReply() is invoked. This allows objects that must be | |
104 // deleted on the originating thread to be bound into the |task| and | |
105 // |reply| Closures. In particular, it can be useful to use | |
106 // WeakPtr<> in the |reply| Closure so that the reply operation can | |
107 // be canceled. See the following pseudo-code: | |
108 // | |
109 // class DataBuffer : public RefCountedThreadSafe<DataBuffer> { | |
110 // public: | |
111 // // Called to add data into a buffer. | |
112 // void AddData(void* buf, size_t length); | |
113 // ... | |
114 // }; | |
115 // | |
116 // | |
117 // class DataLoader : public SupportsWeakPtr<DataLoader> { | |
118 // public: | |
119 // void GetData() { | |
120 // scoped_refptr<DataBuffer> buffer = new DataBuffer(); | |
121 // target_thread_.message_loop_proxy()->PostTaskAndReply( | |
122 // FROM_HERE, | |
123 // base::Bind(&DataBuffer::AddData, buffer), | |
124 // base::Bind(&DataLoader::OnDataReceived, AsWeakPtr(), buffer)); | |
125 // } | |
126 // | |
127 // private: | |
128 // void OnDataReceived(scoped_refptr<DataBuffer> buffer) { | |
129 // // Do something with buffer. | |
130 // } | |
131 // }; | |
132 // | |
133 // | |
134 // Things to notice: | |
135 // * Results of |task| are shared with |reply| by binding a shared argument | |
136 // (a DataBuffer instance). | |
137 // * The DataLoader object has no special thread safety. | |
138 // * The DataLoader object can be deleted while |task| is still running, | |
139 // and the reply will cancel itself safely because it is bound to a | |
140 // WeakPtr<>. | |
141 bool PostTaskAndReply(const tracked_objects::Location& from_here, | |
142 const Closure& task, | |
143 const Closure& reply); | |
144 | |
145 // Submits a non-nestable task to delete the given object. Returns | |
146 // true if the object may be deleted at some point in the future, | |
147 // and false if the object definitely will not be deleted. | |
148 template <class T> | |
149 bool DeleteSoon(const tracked_objects::Location& from_here, | |
150 const T* object) { | |
151 return subtle::DeleteHelperInternal<T, bool>::DeleteViaExecutor( | |
152 this, from_here, object); | |
153 } | |
154 | |
155 // Submits a non-nestable task to release the given object. Returns | |
156 // true if the object may be released at some point in the future, | |
157 // and false if the object definitely will not be released. | |
158 template <class T> | |
159 bool ReleaseSoon(const tracked_objects::Location& from_here, | |
160 T* object) { | |
161 return subtle::ReleaseHelperInternal<T, bool>::ReleaseViaExecutor( | |
162 this, from_here, object); | |
163 } | |
164 | |
165 protected: | |
166 friend struct ExecutorTraits; | |
167 | |
168 Executor(); | |
169 virtual ~Executor(); | |
170 | |
171 // Called when this object should be destroyed. By default simply | |
172 // deletes |this|, but can be overridden to do something else, like | |
173 // delete on a certain thread. | |
174 virtual void OnDestruct() const; | |
175 | |
176 private: | |
177 template <class T, class R> friend class subtle::DeleteHelperInternal; | |
178 template <class T, class R> friend class subtle::ReleaseHelperInternal; | |
179 | |
180 bool DeleteSoonInternal(const tracked_objects::Location& from_here, | |
181 void(*deleter)(const void*), | |
182 const void* object); | |
183 | |
184 bool ReleaseSoonInternal(const tracked_objects::Location& from_here, | |
185 void(*releaser)(const void*), | |
186 const void* object); | |
187 }; | |
188 | |
189 struct BASE_EXPORT ExecutorTraits { | |
190 static void Destruct(const Executor* executor); | |
191 }; | |
192 | |
193 } // namespace base | |
194 | |
195 #endif // BASE_EXECUTOR_H_ | |
OLD | NEW |