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