OLD | NEW |
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. | 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 | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef BASE_THREADING_THREAD_H_ | 5 #ifndef BASE_THREADING_THREAD_H_ |
6 #define BASE_THREADING_THREAD_H_ | 6 #define BASE_THREADING_THREAD_H_ |
7 | 7 |
8 #include <stddef.h> | 8 #include <stddef.h> |
9 | 9 |
10 #include <memory> | 10 #include <memory> |
11 #include <string> | 11 #include <string> |
12 | 12 |
13 #include "base/base_export.h" | 13 #include "base/base_export.h" |
14 #include "base/callback.h" | 14 #include "base/callback.h" |
15 #include "base/macros.h" | 15 #include "base/macros.h" |
16 #include "base/message_loop/message_loop.h" | 16 #include "base/message_loop/message_loop.h" |
17 #include "base/message_loop/timer_slack.h" | 17 #include "base/message_loop/timer_slack.h" |
| 18 #include "base/sequence_checker.h" |
18 #include "base/single_thread_task_runner.h" | 19 #include "base/single_thread_task_runner.h" |
19 #include "base/synchronization/lock.h" | 20 #include "base/synchronization/lock.h" |
20 #include "base/synchronization/waitable_event.h" | 21 #include "base/synchronization/waitable_event.h" |
21 #include "base/threading/platform_thread.h" | 22 #include "base/threading/platform_thread.h" |
22 #include "build/build_config.h" | 23 #include "build/build_config.h" |
23 | 24 |
24 namespace base { | 25 namespace base { |
25 | 26 |
26 class MessagePump; | 27 class MessagePump; |
27 class RunLoop; | 28 class RunLoop; |
28 | 29 |
29 // A simple thread abstraction that establishes a MessageLoop on a new thread. | 30 // A simple thread abstraction that establishes a MessageLoop on a new thread. |
30 // The consumer uses the MessageLoop of the thread to cause code to execute on | 31 // The consumer uses the MessageLoop of the thread to cause code to execute on |
31 // the thread. When this object is destroyed the thread is terminated. All | 32 // the thread. When this object is destroyed the thread is terminated. All |
32 // pending tasks queued on the thread's message loop will run to completion | 33 // pending tasks queued on the thread's message loop will run to completion |
33 // before the thread is terminated. | 34 // before the thread is terminated. |
34 // | 35 // |
35 // WARNING! SUBCLASSES MUST CALL Stop() IN THEIR DESTRUCTORS! See ~Thread(). | 36 // WARNING! SUBCLASSES MUST CALL Stop() IN THEIR DESTRUCTORS! See ~Thread(). |
36 // | 37 // |
37 // After the thread is stopped, the destruction sequence is: | 38 // After the thread is stopped, the destruction sequence is: |
38 // | 39 // |
39 // (1) Thread::CleanUp() | 40 // (1) Thread::CleanUp() |
40 // (2) MessageLoop::~MessageLoop | 41 // (2) MessageLoop::~MessageLoop |
41 // (3.b) MessageLoop::DestructionObserver::WillDestroyCurrentMessageLoop | 42 // (3.b) MessageLoop::DestructionObserver::WillDestroyCurrentMessageLoop |
| 43 // |
| 44 // This API is not thread-safe: unless indicated otherwise its methods are only |
| 45 // valid from the owning sequence (which is the one from which Start() is |
| 46 // invoked, should it differ from the one on which it was constructed). |
42 class BASE_EXPORT Thread : PlatformThread::Delegate { | 47 class BASE_EXPORT Thread : PlatformThread::Delegate { |
43 public: | 48 public: |
44 struct BASE_EXPORT Options { | 49 struct BASE_EXPORT Options { |
45 typedef Callback<std::unique_ptr<MessagePump>()> MessagePumpFactory; | 50 typedef Callback<std::unique_ptr<MessagePump>()> MessagePumpFactory; |
46 | 51 |
47 Options(); | 52 Options(); |
48 Options(MessageLoop::Type type, size_t size); | 53 Options(MessageLoop::Type type, size_t size); |
49 Options(const Options& other); | 54 Options(const Options& other); |
50 ~Options(); | 55 ~Options(); |
51 | 56 |
52 // Specifies the type of message loop that will be allocated on the thread. | 57 // Specifies the type of message loop that will be allocated on the thread. |
53 // This is ignored if message_pump_factory.is_null() is false. | 58 // This is ignored if message_pump_factory.is_null() is false. |
54 MessageLoop::Type message_loop_type; | 59 MessageLoop::Type message_loop_type = MessageLoop::TYPE_DEFAULT; |
55 | 60 |
56 // Specifies timer slack for thread message loop. | 61 // Specifies timer slack for thread message loop. |
57 TimerSlack timer_slack; | 62 TimerSlack timer_slack = TIMER_SLACK_NONE; |
58 | 63 |
59 // Used to create the MessagePump for the MessageLoop. The callback is Run() | 64 // Used to create the MessagePump for the MessageLoop. The callback is Run() |
60 // on the thread. If message_pump_factory.is_null(), then a MessagePump | 65 // on the thread. If message_pump_factory.is_null(), then a MessagePump |
61 // appropriate for |message_loop_type| is created. Setting this forces the | 66 // appropriate for |message_loop_type| is created. Setting this forces the |
62 // MessageLoop::Type to TYPE_CUSTOM. | 67 // MessageLoop::Type to TYPE_CUSTOM. |
63 MessagePumpFactory message_pump_factory; | 68 MessagePumpFactory message_pump_factory; |
64 | 69 |
65 // Specifies the maximum stack size that the thread is allowed to use. | 70 // Specifies the maximum stack size that the thread is allowed to use. |
66 // This does not necessarily correspond to the thread's initial stack size. | 71 // This does not necessarily correspond to the thread's initial stack size. |
67 // A value of 0 indicates that the default maximum should be used. | 72 // A value of 0 indicates that the default maximum should be used. |
68 size_t stack_size; | 73 size_t stack_size = 0; |
69 | 74 |
70 // Specifies the initial thread priority. | 75 // Specifies the initial thread priority. |
71 ThreadPriority priority; | 76 ThreadPriority priority = ThreadPriority::NORMAL; |
72 }; | 77 }; |
73 | 78 |
74 // Constructor. | 79 // Constructor. |
75 // name is a display string to identify the thread. | 80 // name is a display string to identify the thread. |
76 explicit Thread(const std::string& name); | 81 explicit Thread(const std::string& name); |
77 | 82 |
78 // Destroys the thread, stopping it if necessary. | 83 // Destroys the thread, stopping it if necessary. |
79 // | 84 // |
80 // NOTE: ALL SUBCLASSES OF Thread MUST CALL Stop() IN THEIR DESTRUCTORS (or | 85 // NOTE: ALL SUBCLASSES OF Thread MUST CALL Stop() IN THEIR DESTRUCTORS (or |
81 // guarantee Stop() is explicitly called before the subclass is destroyed). | 86 // guarantee Stop() is explicitly called before the subclass is destroyed). |
(...skipping 70 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
152 void StopSoon(); | 157 void StopSoon(); |
153 | 158 |
154 // Returns the message loop for this thread. Use the MessageLoop's | 159 // Returns the message loop for this thread. Use the MessageLoop's |
155 // PostTask methods to execute code on the thread. This only returns | 160 // PostTask methods to execute code on the thread. This only returns |
156 // non-null after a successful call to Start. After Stop has been called, | 161 // non-null after a successful call to Start. After Stop has been called, |
157 // this will return nullptr. | 162 // this will return nullptr. |
158 // | 163 // |
159 // NOTE: You must not call this MessageLoop's Quit method directly. Use | 164 // NOTE: You must not call this MessageLoop's Quit method directly. Use |
160 // the Thread's Stop method instead. | 165 // the Thread's Stop method instead. |
161 // | 166 // |
162 MessageLoop* message_loop() const { return message_loop_; } | 167 // In addition to this Thread's owning sequence, this can also safely be |
| 168 // called from the underlying thread itself. |
| 169 MessageLoop* message_loop() const { |
| 170 // This class doesn't provide synchronization around |message_loop_| and as |
| 171 // such only the owner should access it (and the underlying thread which |
| 172 // never sees it before it's set). In practice, many callers are coming from |
| 173 // unrelated threads but provide their own implicit (e.g. memory barriers |
| 174 // from task posting) or explicit (e.g. locks) synchronization making the |
| 175 // access of |message_loop_| safe... Changing all of those callers is |
| 176 // unfeasible; instead verify that they can reliably see |
| 177 // |message_loop_ != nullptr| without synchronization as a proof that their |
| 178 // external synchronization catches the unsynchronized effects of Start(). |
| 179 // TODO(gab): Despite all of the above this test has to be disabled for now |
| 180 // per crbug.com/629139#c6. |
| 181 // DCHECK(owning_sequence_checker_.CalledOnValidSequencedThread() || |
| 182 // id_ == PlatformThread::CurrentId() || message_loop_) |
| 183 // << id_ << " vs " << PlatformThread::CurrentId(); |
| 184 return message_loop_; |
| 185 } |
163 | 186 |
164 // Returns a TaskRunner for this thread. Use the TaskRunner's PostTask | 187 // Returns a TaskRunner for this thread. Use the TaskRunner's PostTask |
165 // methods to execute code on the thread. Returns nullptr if the thread is not | 188 // methods to execute code on the thread. Returns nullptr if the thread is not |
166 // running (e.g. before Start or after Stop have been called). Callers can | 189 // running (e.g. before Start or after Stop have been called). Callers can |
167 // hold on to this even after the thread is gone; in this situation, attempts | 190 // hold on to this even after the thread is gone; in this situation, attempts |
168 // to PostTask() will fail. | 191 // to PostTask() will fail. |
| 192 // |
| 193 // In addition to this Thread's owning sequence, this can also safely be |
| 194 // called from the underlying thread itself. |
169 scoped_refptr<SingleThreadTaskRunner> task_runner() const { | 195 scoped_refptr<SingleThreadTaskRunner> task_runner() const { |
| 196 // Refer to the DCHECK and comment inside |message_loop()|. |
| 197 DCHECK(owning_sequence_checker_.CalledOnValidSequencedThread() || |
| 198 id_ == PlatformThread::CurrentId() || message_loop_) |
| 199 << id_ << " vs " << PlatformThread::CurrentId(); |
170 return message_loop_ ? message_loop_->task_runner() : nullptr; | 200 return message_loop_ ? message_loop_->task_runner() : nullptr; |
171 } | 201 } |
172 | 202 |
173 // Returns the name of this thread (for display in debugger too). | 203 // Returns the name of this thread (for display in debugger too). |
174 const std::string& thread_name() const { return name_; } | 204 const std::string& thread_name() const { return name_; } |
175 | 205 |
176 // Returns the thread ID. Should not be called before the first Start*() | 206 // Returns the thread ID. Should not be called before the first Start*() |
177 // call. Keeps on returning the same ID even after a Stop() call. The next | 207 // call. Keeps on returning the same ID even after a Stop() call. The next |
178 // Start*() call renews the ID. | 208 // Start*() call renews the ID. |
179 // | 209 // |
180 // WARNING: This function will block if the thread hasn't started yet. | 210 // WARNING: This function will block if the thread hasn't started yet. |
181 // | 211 // |
| 212 // This method is thread-safe. |
182 PlatformThreadId GetThreadId() const; | 213 PlatformThreadId GetThreadId() const; |
183 | 214 |
184 // Returns true if the thread has been started, and not yet stopped. | 215 // Returns true if the thread has been started, and not yet stopped. |
185 bool IsRunning() const; | 216 bool IsRunning() const; |
186 | 217 |
187 protected: | 218 protected: |
188 // Called just prior to starting the message loop | 219 // Called just prior to starting the message loop |
189 virtual void Init() {} | 220 virtual void Init() {} |
190 | 221 |
191 // Called to start the run loop | 222 // Called to start the run loop |
192 virtual void Run(RunLoop* run_loop); | 223 virtual void Run(RunLoop* run_loop); |
193 | 224 |
194 // Called just after the message loop ends | 225 // Called just after the message loop ends |
195 virtual void CleanUp() {} | 226 virtual void CleanUp() {} |
196 | 227 |
197 static void SetThreadWasQuitProperly(bool flag); | 228 static void SetThreadWasQuitProperly(bool flag); |
198 static bool GetThreadWasQuitProperly(); | 229 static bool GetThreadWasQuitProperly(); |
199 | 230 |
200 void set_message_loop(MessageLoop* message_loop) { | 231 void set_message_loop(MessageLoop* message_loop) { |
| 232 DCHECK(owning_sequence_checker_.CalledOnValidSequencedThread()); |
201 message_loop_ = message_loop; | 233 message_loop_ = message_loop; |
202 } | 234 } |
203 | 235 |
204 private: | 236 private: |
205 #if defined(OS_WIN) | 237 #if defined(OS_WIN) |
206 enum ComStatus { | 238 enum ComStatus { |
207 NONE, | 239 NONE, |
208 STA, | 240 STA, |
209 MTA, | 241 MTA, |
210 }; | 242 }; |
211 #endif | 243 #endif |
212 | 244 |
213 // PlatformThread::Delegate methods: | 245 // PlatformThread::Delegate methods: |
214 void ThreadMain() override; | 246 void ThreadMain() override; |
215 | 247 |
216 void ThreadQuitHelper(); | 248 void ThreadQuitHelper(); |
217 | 249 |
218 #if defined(OS_WIN) | 250 #if defined(OS_WIN) |
219 // Whether this thread needs to initialize COM, and if so, in what mode. | 251 // Whether this thread needs to initialize COM, and if so, in what mode. |
220 ComStatus com_status_; | 252 ComStatus com_status_ = NONE; |
221 #endif | 253 #endif |
222 | 254 |
223 // If true, we're in the middle of stopping, and shouldn't access | 255 // If true, we're in the middle of stopping, and shouldn't access |
224 // |message_loop_|. It may non-nullptr and invalid. | 256 // |message_loop_|. It may non-nullptr and invalid. |
225 // Should be written on the thread that created this thread. Also read data | 257 // Should be written on the thread that created this thread. Also read data |
226 // could be wrong on other threads. | 258 // could be wrong on other threads. |
227 bool stopping_; | 259 bool stopping_ = false; |
228 | 260 |
229 // True while inside of Run(). | 261 // True while inside of Run(). |
230 bool running_; | 262 bool running_ = false; |
231 mutable base::Lock running_lock_; // Protects |running_|. | 263 mutable base::Lock running_lock_; // Protects |running_|. |
232 | 264 |
233 // The thread's handle. | 265 // The thread's handle. |
234 PlatformThreadHandle thread_; | 266 PlatformThreadHandle thread_; |
235 mutable base::Lock thread_lock_; // Protects |thread_|. | 267 mutable base::Lock thread_lock_; // Protects |thread_|. |
236 | 268 |
237 // The thread's id once it has started. | 269 // The thread's id once it has started. |
238 PlatformThreadId id_; | 270 PlatformThreadId id_ = kInvalidThreadId; |
239 mutable WaitableEvent id_event_; // Protects |id_|. | 271 mutable WaitableEvent id_event_; // Protects |id_|. |
240 | 272 |
241 // The thread's MessageLoop and RunLoop. Valid only while the thread is alive. | 273 // The thread's MessageLoop and RunLoop. Valid only while the thread is alive. |
242 // Set by the created thread. | 274 // Set by the created thread. |
243 MessageLoop* message_loop_; | 275 MessageLoop* message_loop_ = nullptr; |
244 RunLoop* run_loop_; | 276 RunLoop* run_loop_ = nullptr; |
245 | 277 |
246 // Stores Options::timer_slack_ until the message loop has been bound to | 278 // Stores Options::timer_slack_ until the message loop has been bound to |
247 // a thread. | 279 // a thread. |
248 TimerSlack message_loop_timer_slack_; | 280 TimerSlack message_loop_timer_slack_ = TIMER_SLACK_NONE; |
249 | 281 |
250 // The name of the thread. Used for debugging purposes. | 282 // The name of the thread. Used for debugging purposes. |
251 std::string name_; | 283 const std::string name_; |
252 | 284 |
253 // Signaled when the created thread gets ready to use the message loop. | 285 // Signaled when the created thread gets ready to use the message loop. |
254 mutable WaitableEvent start_event_; | 286 mutable WaitableEvent start_event_; |
255 | 287 |
| 288 // This class is not thread-safe, use this to verify access from the owning |
| 289 // sequence of the Thread. |
| 290 SequenceChecker owning_sequence_checker_; |
| 291 |
256 DISALLOW_COPY_AND_ASSIGN(Thread); | 292 DISALLOW_COPY_AND_ASSIGN(Thread); |
257 }; | 293 }; |
258 | 294 |
259 } // namespace base | 295 } // namespace base |
260 | 296 |
261 #endif // BASE_THREADING_THREAD_H_ | 297 #endif // BASE_THREADING_THREAD_H_ |
OLD | NEW |