| 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_THREADING_THREAD_H_ | |
| 6 #define BASE_THREADING_THREAD_H_ | |
| 7 | |
| 8 #include <string> | |
| 9 | |
| 10 #include "base/base_export.h" | |
| 11 #include "base/callback.h" | |
| 12 #include "base/memory/scoped_ptr.h" | |
| 13 #include "base/message_loop/message_loop.h" | |
| 14 #include "base/message_loop/timer_slack.h" | |
| 15 #include "base/single_thread_task_runner.h" | |
| 16 #include "base/synchronization/lock.h" | |
| 17 #include "base/threading/platform_thread.h" | |
| 18 | |
| 19 namespace base { | |
| 20 | |
| 21 class MessagePump; | |
| 22 class WaitableEvent; | |
| 23 | |
| 24 // A simple thread abstraction that establishes a MessageLoop on a new thread. | |
| 25 // The consumer uses the MessageLoop of the thread to cause code to execute on | |
| 26 // the thread. When this object is destroyed the thread is terminated. All | |
| 27 // pending tasks queued on the thread's message loop will run to completion | |
| 28 // before the thread is terminated. | |
| 29 // | |
| 30 // WARNING! SUBCLASSES MUST CALL Stop() IN THEIR DESTRUCTORS! See ~Thread(). | |
| 31 // | |
| 32 // After the thread is stopped, the destruction sequence is: | |
| 33 // | |
| 34 // (1) Thread::CleanUp() | |
| 35 // (2) MessageLoop::~MessageLoop | |
| 36 // (3.b) MessageLoop::DestructionObserver::WillDestroyCurrentMessageLoop | |
| 37 class BASE_EXPORT Thread : PlatformThread::Delegate { | |
| 38 public: | |
| 39 struct BASE_EXPORT Options { | |
| 40 typedef Callback<scoped_ptr<MessagePump>()> MessagePumpFactory; | |
| 41 | |
| 42 Options(); | |
| 43 Options(MessageLoop::Type type, size_t size); | |
| 44 ~Options(); | |
| 45 | |
| 46 // Specifies the type of message loop that will be allocated on the thread. | |
| 47 // This is ignored if message_pump_factory.is_null() is false. | |
| 48 MessageLoop::Type message_loop_type; | |
| 49 | |
| 50 // Specifies timer slack for thread message loop. | |
| 51 TimerSlack timer_slack; | |
| 52 | |
| 53 // Used to create the MessagePump for the MessageLoop. The callback is Run() | |
| 54 // on the thread. If message_pump_factory.is_null(), then a MessagePump | |
| 55 // appropriate for |message_loop_type| is created. Setting this forces the | |
| 56 // MessageLoop::Type to TYPE_CUSTOM. | |
| 57 MessagePumpFactory message_pump_factory; | |
| 58 | |
| 59 // Specifies the maximum stack size that the thread is allowed to use. | |
| 60 // This does not necessarily correspond to the thread's initial stack size. | |
| 61 // A value of 0 indicates that the default maximum should be used. | |
| 62 size_t stack_size; | |
| 63 | |
| 64 // Specifies the initial thread priority. | |
| 65 ThreadPriority priority; | |
| 66 }; | |
| 67 | |
| 68 // Constructor. | |
| 69 // name is a display string to identify the thread. | |
| 70 explicit Thread(const std::string& name); | |
| 71 | |
| 72 // Destroys the thread, stopping it if necessary. | |
| 73 // | |
| 74 // NOTE: ALL SUBCLASSES OF Thread MUST CALL Stop() IN THEIR DESTRUCTORS (or | |
| 75 // guarantee Stop() is explicitly called before the subclass is destroyed). | |
| 76 // This is required to avoid a data race between the destructor modifying the | |
| 77 // vtable, and the thread's ThreadMain calling the virtual method Run(). It | |
| 78 // also ensures that the CleanUp() virtual method is called on the subclass | |
| 79 // before it is destructed. | |
| 80 ~Thread() override; | |
| 81 | |
| 82 #if defined(OS_WIN) | |
| 83 // Causes the thread to initialize COM. This must be called before calling | |
| 84 // Start() or StartWithOptions(). If |use_mta| is false, the thread is also | |
| 85 // started with a TYPE_UI message loop. It is an error to call | |
| 86 // init_com_with_mta(false) and then StartWithOptions() with any message loop | |
| 87 // type other than TYPE_UI. | |
| 88 void init_com_with_mta(bool use_mta) { | |
| 89 DCHECK(!start_event_); | |
| 90 com_status_ = use_mta ? MTA : STA; | |
| 91 } | |
| 92 #endif | |
| 93 | |
| 94 // Starts the thread. Returns true if the thread was successfully started; | |
| 95 // otherwise, returns false. Upon successful return, the message_loop() | |
| 96 // getter will return non-null. | |
| 97 // | |
| 98 // Note: This function can't be called on Windows with the loader lock held; | |
| 99 // i.e. during a DllMain, global object construction or destruction, atexit() | |
| 100 // callback. | |
| 101 bool Start(); | |
| 102 | |
| 103 // Starts the thread. Behaves exactly like Start in addition to allow to | |
| 104 // override the default options. | |
| 105 // | |
| 106 // Note: This function can't be called on Windows with the loader lock held; | |
| 107 // i.e. during a DllMain, global object construction or destruction, atexit() | |
| 108 // callback. | |
| 109 bool StartWithOptions(const Options& options); | |
| 110 | |
| 111 // Starts the thread and wait for the thread to start and run initialization | |
| 112 // before returning. It's same as calling Start() and then | |
| 113 // WaitUntilThreadStarted(). | |
| 114 // Note that using this (instead of Start() or StartWithOptions() causes | |
| 115 // jank on the calling thread, should be used only in testing code. | |
| 116 bool StartAndWaitForTesting(); | |
| 117 | |
| 118 // Blocks until the thread starts running. Called within StartAndWait(). | |
| 119 // Note that calling this causes jank on the calling thread, must be used | |
| 120 // carefully for production code. | |
| 121 bool WaitUntilThreadStarted(); | |
| 122 | |
| 123 // Signals the thread to exit and returns once the thread has exited. After | |
| 124 // this method returns, the Thread object is completely reset and may be used | |
| 125 // as if it were newly constructed (i.e., Start may be called again). | |
| 126 // | |
| 127 // Stop may be called multiple times and is simply ignored if the thread is | |
| 128 // already stopped. | |
| 129 // | |
| 130 // NOTE: If you are a consumer of Thread, it is not necessary to call this | |
| 131 // before deleting your Thread objects, as the destructor will do it. | |
| 132 // IF YOU ARE A SUBCLASS OF Thread, YOU MUST CALL THIS IN YOUR DESTRUCTOR. | |
| 133 void Stop(); | |
| 134 | |
| 135 // Signals the thread to exit in the near future. | |
| 136 // | |
| 137 // WARNING: This function is not meant to be commonly used. Use at your own | |
| 138 // risk. Calling this function will cause message_loop() to become invalid in | |
| 139 // the near future. This function was created to workaround a specific | |
| 140 // deadlock on Windows with printer worker thread. In any other case, Stop() | |
| 141 // should be used. | |
| 142 // | |
| 143 // StopSoon should not be called multiple times as it is risky to do so. It | |
| 144 // could cause a timing issue in message_loop() access. Call Stop() to reset | |
| 145 // the thread object once it is known that the thread has quit. | |
| 146 void StopSoon(); | |
| 147 | |
| 148 // Returns the message loop for this thread. Use the MessageLoop's | |
| 149 // PostTask methods to execute code on the thread. This only returns | |
| 150 // non-null after a successful call to Start. After Stop has been called, | |
| 151 // this will return NULL. | |
| 152 // | |
| 153 // NOTE: You must not call this MessageLoop's Quit method directly. Use | |
| 154 // the Thread's Stop method instead. | |
| 155 // | |
| 156 MessageLoop* message_loop() const { return message_loop_; } | |
| 157 | |
| 158 // Returns a TaskRunner for this thread. Use the TaskRunner's PostTask | |
| 159 // methods to execute code on the thread. Returns NULL if the thread is not | |
| 160 // running (e.g. before Start or after Stop have been called). Callers can | |
| 161 // hold on to this even after the thread is gone; in this situation, attempts | |
| 162 // to PostTask() will fail. | |
| 163 scoped_refptr<SingleThreadTaskRunner> task_runner() const { | |
| 164 return message_loop_ ? message_loop_->task_runner() : nullptr; | |
| 165 } | |
| 166 | |
| 167 // Returns the name of this thread (for display in debugger too). | |
| 168 const std::string& thread_name() const { return name_; } | |
| 169 | |
| 170 // The native thread handle. | |
| 171 PlatformThreadHandle thread_handle() { return thread_; } | |
| 172 | |
| 173 // The thread ID. | |
| 174 PlatformThreadId thread_id() const; | |
| 175 | |
| 176 // Returns true if the thread has been started, and not yet stopped. | |
| 177 bool IsRunning() const; | |
| 178 | |
| 179 protected: | |
| 180 // Called just prior to starting the message loop | |
| 181 virtual void Init() {} | |
| 182 | |
| 183 // Called to start the message loop | |
| 184 virtual void Run(MessageLoop* message_loop); | |
| 185 | |
| 186 // Called just after the message loop ends | |
| 187 virtual void CleanUp() {} | |
| 188 | |
| 189 static void SetThreadWasQuitProperly(bool flag); | |
| 190 static bool GetThreadWasQuitProperly(); | |
| 191 | |
| 192 void set_message_loop(MessageLoop* message_loop) { | |
| 193 message_loop_ = message_loop; | |
| 194 } | |
| 195 | |
| 196 private: | |
| 197 #if defined(OS_WIN) | |
| 198 enum ComStatus { | |
| 199 NONE, | |
| 200 STA, | |
| 201 MTA, | |
| 202 }; | |
| 203 #endif | |
| 204 | |
| 205 // PlatformThread::Delegate methods: | |
| 206 void ThreadMain() override; | |
| 207 | |
| 208 #if defined(OS_WIN) | |
| 209 // Whether this thread needs to initialize COM, and if so, in what mode. | |
| 210 ComStatus com_status_; | |
| 211 #endif | |
| 212 | |
| 213 // If true, we're in the middle of stopping, and shouldn't access | |
| 214 // |message_loop_|. It may non-NULL and invalid. | |
| 215 bool stopping_; | |
| 216 | |
| 217 // True while inside of Run(). | |
| 218 bool running_; | |
| 219 mutable base::Lock running_lock_; // Protects running_. | |
| 220 | |
| 221 // The thread's handle. | |
| 222 PlatformThreadHandle thread_; | |
| 223 mutable base::Lock thread_lock_; // Protects thread_. | |
| 224 | |
| 225 // The thread's message loop. Valid only while the thread is alive. Set | |
| 226 // by the created thread. | |
| 227 MessageLoop* message_loop_; | |
| 228 | |
| 229 // Stores Options::timer_slack_ until the message loop has been bound to | |
| 230 // a thread. | |
| 231 TimerSlack message_loop_timer_slack_; | |
| 232 | |
| 233 // The name of the thread. Used for debugging purposes. | |
| 234 std::string name_; | |
| 235 | |
| 236 // Non-null if the thread has successfully started. | |
| 237 scoped_ptr<WaitableEvent> start_event_; | |
| 238 | |
| 239 friend void ThreadQuitHelper(); | |
| 240 | |
| 241 DISALLOW_COPY_AND_ASSIGN(Thread); | |
| 242 }; | |
| 243 | |
| 244 } // namespace base | |
| 245 | |
| 246 #endif // BASE_THREADING_THREAD_H_ | |
| OLD | NEW |
|---|
Chromium Code Reviews
