message_loop.h revision 00d26a728db2814620f390b418a7d6325ce5aca6
1// Copyright (c) 2006-2008 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_MESSAGE_LOOP_H_ 6#define BASE_MESSAGE_LOOP_H_ 7 8#include <queue> 9#include <string> 10 11#include "base/basictypes.h" 12#include "base/lock.h" 13#include "base/message_pump.h" 14#include "base/observer_list.h" 15#include "base/ref_counted.h" 16#include "base/task.h" 17 18#if defined(OS_WIN) 19// We need this to declare base::MessagePumpWin::Dispatcher, which we should 20// really just eliminate. 21#include "base/message_pump_win.h" 22#elif defined(OS_POSIX) 23#include "base/message_pump_libevent.h" 24#if !defined(OS_MACOSX) 25#include "base/message_pump_glib.h" 26#endif 27#endif 28 29class Histogram; 30 31// A MessageLoop is used to process events for a particular thread. There is 32// at most one MessageLoop instance per thread. 33// 34// Events include at a minimum Task instances submitted to PostTask or those 35// managed by TimerManager. Depending on the type of message pump used by the 36// MessageLoop other events such as UI messages may be processed. On Windows 37// APC calls (as time permits) and signals sent to a registered set of HANDLEs 38// may also be processed. 39// 40// NOTE: Unless otherwise specified, a MessageLoop's methods may only be called 41// on the thread where the MessageLoop's Run method executes. 42// 43// NOTE: MessageLoop has task reentrancy protection. This means that if a 44// task is being processed, a second task cannot start until the first task is 45// finished. Reentrancy can happen when processing a task, and an inner 46// message pump is created. That inner pump then processes native messages 47// which could implicitly start an inner task. Inner message pumps are created 48// with dialogs (DialogBox), common dialogs (GetOpenFileName), OLE functions 49// (DoDragDrop), printer functions (StartDoc) and *many* others. 50// 51// Sample workaround when inner task processing is needed: 52// bool old_state = MessageLoop::current()->NestableTasksAllowed(); 53// MessageLoop::current()->SetNestableTasksAllowed(true); 54// HRESULT hr = DoDragDrop(...); // Implicitly runs a modal message loop here. 55// MessageLoop::current()->SetNestableTasksAllowed(old_state); 56// // Process hr (the result returned by DoDragDrop(). 57// 58// Please be SURE your task is reentrant (nestable) and all global variables 59// are stable and accessible before calling SetNestableTasksAllowed(true). 60// 61class MessageLoop : public base::MessagePump::Delegate { 62 public: 63 // A TaskObserver is an object that receives task notifications from the 64 // MessageLoop. 65 // 66 // NOTE: A TaskObserver implementation should be extremely fast! 67 class TaskObserver { 68 public: 69 TaskObserver(); 70 71 // This method is called before processing a task. 72 virtual void WillProcessTask(base::TimeTicks birth_time) = 0; 73 74 // This method is called after processing a task. 75 virtual void DidProcessTask() = 0; 76 77 protected: 78 virtual ~TaskObserver(); 79 }; 80 81 static void EnableHistogrammer(bool enable_histogrammer); 82 83 // A DestructionObserver is notified when the current MessageLoop is being 84 // destroyed. These obsevers are notified prior to MessageLoop::current() 85 // being changed to return NULL. This gives interested parties the chance to 86 // do final cleanup that depends on the MessageLoop. 87 // 88 // NOTE: Any tasks posted to the MessageLoop during this notification will 89 // not be run. Instead, they will be deleted. 90 // 91 class DestructionObserver { 92 public: 93 virtual ~DestructionObserver(); 94 virtual void WillDestroyCurrentMessageLoop() = 0; 95 }; 96 97 // Add a DestructionObserver, which will start receiving notifications 98 // immediately. 99 void AddDestructionObserver(DestructionObserver* destruction_observer); 100 101 // Remove a DestructionObserver. It is safe to call this method while a 102 // DestructionObserver is receiving a notification callback. 103 void RemoveDestructionObserver(DestructionObserver* destruction_observer); 104 105 // The "PostTask" family of methods call the task's Run method asynchronously 106 // from within a message loop at some point in the future. 107 // 108 // With the PostTask variant, tasks are invoked in FIFO order, inter-mixed 109 // with normal UI or IO event processing. With the PostDelayedTask variant, 110 // tasks are called after at least approximately 'delay_ms' have elapsed. 111 // 112 // The NonNestable variants work similarly except that they promise never to 113 // dispatch the task from a nested invocation of MessageLoop::Run. Instead, 114 // such tasks get deferred until the top-most MessageLoop::Run is executing. 115 // 116 // The MessageLoop takes ownership of the Task, and deletes it after it has 117 // been Run(). 118 // 119 // NOTE: These methods may be called on any thread. The Task will be invoked 120 // on the thread that executes MessageLoop::Run(). 121 122 void PostTask( 123 const tracked_objects::Location& from_here, Task* task); 124 125 void PostDelayedTask( 126 const tracked_objects::Location& from_here, Task* task, int64 delay_ms); 127 128 void PostNonNestableTask( 129 const tracked_objects::Location& from_here, Task* task); 130 131 void PostNonNestableDelayedTask( 132 const tracked_objects::Location& from_here, Task* task, int64 delay_ms); 133 134 // A variant on PostTask that deletes the given object. This is useful 135 // if the object needs to live until the next run of the MessageLoop (for 136 // example, deleting a RenderProcessHost from within an IPC callback is not 137 // good). 138 // 139 // NOTE: This method may be called on any thread. The object will be deleted 140 // on the thread that executes MessageLoop::Run(). If this is not the same 141 // as the thread that calls PostDelayedTask(FROM_HERE, ), then T MUST inherit 142 // from RefCountedThreadSafe<T>! 143 template <class T> 144 void DeleteSoon(const tracked_objects::Location& from_here, T* object) { 145 PostNonNestableTask(from_here, new DeleteTask<T>(object)); 146 } 147 148 // A variant on PostTask that releases the given reference counted object 149 // (by calling its Release method). This is useful if the object needs to 150 // live until the next run of the MessageLoop, or if the object needs to be 151 // released on a particular thread. 152 // 153 // NOTE: This method may be called on any thread. The object will be 154 // released (and thus possibly deleted) on the thread that executes 155 // MessageLoop::Run(). If this is not the same as the thread that calls 156 // PostDelayedTask(FROM_HERE, ), then T MUST inherit from 157 // RefCountedThreadSafe<T>! 158 template <class T> 159 void ReleaseSoon(const tracked_objects::Location& from_here, T* object) { 160 PostNonNestableTask(from_here, new ReleaseTask<T>(object)); 161 } 162 163 // Run the message loop. 164 void Run(); 165 166 // Process all pending tasks, windows messages, etc., but don't wait/sleep. 167 // Return as soon as all items that can be run are taken care of. 168 void RunAllPending(); 169 170 // Signals the Run method to return after it is done processing all pending 171 // messages. This method may only be called on the same thread that called 172 // Run, and Run must still be on the call stack. 173 // 174 // Use QuitTask if you need to Quit another thread's MessageLoop, but note 175 // that doing so is fairly dangerous if the target thread makes nested calls 176 // to MessageLoop::Run. The problem being that you won't know which nested 177 // run loop you are quiting, so be careful! 178 // 179 void Quit(); 180 181 // This method is a variant of Quit, that does not wait for pending messages 182 // to be processed before returning from Run. 183 void QuitNow(); 184 185 // Invokes Quit on the current MessageLoop when run. Useful to schedule an 186 // arbitrary MessageLoop to Quit. 187 class QuitTask : public Task { 188 public: 189 virtual void Run() { 190 MessageLoop::current()->Quit(); 191 } 192 }; 193 194 // A MessageLoop has a particular type, which indicates the set of 195 // asynchronous events it may process in addition to tasks and timers. 196 // 197 // TYPE_DEFAULT 198 // This type of ML only supports tasks and timers. 199 // 200 // TYPE_UI 201 // This type of ML also supports native UI events (e.g., Windows messages). 202 // See also MessageLoopForUI. 203 // 204 // TYPE_IO 205 // This type of ML also supports asynchronous IO. See also 206 // MessageLoopForIO. 207 // 208 enum Type { 209 TYPE_DEFAULT, 210 TYPE_UI, 211 TYPE_IO 212 }; 213 214 // Normally, it is not necessary to instantiate a MessageLoop. Instead, it 215 // is typical to make use of the current thread's MessageLoop instance. 216 explicit MessageLoop(Type type = TYPE_DEFAULT); 217 ~MessageLoop(); 218 219 // Returns the type passed to the constructor. 220 Type type() const { return type_; } 221 222 // Optional call to connect the thread name with this loop. 223 void set_thread_name(const std::string& thread_name) { 224 DCHECK(thread_name_.empty()) << "Should not rename this thread!"; 225 thread_name_ = thread_name; 226 } 227 const std::string& thread_name() const { return thread_name_; } 228 229 // Returns the MessageLoop object for the current thread, or null if none. 230 static MessageLoop* current(); 231 232 // Enables or disables the recursive task processing. This happens in the case 233 // of recursive message loops. Some unwanted message loop may occurs when 234 // using common controls or printer functions. By default, recursive task 235 // processing is disabled. 236 // 237 // The specific case where tasks get queued is: 238 // - The thread is running a message loop. 239 // - It receives a task #1 and execute it. 240 // - The task #1 implicitly start a message loop, like a MessageBox in the 241 // unit test. This can also be StartDoc or GetSaveFileName. 242 // - The thread receives a task #2 before or while in this second message 243 // loop. 244 // - With NestableTasksAllowed set to true, the task #2 will run right away. 245 // Otherwise, it will get executed right after task #1 completes at "thread 246 // message loop level". 247 void SetNestableTasksAllowed(bool allowed); 248 bool NestableTasksAllowed() const; 249 250 // Enables nestable tasks on |loop| while in scope. 251 class ScopedNestableTaskAllower { 252 public: 253 explicit ScopedNestableTaskAllower(MessageLoop* loop) 254 : loop_(loop), 255 old_state_(loop_->NestableTasksAllowed()) { 256 loop_->SetNestableTasksAllowed(true); 257 } 258 ~ScopedNestableTaskAllower() { 259 loop_->SetNestableTasksAllowed(old_state_); 260 } 261 262 private: 263 MessageLoop* loop_; 264 bool old_state_; 265 }; 266 267 // Enables or disables the restoration during an exception of the unhandled 268 // exception filter that was active when Run() was called. This can happen 269 // if some third party code call SetUnhandledExceptionFilter() and never 270 // restores the previous filter. 271 void set_exception_restoration(bool restore) { 272 exception_restoration_ = restore; 273 } 274 275 // Returns true if we are currently running a nested message loop. 276 bool IsNested(); 277 278 // These functions can only be called on the same thread that |this| is 279 // running on. 280 void AddTaskObserver(TaskObserver* task_observer); 281 void RemoveTaskObserver(TaskObserver* task_observer); 282 283#if defined(OS_WIN) 284 typedef base::MessagePumpWin::Dispatcher Dispatcher; 285 typedef base::MessagePumpForUI::Observer Observer; 286#elif !defined(OS_MACOSX) 287 typedef base::MessagePumpForUI::Dispatcher Dispatcher; 288 typedef base::MessagePumpForUI::Observer Observer; 289#endif 290 291 // Returns true if the message loop has high resolution timers enabled. 292 // Provided for testing. 293 bool high_resolution_timers_enabled() { 294#if defined(OS_WIN) 295 return !high_resolution_timer_expiration_.is_null(); 296#else 297 return true; 298#endif 299 } 300 301 // When we go into high resolution timer mode, we will stay in hi-res mode 302 // for at least 1s. 303 static const int kHighResolutionTimerModeLeaseTimeMs = 1000; 304 305 //---------------------------------------------------------------------------- 306 protected: 307 struct RunState { 308 // Used to count how many Run() invocations are on the stack. 309 int run_depth; 310 311 // Used to record that Quit() was called, or that we should quit the pump 312 // once it becomes idle. 313 bool quit_received; 314 315#if !defined(OS_MACOSX) 316 Dispatcher* dispatcher; 317#endif 318 }; 319 320 class AutoRunState : RunState { 321 public: 322 explicit AutoRunState(MessageLoop* loop); 323 ~AutoRunState(); 324 private: 325 MessageLoop* loop_; 326 RunState* previous_state_; 327 }; 328 329 // This structure is copied around by value. 330 struct PendingTask { 331 Task* task; // The task to run. 332 base::Time delayed_run_time; // The time when the task should be run. 333 int sequence_num; // Used to facilitate sorting by run time. 334 bool nestable; // True if OK to dispatch from a nested loop. 335 336 PendingTask(Task* task, bool nestable) 337 : task(task), sequence_num(0), nestable(nestable) { 338 } 339 340 // Used to support sorting. 341 bool operator<(const PendingTask& other) const; 342 }; 343 344 class TaskQueue : public std::queue<PendingTask> { 345 public: 346 void Swap(TaskQueue* queue) { 347 c.swap(queue->c); // Calls std::deque::swap 348 } 349 }; 350 351 typedef std::priority_queue<PendingTask> DelayedTaskQueue; 352 353#if defined(OS_WIN) 354 base::MessagePumpWin* pump_win() { 355 return static_cast<base::MessagePumpWin*>(pump_.get()); 356 } 357#elif defined(OS_POSIX) 358 base::MessagePumpLibevent* pump_libevent() { 359 return static_cast<base::MessagePumpLibevent*>(pump_.get()); 360 } 361#endif 362 363 // A function to encapsulate all the exception handling capability in the 364 // stacks around the running of a main message loop. It will run the message 365 // loop in a SEH try block or not depending on the set_SEH_restoration() 366 // flag invoking respectively RunInternalInSEHFrame() or RunInternal(). 367 void RunHandler(); 368 369#if defined(OS_WIN) 370 __declspec(noinline) void RunInternalInSEHFrame(); 371#endif 372 373 // A surrounding stack frame around the running of the message loop that 374 // supports all saving and restoring of state, as is needed for any/all (ugly) 375 // recursive calls. 376 void RunInternal(); 377 378 // Called to process any delayed non-nestable tasks. 379 bool ProcessNextDelayedNonNestableTask(); 380 381 //---------------------------------------------------------------------------- 382 // Run a work_queue_ task or new_task, and delete it (if it was processed by 383 // PostTask). If there are queued tasks, the oldest one is executed and 384 // new_task is queued. new_task is optional and can be NULL. In this NULL 385 // case, the method will run one pending task (if any exist). Returns true if 386 // it executes a task. Queued tasks accumulate only when there is a 387 // non-nestable task currently processing, in which case the new_task is 388 // appended to the list work_queue_. Such re-entrancy generally happens when 389 // an unrequested message pump (typical of a native dialog) is executing in 390 // the context of a task. 391 bool QueueOrRunTask(Task* new_task); 392 393 // Runs the specified task and deletes it. 394 void RunTask(Task* task); 395 396 // Calls RunTask or queues the pending_task on the deferred task list if it 397 // cannot be run right now. Returns true if the task was run. 398 bool DeferOrRunPendingTask(const PendingTask& pending_task); 399 400 // Adds the pending task to delayed_work_queue_. 401 void AddToDelayedWorkQueue(const PendingTask& pending_task); 402 403 // Load tasks from the incoming_queue_ into work_queue_ if the latter is 404 // empty. The former requires a lock to access, while the latter is directly 405 // accessible on this thread. 406 void ReloadWorkQueue(); 407 408 // Delete tasks that haven't run yet without running them. Used in the 409 // destructor to make sure all the task's destructors get called. Returns 410 // true if some work was done. 411 bool DeletePendingTasks(); 412 413 // Post a task to our incomming queue. 414 void PostTask_Helper(const tracked_objects::Location& from_here, Task* task, 415 int64 delay_ms, bool nestable); 416 417 // base::MessagePump::Delegate methods: 418 virtual bool DoWork(); 419 virtual bool DoDelayedWork(base::Time* next_delayed_work_time); 420 virtual bool DoIdleWork(); 421 422 // Start recording histogram info about events and action IF it was enabled 423 // and IF the statistics recorder can accept a registration of our histogram. 424 void StartHistogrammer(); 425 426 // Add occurence of event to our histogram, so that we can see what is being 427 // done in a specific MessageLoop instance (i.e., specific thread). 428 // If message_histogram_ is NULL, this is a no-op. 429 void HistogramEvent(int event); 430 431 Type type_; 432 433 // A list of tasks that need to be processed by this instance. Note that 434 // this queue is only accessed (push/pop) by our current thread. 435 TaskQueue work_queue_; 436 437 // Contains delayed tasks, sorted by their 'delayed_run_time' property. 438 DelayedTaskQueue delayed_work_queue_; 439 440 // A queue of non-nestable tasks that we had to defer because when it came 441 // time to execute them we were in a nested message loop. They will execute 442 // once we're out of nested message loops. 443 TaskQueue deferred_non_nestable_work_queue_; 444 445 scoped_refptr<base::MessagePump> pump_; 446 447 ObserverList<DestructionObserver> destruction_observers_; 448 449 // A recursion block that prevents accidentally running additonal tasks when 450 // insider a (accidentally induced?) nested message pump. 451 bool nestable_tasks_allowed_; 452 453 bool exception_restoration_; 454 455 std::string thread_name_; 456 // A profiling histogram showing the counts of various messages and events. 457 scoped_refptr<Histogram> message_histogram_; 458 459 // A null terminated list which creates an incoming_queue of tasks that are 460 // aquired under a mutex for processing on this instance's thread. These tasks 461 // have not yet been sorted out into items for our work_queue_ vs items that 462 // will be handled by the TimerManager. 463 TaskQueue incoming_queue_; 464 // Protect access to incoming_queue_. 465 Lock incoming_queue_lock_; 466 467 RunState* state_; 468 469#if defined(OS_WIN) 470 base::TimeTicks high_resolution_timer_expiration_; 471#endif 472 473 // The next sequence number to use for delayed tasks. 474 int next_sequence_num_; 475 476 ObserverList<TaskObserver> task_observers_; 477 478 DISALLOW_COPY_AND_ASSIGN(MessageLoop); 479}; 480 481//----------------------------------------------------------------------------- 482// MessageLoopForUI extends MessageLoop with methods that are particular to a 483// MessageLoop instantiated with TYPE_UI. 484// 485// This class is typically used like so: 486// MessageLoopForUI::current()->...call some method... 487// 488class MessageLoopForUI : public MessageLoop { 489 public: 490 MessageLoopForUI() : MessageLoop(TYPE_UI) { 491 } 492 493 // Returns the MessageLoopForUI of the current thread. 494 static MessageLoopForUI* current() { 495 MessageLoop* loop = MessageLoop::current(); 496 //DCHECK_EQ(MessageLoop::TYPE_UI, loop->type()); 497 return static_cast<MessageLoopForUI*>(loop); 498 } 499 500#if defined(OS_WIN) 501 void DidProcessMessage(const MSG& message); 502#endif // defined(OS_WIN) 503 504#if !defined(OS_MACOSX) 505 // Please see message_pump_win/message_pump_glib for definitions of these 506 // methods. 507 void AddObserver(Observer* observer); 508 void RemoveObserver(Observer* observer); 509 void Run(Dispatcher* dispatcher); 510 511 protected: 512 // TODO(rvargas): Make this platform independent. 513 base::MessagePumpForUI* pump_ui() { 514 return static_cast<base::MessagePumpForUI*>(pump_.get()); 515 } 516#endif // !defined(OS_MACOSX) 517}; 518 519// Do not add any member variables to MessageLoopForUI! This is important b/c 520// MessageLoopForUI is often allocated via MessageLoop(TYPE_UI). Any extra 521// data that you need should be stored on the MessageLoop's pump_ instance. 522COMPILE_ASSERT(sizeof(MessageLoop) == sizeof(MessageLoopForUI), 523 MessageLoopForUI_should_not_have_extra_member_variables); 524 525//----------------------------------------------------------------------------- 526// MessageLoopForIO extends MessageLoop with methods that are particular to a 527// MessageLoop instantiated with TYPE_IO. 528// 529// This class is typically used like so: 530// MessageLoopForIO::current()->...call some method... 531// 532class MessageLoopForIO : public MessageLoop { 533 public: 534#if defined(OS_WIN) 535 typedef base::MessagePumpForIO::IOHandler IOHandler; 536 typedef base::MessagePumpForIO::IOContext IOContext; 537 typedef base::MessagePumpForIO::IOObserver IOObserver; 538#elif defined(OS_POSIX) 539 typedef base::MessagePumpLibevent::Watcher Watcher; 540 typedef base::MessagePumpLibevent::FileDescriptorWatcher 541 FileDescriptorWatcher; 542 typedef base::MessagePumpLibevent::IOObserver IOObserver; 543 544 enum Mode { 545 WATCH_READ = base::MessagePumpLibevent::WATCH_READ, 546 WATCH_WRITE = base::MessagePumpLibevent::WATCH_WRITE, 547 WATCH_READ_WRITE = base::MessagePumpLibevent::WATCH_READ_WRITE 548 }; 549 550#endif 551 552 MessageLoopForIO() : MessageLoop(TYPE_IO) { 553 } 554 555 // Returns the MessageLoopForIO of the current thread. 556 static MessageLoopForIO* current() { 557 MessageLoop* loop = MessageLoop::current(); 558 //DCHECK_EQ(MessageLoop::TYPE_IO, loop->type()); 559 return static_cast<MessageLoopForIO*>(loop); 560 } 561 562 void AddIOObserver(IOObserver* io_observer) { 563 pump_io()->AddIOObserver(io_observer); 564 } 565 566 void RemoveIOObserver(IOObserver* io_observer) { 567 pump_io()->RemoveIOObserver(io_observer); 568 } 569 570#if defined(OS_WIN) 571 // Please see MessagePumpWin for definitions of these methods. 572 void RegisterIOHandler(HANDLE file_handle, IOHandler* handler); 573 bool WaitForIOCompletion(DWORD timeout, IOHandler* filter); 574 575 protected: 576 // TODO(rvargas): Make this platform independent. 577 base::MessagePumpForIO* pump_io() { 578 return static_cast<base::MessagePumpForIO*>(pump_.get()); 579 } 580 581#elif defined(OS_POSIX) 582 // Please see MessagePumpLibevent for definition. 583 bool WatchFileDescriptor(int fd, 584 bool persistent, 585 Mode mode, 586 FileDescriptorWatcher *controller, 587 Watcher *delegate); 588 589 private: 590 base::MessagePumpLibevent* pump_io() { 591 return static_cast<base::MessagePumpLibevent*>(pump_.get()); 592 } 593#endif // defined(OS_POSIX) 594}; 595 596// Do not add any member variables to MessageLoopForIO! This is important b/c 597// MessageLoopForIO is often allocated via MessageLoop(TYPE_IO). Any extra 598// data that you need should be stored on the MessageLoop's pump_ instance. 599COMPILE_ASSERT(sizeof(MessageLoop) == sizeof(MessageLoopForIO), 600 MessageLoopForIO_should_not_have_extra_member_variables); 601 602#endif // BASE_MESSAGE_LOOP_H_ 603