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. That is, submitting a task as non-nestable may not | |
35 // affect when the task gets executed, or it could make it run | |
36 // later than it normally would, but it won't make it run earlier | |
37 // than it normally would. (This is implied by the definition of | |
38 // "non-nestable"; see comment above PostNonNestable*Task.) | |
39 // | |
40 // - Increasing the delay can only delay execution of the task. | |
41 // That is, increasing the delay may not affect when the task gets | |
42 // executed, or it could make it run later than it normally would, | |
43 // but it won't make it run earlier than it normally would. | |
44 // | |
45 // Executor does not guarantee the order in which submitted tasks are | |
46 // run or whether they're run on a particular thread. Also it does | |
47 // not guarantee a memory model for shared data between tasks. (In | |
48 // other words, you should use your own synchronization/locking | |
49 // primitives if you need to share data between tasks.) | |
50 // | |
51 // Implementations of Executor should be thread-safe in that all | |
52 // methods must be safe to call on any thread. Ownership semantics | |
53 // for Executors are in general not clear, which is why the interface | |
54 // itself is RefCountedThreadSafe. | |
55 // | |
56 // Some theoretical implementations of Executor: | |
57 // | |
58 // - An Executor that uses a worker pool to run submitted tasks. | |
59 // | |
60 // - An Executor that, for each task, spawns a non-joinable thread to | |
61 // execute that task and immediately quit. | |
62 // | |
63 // - An Executor that stores the list of submitted tasks and has a | |
64 // method Run() that executes each runnable task in random order. | |
65 class BASE_EXPORT Executor | |
66 : public RefCountedThreadSafe<Executor, ExecutorTraits> { | |
67 public: | |
68 // TODO(akalin): Get rid of the boolean return value for the | |
69 // Post*Task methods. | |
70 | |
71 // Submits the given task for execution. Returns true if the task | |
72 // may be executed at some point in the future, and false if the | |
73 // task definitely will not be executed. | |
74 virtual bool PostTask(const tracked_objects::Location& from_here, | |
75 const Closure& task) = 0; | |
76 | |
77 // TODO(akalin): Make Post*DelayedTask use TimeDelta instead. | |
78 | |
79 // Like PostTask, but tries to run the submitted task only after | |
80 // |delay_ms| has passed. PostDelayedTask with zero delay should be | |
81 // equivalent to PostTask. | |
82 // | |
83 // It is valid for an implementation to ignore |delay_ms|; that is, | |
84 // to have PostDelayedTask behave the same as PostTask. | |
85 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 her
| |
86 const Closure& task, | |
87 int64 delay_ms) = 0; | |
88 | |
89 // The two methods below are like the two methods above, but they | |
90 // guarantee that the submitted task will not execute nested within | |
91 // an already-executing task. | |
92 | |
93 virtual bool PostNonNestableTask(const tracked_objects::Location& from_here, | |
94 const Closure& task) = 0; | |
95 | |
96 virtual bool PostNonNestableDelayedTask( | |
97 const tracked_objects::Location& from_here, | |
98 const Closure& task, | |
99 int64 delay_ms) = 0; | |
100 | |
101 // Returns true if the current thread is a thread on which a task | |
102 // may be executed, and false if no task will be executed on the | |
103 // current thread. | |
104 // | |
105 // It is valid for an implementation to always return true, or in | |
106 // general to use 'true' as a default value. | |
107 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 thin
| |
108 | |
109 // 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
| |
110 // posted to the thread that called PostTaskAndReply(). Both |task| | |
111 // and |reply| are guaranteed to be deleted on the thread from which | |
112 // PostTaskAndReply() is invoked. This allows objects that must be | |
113 // deleted on the originating thread to be bound into the |task| and | |
114 // |reply| Closures. In particular, it can be useful to use | |
115 // WeakPtr<> in the |reply| Closure so that the reply operation can | |
116 // be canceled. See the following pseudo-code: | |
117 // | |
118 // class DataBuffer : public RefCountedThreadSafe<DataBuffer> { | |
119 // public: | |
120 // // Called to add data into a buffer. | |
121 // void AddData(void* buf, size_t length); | |
122 // ... | |
123 // }; | |
124 // | |
125 // | |
126 // class DataLoader : public SupportsWeakPtr<DataLoader> { | |
127 // public: | |
128 // void GetData() { | |
129 // scoped_refptr<DataBuffer> buffer = new DataBuffer(); | |
130 // target_thread_.message_loop_proxy()->PostTaskAndReply( | |
131 // FROM_HERE, | |
132 // base::Bind(&DataBuffer::AddData, buffer), | |
133 // base::Bind(&DataLoader::OnDataReceived, AsWeakPtr(), buffer)); | |
134 // } | |
135 // | |
136 // private: | |
137 // void OnDataReceived(scoped_refptr<DataBuffer> buffer) { | |
138 // // Do something with buffer. | |
139 // } | |
140 // }; | |
141 // | |
142 // | |
143 // Things to notice: | |
144 // * Results of |task| are shared with |reply| by binding a shared argument | |
145 // (a DataBuffer instance). | |
146 // * The DataLoader object has no special thread safety. | |
147 // * The DataLoader object can be deleted while |task| is still running, | |
148 // and the reply will cancel itself safely because it is bound to a | |
149 // WeakPtr<>. | |
150 bool PostTaskAndReply(const tracked_objects::Location& from_here, | |
151 const Closure& task, | |
152 const Closure& reply); | |
153 | |
154 // Submits a non-nestable task to delete the given object. Returns | |
155 // true if the object may be deleted at some point in the future, | |
156 // and false if the object definitely will not be deleted. | |
157 template <class T> | |
158 bool DeleteSoon(const tracked_objects::Location& from_here, | |
159 const T* object) { | |
160 return subtle::DeleteHelperInternal<T, bool>::DeleteViaExecutor( | |
161 this, from_here, object); | |
162 } | |
163 | |
164 // Submits a non-nestable task to release the given object. Returns | |
165 // true if the object may be released at some point in the future, | |
166 // and false if the object definitely will not be released. | |
167 template <class T> | |
168 bool ReleaseSoon(const tracked_objects::Location& from_here, | |
169 T* object) { | |
170 return subtle::ReleaseHelperInternal<T, bool>::ReleaseViaExecutor( | |
171 this, from_here, object); | |
172 } | |
173 | |
174 protected: | |
175 friend struct ExecutorTraits; | |
176 | |
177 // Only the Windows debug build seems to need this: see | |
178 // http://crbug.com/112250. | |
179 friend class RefCountedThreadSafe<Executor, ExecutorTraits>; | |
180 | |
181 Executor(); | |
182 virtual ~Executor(); | |
183 | |
184 // Called when this object should be destroyed. By default simply | |
185 // deletes |this|, but can be overridden to do something else, like | |
186 // delete on a certain thread. | |
187 virtual void OnDestruct() const; | |
188 | |
189 private: | |
190 template <class T, class R> friend class subtle::DeleteHelperInternal; | |
191 template <class T, class R> friend class subtle::ReleaseHelperInternal; | |
192 | |
193 bool DeleteSoonInternal(const tracked_objects::Location& from_here, | |
194 void(*deleter)(const void*), | |
195 const void* object); | |
196 | |
197 bool ReleaseSoonInternal(const tracked_objects::Location& from_here, | |
198 void(*releaser)(const void*), | |
199 const void* object); | |
200 }; | |
201 | |
202 struct BASE_EXPORT ExecutorTraits { | |
203 static void Destruct(const Executor* executor); | |
204 }; | |
205 | |
206 } // namespace base | |
207 | |
208 #endif // BASE_EXECUTOR_H_ | |
OLD | NEW |