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_MESSAGE_PUMP_WIN_H_ | |
6 #define BASE_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_pump.h" | |
16 #include "base/message_pump_dispatcher.h" | |
17 #include "base/message_pump_observer.h" | |
18 #include "base/observer_list.h" | |
19 #include "base/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_PUMP_WIN_H_ | |
OLD | NEW |