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_MESSAGE_LOOP_MESSAGE_PUMP_WIN_H_ 6 #define BASE_MESSAGE_LOOP_MESSAGE_PUMP_WIN_H_ 7 8 #include <windows.h> 9 10 #include <list> 11 12 #include "base/base_export.h" 13 #include "base/basictypes.h" 14 #include "base/memory/scoped_ptr.h" 15 #include "base/message_loop/message_pump.h" 16 #include "base/message_loop/message_pump_dispatcher.h" 17 #include "base/message_loop/message_pump_observer.h" 18 #include "base/observer_list.h" 19 #include "base/time/time.h" 20 #include "base/win/scoped_handle.h" 21 22 namespace base { 23 24 // MessagePumpWin serves as the base for specialized versions of the MessagePump 25 // for Windows. It provides basic functionality like handling of observers and 26 // controlling the lifetime of the message pump. 27 class BASE_EXPORT MessagePumpWin : public MessagePump { 28 public: 29 MessagePumpWin() : have_work_(0), state_(NULL) {} 30 virtual ~MessagePumpWin() {} 31 32 // Add an Observer, which will start receiving notifications immediately. 33 void AddObserver(MessagePumpObserver* observer); 34 35 // Remove an Observer. It is safe to call this method while an Observer is 36 // receiving a notification callback. 37 void RemoveObserver(MessagePumpObserver* observer); 38 39 // Give a chance to code processing additional messages to notify the 40 // message loop observers that another message has been processed. 41 void WillProcessMessage(const MSG& msg); 42 void DidProcessMessage(const MSG& msg); 43 44 // Like MessagePump::Run, but MSG objects are routed through dispatcher. 45 void RunWithDispatcher(Delegate* delegate, MessagePumpDispatcher* dispatcher); 46 47 // MessagePump methods: 48 virtual void Run(Delegate* delegate) { RunWithDispatcher(delegate, NULL); } 49 virtual void Quit(); 50 51 protected: 52 struct RunState { 53 Delegate* delegate; 54 MessagePumpDispatcher* dispatcher; 55 56 // Used to flag that the current Run() invocation should return ASAP. 57 bool should_quit; 58 59 // Used to count how many Run() invocations are on the stack. 60 int run_depth; 61 }; 62 63 virtual void DoRunLoop() = 0; 64 int GetCurrentDelay() const; 65 66 ObserverList<MessagePumpObserver> observers_; 67 68 // The time at which delayed work should run. 69 TimeTicks delayed_work_time_; 70 71 // A boolean value used to indicate if there is a kMsgDoWork message pending 72 // in the Windows Message queue. There is at most one such message, and it 73 // can drive execution of tasks when a native message pump is running. 74 LONG have_work_; 75 76 // State for the current invocation of Run. 77 RunState* state_; 78 }; 79 80 //----------------------------------------------------------------------------- 81 // MessagePumpForUI extends MessagePumpWin with methods that are particular to a 82 // MessageLoop instantiated with TYPE_UI. 83 // 84 // MessagePumpForUI implements a "traditional" Windows message pump. It contains 85 // a nearly infinite loop that peeks out messages, and then dispatches them. 86 // Intermixed with those peeks are callouts to DoWork for pending tasks, and 87 // DoDelayedWork for pending timers. When there are no events to be serviced, 88 // this pump goes into a wait state. In most cases, this message pump handles 89 // all processing. 90 // 91 // However, when a task, or windows event, invokes on the stack a native dialog 92 // box or such, that window typically provides a bare bones (native?) message 93 // pump. That bare-bones message pump generally supports little more than a 94 // peek of the Windows message queue, followed by a dispatch of the peeked 95 // message. MessageLoop extends that bare-bones message pump to also service 96 // Tasks, at the cost of some complexity. 97 // 98 // The basic structure of the extension (refered to as a sub-pump) is that a 99 // special message, kMsgHaveWork, is repeatedly injected into the Windows 100 // Message queue. Each time the kMsgHaveWork message is peeked, checks are 101 // made for an extended set of events, including the availability of Tasks to 102 // run. 103 // 104 // After running a task, the special message kMsgHaveWork is again posted to 105 // the Windows Message queue, ensuring a future time slice for processing a 106 // future event. To prevent flooding the Windows Message queue, care is taken 107 // to be sure that at most one kMsgHaveWork message is EVER pending in the 108 // Window's Message queue. 109 // 110 // There are a few additional complexities in this system where, when there are 111 // no Tasks to run, this otherwise infinite stream of messages which drives the 112 // sub-pump is halted. The pump is automatically re-started when Tasks are 113 // queued. 114 // 115 // A second complexity is that the presence of this stream of posted tasks may 116 // prevent a bare-bones message pump from ever peeking a WM_PAINT or WM_TIMER. 117 // Such paint and timer events always give priority to a posted message, such as 118 // kMsgHaveWork messages. As a result, care is taken to do some peeking in 119 // between the posting of each kMsgHaveWork message (i.e., after kMsgHaveWork 120 // is peeked, and before a replacement kMsgHaveWork is posted). 121 // 122 // NOTE: Although it may seem odd that messages are used to start and stop this 123 // flow (as opposed to signaling objects, etc.), it should be understood that 124 // the native message pump will *only* respond to messages. As a result, it is 125 // an excellent choice. It is also helpful that the starter messages that are 126 // placed in the queue when new task arrive also awakens DoRunLoop. 127 // 128 class BASE_EXPORT MessagePumpForUI : public MessagePumpWin { 129 public: 130 // A MessageFilter implements the common Peek/Translate/Dispatch code to deal 131 // with windows messages. 132 // This abstraction is used to inject TSF message peeking. See 133 // TextServicesMessageFilter. 134 class BASE_EXPORT MessageFilter { 135 public: 136 virtual ~MessageFilter() {} 137 // Implements the functionality exposed by the OS through PeekMessage. 138 virtual BOOL DoPeekMessage(MSG* msg, 139 HWND window_handle, 140 UINT msg_filter_min, 141 UINT msg_filter_max, 142 UINT remove_msg) { 143 return PeekMessage(msg, window_handle, msg_filter_min, msg_filter_max, 144 remove_msg); 145 } 146 // Returns true if |message| was consumed by the filter and no extra 147 // processing is required. If this method returns false, it is the 148 // responsibility of the caller to ensure that normal processing takes 149 // place. 150 // The priority to consume messages is the following: 151 // - Native Windows' message filter (CallMsgFilter). 152 // - MessageFilter::ProcessMessage. 153 // - MessagePumpDispatcher. 154 // - TranslateMessage / DispatchMessage. 155 virtual bool ProcessMessage(const MSG& msg) { return false;} 156 }; 157 // The application-defined code passed to the hook procedure. 158 static const int kMessageFilterCode = 0x5001; 159 160 MessagePumpForUI(); 161 virtual ~MessagePumpForUI(); 162 163 // Sets a new MessageFilter. MessagePumpForUI takes ownership of 164 // |message_filter|. When SetMessageFilter is called, old MessageFilter is 165 // deleted. 166 void SetMessageFilter(scoped_ptr<MessageFilter> message_filter); 167 168 // MessagePump methods: 169 virtual void ScheduleWork(); 170 virtual void ScheduleDelayedWork(const TimeTicks& delayed_work_time); 171 172 // Applications can call this to encourage us to process all pending WM_PAINT 173 // messages. This method will process all paint messages the Windows Message 174 // queue can provide, up to some fixed number (to avoid any infinite loops). 175 void PumpOutPendingPaintMessages(); 176 177 private: 178 static LRESULT CALLBACK WndProcThunk(HWND window_handle, 179 UINT message, 180 WPARAM wparam, 181 LPARAM lparam); 182 virtual void DoRunLoop(); 183 void InitMessageWnd(); 184 void WaitForWork(); 185 void HandleWorkMessage(); 186 void HandleTimerMessage(); 187 bool ProcessNextWindowsMessage(); 188 bool ProcessMessageHelper(const MSG& msg); 189 bool ProcessPumpReplacementMessage(); 190 191 // Atom representing the registered window class. 192 ATOM atom_; 193 194 // A hidden message-only window. 195 HWND message_hwnd_; 196 197 scoped_ptr<MessageFilter> message_filter_; 198 }; 199 200 //----------------------------------------------------------------------------- 201 // MessagePumpForIO extends MessagePumpWin with methods that are particular to a 202 // MessageLoop instantiated with TYPE_IO. This version of MessagePump does not 203 // deal with Windows mesagges, and instead has a Run loop based on Completion 204 // Ports so it is better suited for IO operations. 205 // 206 class BASE_EXPORT MessagePumpForIO : public MessagePumpWin { 207 public: 208 struct IOContext; 209 210 // Clients interested in receiving OS notifications when asynchronous IO 211 // operations complete should implement this interface and register themselves 212 // with the message pump. 213 // 214 // Typical use #1: 215 // // Use only when there are no user's buffers involved on the actual IO, 216 // // so that all the cleanup can be done by the message pump. 217 // class MyFile : public IOHandler { 218 // MyFile() { 219 // ... 220 // context_ = new IOContext; 221 // context_->handler = this; 222 // message_pump->RegisterIOHandler(file_, this); 223 // } 224 // ~MyFile() { 225 // if (pending_) { 226 // // By setting the handler to NULL, we're asking for this context 227 // // to be deleted when received, without calling back to us. 228 // context_->handler = NULL; 229 // } else { 230 // delete context_; 231 // } 232 // } 233 // virtual void OnIOCompleted(IOContext* context, DWORD bytes_transfered, 234 // DWORD error) { 235 // pending_ = false; 236 // } 237 // void DoSomeIo() { 238 // ... 239 // // The only buffer required for this operation is the overlapped 240 // // structure. 241 // ConnectNamedPipe(file_, &context_->overlapped); 242 // pending_ = true; 243 // } 244 // bool pending_; 245 // IOContext* context_; 246 // HANDLE file_; 247 // }; 248 // 249 // Typical use #2: 250 // class MyFile : public IOHandler { 251 // MyFile() { 252 // ... 253 // message_pump->RegisterIOHandler(file_, this); 254 // } 255 // // Plus some code to make sure that this destructor is not called 256 // // while there are pending IO operations. 257 // ~MyFile() { 258 // } 259 // virtual void OnIOCompleted(IOContext* context, DWORD bytes_transfered, 260 // DWORD error) { 261 // ... 262 // delete context; 263 // } 264 // void DoSomeIo() { 265 // ... 266 // IOContext* context = new IOContext; 267 // // This is not used for anything. It just prevents the context from 268 // // being considered "abandoned". 269 // context->handler = this; 270 // ReadFile(file_, buffer, num_bytes, &read, &context->overlapped); 271 // } 272 // HANDLE file_; 273 // }; 274 // 275 // Typical use #3: 276 // Same as the previous example, except that in order to deal with the 277 // requirement stated for the destructor, the class calls WaitForIOCompletion 278 // from the destructor to block until all IO finishes. 279 // ~MyFile() { 280 // while(pending_) 281 // message_pump->WaitForIOCompletion(INFINITE, this); 282 // } 283 // 284 class IOHandler { 285 public: 286 virtual ~IOHandler() {} 287 // This will be called once the pending IO operation associated with 288 // |context| completes. |error| is the Win32 error code of the IO operation 289 // (ERROR_SUCCESS if there was no error). |bytes_transfered| will be zero 290 // on error. 291 virtual void OnIOCompleted(IOContext* context, DWORD bytes_transfered, 292 DWORD error) = 0; 293 }; 294 295 // An IOObserver is an object that receives IO notifications from the 296 // MessagePump. 297 // 298 // NOTE: An IOObserver implementation should be extremely fast! 299 class IOObserver { 300 public: 301 IOObserver() {} 302 303 virtual void WillProcessIOEvent() = 0; 304 virtual void DidProcessIOEvent() = 0; 305 306 protected: 307 virtual ~IOObserver() {} 308 }; 309 310 // The extended context that should be used as the base structure on every 311 // overlapped IO operation. |handler| must be set to the registered IOHandler 312 // for the given file when the operation is started, and it can be set to NULL 313 // before the operation completes to indicate that the handler should not be 314 // called anymore, and instead, the IOContext should be deleted when the OS 315 // notifies the completion of this operation. Please remember that any buffers 316 // involved with an IO operation should be around until the callback is 317 // received, so this technique can only be used for IO that do not involve 318 // additional buffers (other than the overlapped structure itself). 319 struct IOContext { 320 OVERLAPPED overlapped; 321 IOHandler* handler; 322 }; 323 324 MessagePumpForIO(); 325 virtual ~MessagePumpForIO() {} 326 327 // MessagePump methods: 328 virtual void ScheduleWork(); 329 virtual void ScheduleDelayedWork(const TimeTicks& delayed_work_time); 330 331 // Register the handler to be used when asynchronous IO for the given file 332 // completes. The registration persists as long as |file_handle| is valid, so 333 // |handler| must be valid as long as there is pending IO for the given file. 334 void RegisterIOHandler(HANDLE file_handle, IOHandler* handler); 335 336 // Register the handler to be used to process job events. The registration 337 // persists as long as the job object is live, so |handler| must be valid 338 // until the job object is destroyed. Returns true if the registration 339 // succeeded, and false otherwise. 340 bool RegisterJobObject(HANDLE job_handle, IOHandler* handler); 341 342 // Waits for the next IO completion that should be processed by |filter|, for 343 // up to |timeout| milliseconds. Return true if any IO operation completed, 344 // regardless of the involved handler, and false if the timeout expired. If 345 // the completion port received any message and the involved IO handler 346 // matches |filter|, the callback is called before returning from this code; 347 // if the handler is not the one that we are looking for, the callback will 348 // be postponed for another time, so reentrancy problems can be avoided. 349 // External use of this method should be reserved for the rare case when the 350 // caller is willing to allow pausing regular task dispatching on this thread. 351 bool WaitForIOCompletion(DWORD timeout, IOHandler* filter); 352 353 void AddIOObserver(IOObserver* obs); 354 void RemoveIOObserver(IOObserver* obs); 355 356 private: 357 struct IOItem { 358 IOHandler* handler; 359 IOContext* context; 360 DWORD bytes_transfered; 361 DWORD error; 362 363 // In some cases |context| can be a non-pointer value casted to a pointer. 364 // |has_valid_io_context| is true if |context| is a valid IOContext 365 // pointer, and false otherwise. 366 bool has_valid_io_context; 367 }; 368 369 virtual void DoRunLoop(); 370 void WaitForWork(); 371 bool MatchCompletedIOItem(IOHandler* filter, IOItem* item); 372 bool GetIOItem(DWORD timeout, IOItem* item); 373 bool ProcessInternalIOItem(const IOItem& item); 374 void WillProcessIOEvent(); 375 void DidProcessIOEvent(); 376 377 // Converts an IOHandler pointer to a completion port key. 378 // |has_valid_io_context| specifies whether completion packets posted to 379 // |handler| will have valid OVERLAPPED pointers. 380 static ULONG_PTR HandlerToKey(IOHandler* handler, bool has_valid_io_context); 381 382 // Converts a completion port key to an IOHandler pointer. 383 static IOHandler* KeyToHandler(ULONG_PTR key, bool* has_valid_io_context); 384 385 // The completion port associated with this thread. 386 win::ScopedHandle port_; 387 // This list will be empty almost always. It stores IO completions that have 388 // not been delivered yet because somebody was doing cleanup. 389 std::list<IOItem> completed_io_; 390 391 ObserverList<IOObserver> io_observers_; 392 }; 393 394 } // namespace base 395 396 #endif // BASE_MESSAGE_LOOP_MESSAGE_PUMP_WIN_H_ 397