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.
5 #ifndef BASE_MESSAGE_PUMP_WIN_H_
6 #define BASE_MESSAGE_PUMP_WIN_H_
12 #include "base/lock.h"
13 #include "base/message_pump.h"
14 #include "base/observer_list.h"
15 #include "base/scoped_handle.h"
16 #include "base/time.h"
20 // MessagePumpWin serves as the base for specialized versions of the MessagePump
21 // for Windows. It provides basic functionality like handling of observers and
22 // controlling the lifetime of the message pump.
23 class MessagePumpWin
: public MessagePump
{
25 // An Observer is an object that receives global notifications from the
28 // NOTE: An Observer implementation should be extremely fast!
32 virtual ~Observer() {}
34 // This method is called before processing a message.
35 // The message may be undefined in which case msg.message is 0
36 virtual void WillProcessMessage(const MSG
& msg
) = 0;
38 // This method is called when control returns from processing a UI message.
39 // The message may be undefined in which case msg.message is 0
40 virtual void DidProcessMessage(const MSG
& msg
) = 0;
43 // Dispatcher is used during a nested invocation of Run to dispatch events.
44 // If Run is invoked with a non-NULL Dispatcher, MessageLoop does not
45 // dispatch events (or invoke TranslateMessage), rather every message is
46 // passed to Dispatcher's Dispatch method for dispatch. It is up to the
47 // Dispatcher to dispatch, or not, the event.
49 // The nested loop is exited by either posting a quit, or returning false
53 virtual ~Dispatcher() {}
54 // Dispatches the event. If true is returned processing continues as
55 // normal. If false is returned, the nested loop exits immediately.
56 virtual bool Dispatch(const MSG
& msg
) = 0;
59 MessagePumpWin() : have_work_(0), state_(NULL
) {}
60 virtual ~MessagePumpWin() {}
62 // Add an Observer, which will start receiving notifications immediately.
63 void AddObserver(Observer
* observer
);
65 // Remove an Observer. It is safe to call this method while an Observer is
66 // receiving a notification callback.
67 void RemoveObserver(Observer
* observer
);
69 // Give a chance to code processing additional messages to notify the
70 // message loop observers that another message has been processed.
71 void WillProcessMessage(const MSG
& msg
);
72 void DidProcessMessage(const MSG
& msg
);
74 // Like MessagePump::Run, but MSG objects are routed through dispatcher.
75 void RunWithDispatcher(Delegate
* delegate
, Dispatcher
* dispatcher
);
77 // MessagePump methods:
78 virtual void Run(Delegate
* delegate
) { RunWithDispatcher(delegate
, NULL
); }
84 Dispatcher
* dispatcher
;
86 // Used to flag that the current Run() invocation should return ASAP.
89 // Used to count how many Run() invocations are on the stack.
93 virtual void DoRunLoop() = 0;
94 int GetCurrentDelay() const;
96 ObserverList
<Observer
> observers_
;
98 // The time at which delayed work should run.
99 Time delayed_work_time_
;
101 // A boolean value used to indicate if there is a kMsgDoWork message pending
102 // in the Windows Message queue. There is at most one such message, and it
103 // can drive execution of tasks when a native message pump is running.
106 // State for the current invocation of Run.
110 //-----------------------------------------------------------------------------
111 // MessagePumpForUI extends MessagePumpWin with methods that are particular to a
112 // MessageLoop instantiated with TYPE_UI.
114 // MessagePumpForUI implements a "traditional" Windows message pump. It contains
115 // a nearly infinite loop that peeks out messages, and then dispatches them.
116 // Intermixed with those peeks are callouts to DoWork for pending tasks, and
117 // DoDelayedWork for pending timers. When there are no events to be serviced,
118 // this pump goes into a wait state. In most cases, this message pump handles
121 // However, when a task, or windows event, invokes on the stack a native dialog
122 // box or such, that window typically provides a bare bones (native?) message
123 // pump. That bare-bones message pump generally supports little more than a
124 // peek of the Windows message queue, followed by a dispatch of the peeked
125 // message. MessageLoop extends that bare-bones message pump to also service
126 // Tasks, at the cost of some complexity.
128 // The basic structure of the extension (refered to as a sub-pump) is that a
129 // special message, kMsgHaveWork, is repeatedly injected into the Windows
130 // Message queue. Each time the kMsgHaveWork message is peeked, checks are
131 // made for an extended set of events, including the availability of Tasks to
134 // After running a task, the special message kMsgHaveWork is again posted to
135 // the Windows Message queue, ensuring a future time slice for processing a
136 // future event. To prevent flooding the Windows Message queue, care is taken
137 // to be sure that at most one kMsgHaveWork message is EVER pending in the
138 // Window's Message queue.
140 // There are a few additional complexities in this system where, when there are
141 // no Tasks to run, this otherwise infinite stream of messages which drives the
142 // sub-pump is halted. The pump is automatically re-started when Tasks are
145 // A second complexity is that the presence of this stream of posted tasks may
146 // prevent a bare-bones message pump from ever peeking a WM_PAINT or WM_TIMER.
147 // Such paint and timer events always give priority to a posted message, such as
148 // kMsgHaveWork messages. As a result, care is taken to do some peeking in
149 // between the posting of each kMsgHaveWork message (i.e., after kMsgHaveWork
150 // is peeked, and before a replacement kMsgHaveWork is posted).
152 // NOTE: Although it may seem odd that messages are used to start and stop this
153 // flow (as opposed to signaling objects, etc.), it should be understood that
154 // the native message pump will *only* respond to messages. As a result, it is
155 // an excellent choice. It is also helpful that the starter messages that are
156 // placed in the queue when new task arrive also awakens DoRunLoop.
158 class MessagePumpForUI
: public MessagePumpWin
{
160 // The application-defined code passed to the hook procedure.
161 static const int kMessageFilterCode
= 0x5001;
164 virtual ~MessagePumpForUI();
166 // MessagePump methods:
167 virtual void ScheduleWork();
168 virtual void ScheduleDelayedWork(const Time
& delayed_work_time
);
170 // Applications can call this to encourage us to process all pending WM_PAINT
171 // messages. This method will process all paint messages the Windows Message
172 // queue can provide, up to some fixed number (to avoid any infinite loops).
173 void PumpOutPendingPaintMessages();
176 static LRESULT CALLBACK
WndProcThunk(
177 HWND hwnd
, UINT message
, WPARAM wparam
, LPARAM lparam
);
178 virtual void DoRunLoop();
179 void InitMessageWnd();
181 void HandleWorkMessage();
182 void HandleTimerMessage();
183 bool ProcessNextWindowsMessage();
184 bool ProcessMessageHelper(const MSG
& msg
);
185 bool ProcessPumpReplacementMessage();
187 // A hidden message-only window.
191 //-----------------------------------------------------------------------------
192 // MessagePumpForIO extends MessagePumpWin with methods that are particular to a
193 // MessageLoop instantiated with TYPE_IO. This version of MessagePump does not
194 // deal with Windows mesagges, and instead has a Run loop based on Completion
195 // Ports so it is better suited for IO operations.
197 class MessagePumpForIO
: public MessagePumpWin
{
201 // Clients interested in receiving OS notifications when asynchronous IO
202 // operations complete should implement this interface and register themselves
203 // with the message pump.
206 // // Use only when there are no user's buffers involved on the actual IO,
207 // // so that all the cleanup can be done by the message pump.
208 // class MyFile : public IOHandler {
211 // context_ = new IOContext;
212 // context_->handler = this;
213 // message_pump->RegisterIOHandler(file_, this);
217 // // By setting the handler to NULL, we're asking for this context
218 // // to be deleted when received, without calling back to us.
219 // context_->handler = NULL;
224 // virtual void OnIOCompleted(IOContext* context, DWORD bytes_transfered,
230 // // The only buffer required for this operation is the overlapped
232 // ConnectNamedPipe(file_, &context_->overlapped);
236 // IOContext* context_;
241 // class MyFile : public IOHandler {
244 // message_pump->RegisterIOHandler(file_, this);
246 // // Plus some code to make sure that this destructor is not called
247 // // while there are pending IO operations.
250 // virtual void OnIOCompleted(IOContext* context, DWORD bytes_transfered,
257 // IOContext* context = new IOContext;
258 // // This is not used for anything. It just prevents the context from
259 // // being considered "abandoned".
260 // context->handler = this;
261 // ReadFile(file_, buffer, num_bytes, &read, &context->overlapped);
267 // Same as the previous example, except that in order to deal with the
268 // requirement stated for the destructor, the class calls WaitForIOCompletion
269 // from the destructor to block until all IO finishes.
272 // message_pump->WaitForIOCompletion(INFINITE, this);
277 virtual ~IOHandler() {}
278 // This will be called once the pending IO operation associated with
279 // |context| completes. |error| is the Win32 error code of the IO operation
280 // (ERROR_SUCCESS if there was no error). |bytes_transfered| will be zero
282 virtual void OnIOCompleted(IOContext
* context
, DWORD bytes_transfered
,
286 // The extended context that should be used as the base structure on every
287 // overlapped IO operation. |handler| must be set to the registered IOHandler
288 // for the given file when the operation is started, and it can be set to NULL
289 // before the operation completes to indicate that the handler should not be
290 // called anymore, and instead, the IOContext should be deleted when the OS
291 // notifies the completion of this operation. Please remember that any buffers
292 // involved with an IO operation should be around until the callback is
293 // received, so this technique can only be used for IO that do not involve
294 // additional buffers (other than the overlapped structure itself).
296 OVERLAPPED overlapped
;
301 virtual ~MessagePumpForIO() {}
303 // MessagePump methods:
304 virtual void ScheduleWork();
305 virtual void ScheduleDelayedWork(const Time
& delayed_work_time
);
307 // Register the handler to be used when asynchronous IO for the given file
308 // completes. The registration persists as long as |file_handle| is valid, so
309 // |handler| must be valid as long as there is pending IO for the given file.
310 void RegisterIOHandler(HANDLE file_handle
, IOHandler
* handler
);
312 // Waits for the next IO completion that should be processed by |filter|, for
313 // up to |timeout| milliseconds. Return true if any IO operation completed,
314 // regardless of the involved handler, and false if the timeout expired. If
315 // the completion port received any message and the involved IO handler
316 // matches |filter|, the callback is called before returning from this code;
317 // if the handler is not the one that we are looking for, the callback will
318 // be postponed for another time, so reentrancy problems can be avoided.
319 // External use of this method should be reserved for the rare case when the
320 // caller is willing to allow pausing regular task dispatching on this thread.
321 bool WaitForIOCompletion(DWORD timeout
, IOHandler
* filter
);
327 DWORD bytes_transfered
;
331 virtual void DoRunLoop();
333 bool MatchCompletedIOItem(IOHandler
* filter
, IOItem
* item
);
334 bool GetIOItem(DWORD timeout
, IOItem
* item
);
335 bool ProcessInternalIOItem(const IOItem
& item
);
337 // The completion port associated with this thread.
339 // This list will be empty almost always. It stores IO completions that have
340 // not been delivered yet because somebody was doing cleanup.
341 std::list
<IOItem
> completed_io_
;
346 #endif // BASE_MESSAGE_PUMP_WIN_H_