tor-browser

message_pump_win.h (13761B)

---

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
// Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef BASE_MESSAGE_PUMP_WIN_H_
#define BASE_MESSAGE_PUMP_WIN_H_

#include <windows.h>

#include <list>

#include "base/message_pump.h"
#include "base/observer_list.h"
#include "base/scoped_handle.h"
#include "base/time.h"

namespace base {

// MessagePumpWin serves as the base for specialized versions of the MessagePump
// for Windows. It provides basic functionality like handling of observers and
// controlling the lifetime of the message pump.
class MessagePumpWin : public MessagePump {
public:
 // An Observer is an object that receives global notifications from the
 // MessageLoop.
 //
 // NOTE: An Observer implementation should be extremely fast!
 //
 class Observer {
  public:
   virtual ~Observer() {}

   // This method is called before processing a message.
   // The message may be undefined in which case msg.message is 0
   virtual void WillProcessMessage(const MSG& msg) = 0;

   // This method is called when control returns from processing a UI message.
   // The message may be undefined in which case msg.message is 0
   virtual void DidProcessMessage(const MSG& msg) = 0;
 };

 // Dispatcher is used during a nested invocation of Run to dispatch events.
 // If Run is invoked with a non-NULL Dispatcher, MessageLoop does not
 // dispatch events (or invoke TranslateMessage), rather every message is
 // passed to Dispatcher's Dispatch method for dispatch. It is up to the
 // Dispatcher to dispatch, or not, the event.
 //
 // The nested loop is exited by either posting a quit, or returning false
 // from Dispatch.
 class Dispatcher {
  public:
   virtual ~Dispatcher() {}
   // Dispatches the event. If true is returned processing continues as
   // normal. If false is returned, the nested loop exits immediately.
   virtual bool Dispatch(const MSG& msg) = 0;
 };

 MessagePumpWin() : have_work_(0), state_(NULL) {}
 virtual ~MessagePumpWin() {}

 // Add an Observer, which will start receiving notifications immediately.
 void AddObserver(Observer* observer);

 // Remove an Observer.  It is safe to call this method while an Observer is
 // receiving a notification callback.
 void RemoveObserver(Observer* observer);

 // Give a chance to code processing additional messages to notify the
 // message loop observers that another message has been processed.
 void WillProcessMessage(const MSG& msg);
 void DidProcessMessage(const MSG& msg);

 // Like MessagePump::Run, but MSG objects are routed through dispatcher.
 void RunWithDispatcher(Delegate* delegate, Dispatcher* dispatcher);

 // MessagePump methods:
 virtual void Run(Delegate* delegate) { RunWithDispatcher(delegate, NULL); }
 virtual void Quit();

protected:
 struct RunState {
   Delegate* delegate;
   Dispatcher* dispatcher;

   // Used to flag that the current Run() invocation should return ASAP.
   bool should_quit;

   // Used to count how many Run() invocations are on the stack.
   int run_depth;
 };

 virtual void DoRunLoop() = 0;
 int GetCurrentDelay() const;

 ObserverList<Observer> observers_;

 // The time at which delayed work should run.
 TimeTicks delayed_work_time_;

 // A boolean value used to indicate if there is a kMsgDoWork message pending
 // in the Windows Message queue.  There is at most one such message, and it
 // can drive execution of tasks when a native message pump is running.
 LONG have_work_;

 // State for the current invocation of Run.
 RunState* state_;
};

//-----------------------------------------------------------------------------
// MessagePumpForUI extends MessagePumpWin with methods that are particular to a
// MessageLoop instantiated with TYPE_UI.
//
// MessagePumpForUI implements a "traditional" Windows message pump. It contains
// a nearly infinite loop that peeks out messages, and then dispatches them.
// Intermixed with those peeks are callouts to DoWork for pending tasks, and
// DoDelayedWork for pending timers. When there are no events to be serviced,
// this pump goes into a wait state. In most cases, this message pump handles
// all processing.
//
// However, when a task, or windows event, invokes on the stack a native dialog
// box or such, that window typically provides a bare bones (native?) message
// pump.  That bare-bones message pump generally supports little more than a
// peek of the Windows message queue, followed by a dispatch of the peeked
// message.  MessageLoop extends that bare-bones message pump to also service
// Tasks, at the cost of some complexity.
//
// The basic structure of the extension (refered to as a sub-pump) is that a
// special message, kMsgHaveWork, is repeatedly injected into the Windows
// Message queue.  Each time the kMsgHaveWork message is peeked, checks are
// made for an extended set of events, including the availability of Tasks to
// run.
//
// After running a task, the special message kMsgHaveWork is again posted to
// the Windows Message queue, ensuring a future time slice for processing a
// future event.  To prevent flooding the Windows Message queue, care is taken
// to be sure that at most one kMsgHaveWork message is EVER pending in the
// Window's Message queue.
//
// There are a few additional complexities in this system where, when there are
// no Tasks to run, this otherwise infinite stream of messages which drives the
// sub-pump is halted.  The pump is automatically re-started when Tasks are
// queued.
//
// A second complexity is that the presence of this stream of posted tasks may
// prevent a bare-bones message pump from ever peeking a WM_PAINT or WM_TIMER.
// Such paint and timer events always give priority to a posted message, such as
// kMsgHaveWork messages.  As a result, care is taken to do some peeking in
// between the posting of each kMsgHaveWork message (i.e., after kMsgHaveWork
// is peeked, and before a replacement kMsgHaveWork is posted).
//
// NOTE: Although it may seem odd that messages are used to start and stop this
// flow (as opposed to signaling objects, etc.), it should be understood that
// the native message pump will *only* respond to messages.  As a result, it is
// an excellent choice.  It is also helpful that the starter messages that are
// placed in the queue when new task arrive also awakens DoRunLoop.
//
class MessagePumpForUI : public MessagePumpWin {
public:
 MessagePumpForUI();
 virtual ~MessagePumpForUI();

 // MessagePump methods:
 virtual void ScheduleWork();
 virtual void ScheduleDelayedWork(const TimeTicks& delayed_work_time);

 // Applications can call this to encourage us to process all pending WM_PAINT
 // messages.  This method will process all paint messages the Windows Message
 // queue can provide, up to some fixed number (to avoid any infinite loops).
 void PumpOutPendingPaintMessages();

protected:
 virtual void DoRunLoop();

 bool ProcessNextWindowsMessage();
 void InitMessageWnd();
 void WaitForWork();
 void HandleWorkMessage();
 void HandleTimerMessage();
 bool ProcessMessageHelper(const MSG& msg);
 bool ProcessPumpReplacementMessage();

 // A hidden message-only window.
 HWND message_hwnd_;

private:
 static LRESULT CALLBACK WndProcThunk(HWND hwnd, UINT message, WPARAM wparam,
                                      LPARAM lparam);
};

//-----------------------------------------------------------------------------
// MessagePumpForIO extends MessagePumpWin with methods that are particular to a
// MessageLoop instantiated with TYPE_IO. This version of MessagePump does not
// deal with Windows mesagges, and instead has a Run loop based on Completion
// Ports so it is better suited for IO operations.
//
class MessagePumpForIO : public MessagePumpWin {
public:
 struct IOContext;

 // Clients interested in receiving OS notifications when asynchronous IO
 // operations complete should implement this interface and register themselves
 // with the message pump.
 //
 // Typical use #1:
 //   // Use only when there are no user's buffers involved on the actual IO,
 //   // so that all the cleanup can be done by the message pump.
 //   class MyFile : public IOHandler {
 //     MyFile() {
 //       ...
 //       context_ = new IOContext;
 //       context_->handler = this;
 //       message_pump->RegisterIOHandler(file_, this);
 //     }
 //     ~MyFile() {
 //       if (pending_) {
 //         // By setting the handler to NULL, we're asking for this context
 //         // to be deleted when received, without calling back to us.
 //         context_->handler = NULL;
 //       } else {
 //         delete context_;
 //      }
 //     }
 //     virtual void OnIOCompleted(IOContext* context, DWORD bytes_transfered,
 //                                DWORD error) {
 //         pending_ = false;
 //     }
 //     void DoSomeIo() {
 //       ...
 //       // The only buffer required for this operation is the overlapped
 //       // structure.
 //       ConnectNamedPipe(file_, &context_->overlapped);
 //       pending_ = true;
 //     }
 //     bool pending_;
 //     IOContext* context_;
 //     HANDLE file_;
 //   };
 //
 // Typical use #2:
 //   class MyFile : public IOHandler {
 //     MyFile() {
 //       ...
 //       message_pump->RegisterIOHandler(file_, this);
 //     }
 //     // Plus some code to make sure that this destructor is not called
 //     // while there are pending IO operations.
 //     ~MyFile() {
 //     }
 //     virtual void OnIOCompleted(IOContext* context, DWORD bytes_transfered,
 //                                DWORD error) {
 //       ...
 //       delete context;
 //     }
 //     void DoSomeIo() {
 //       ...
 //       IOContext* context = new IOContext;
 //       // This is not used for anything. It just prevents the context from
 //       // being considered "abandoned".
 //       context->handler = this;
 //       ReadFile(file_, buffer, num_bytes, &read, &context->overlapped);
 //     }
 //     HANDLE file_;
 //   };
 //
 // Typical use #3:
 // Same as the previous example, except that in order to deal with the
 // requirement stated for the destructor, the class calls WaitForIOCompletion
 // from the destructor to block until all IO finishes.
 //     ~MyFile() {
 //       while(pending_)
 //         message_pump->WaitForIOCompletion(INFINITE, this);
 //     }
 //
 class IOHandler {
  public:
   virtual ~IOHandler() {}
   // This will be called once the pending IO operation associated with
   // |context| completes. |error| is the Win32 error code of the IO operation
   // (ERROR_SUCCESS if there was no error). |bytes_transfered| will be zero
   // on error.
   virtual void OnIOCompleted(IOContext* context, DWORD bytes_transfered,
                              DWORD error) = 0;
 };

 // The extended context that should be used as the base structure on every
 // overlapped IO operation. |handler| must be set to the registered IOHandler
 // for the given file when the operation is started, and it can be set to NULL
 // before the operation completes to indicate that the handler should not be
 // called anymore, and instead, the IOContext should be deleted when the OS
 // notifies the completion of this operation. Please remember that any buffers
 // involved with an IO operation should be around until the callback is
 // received, so this technique can only be used for IO that do not involve
 // additional buffers (other than the overlapped structure itself).
 struct IOContext {
   OVERLAPPED overlapped;
   IOHandler* handler;
 };

 MessagePumpForIO();
 virtual ~MessagePumpForIO() {}

 // MessagePump methods:
 virtual void ScheduleWork();
 virtual void ScheduleDelayedWork(const TimeTicks& delayed_work_time);

 // Register the handler to be used when asynchronous IO for the given file
 // completes. The registration persists as long as |file_handle| is valid, so
 // |handler| must be valid as long as there is pending IO for the given file.
 void RegisterIOHandler(HANDLE file_handle, IOHandler* handler);

 // Waits for the next IO completion that should be processed by |filter|, for
 // up to |timeout| milliseconds. Return true if any IO operation completed,
 // regardless of the involved handler, and false if the timeout expired. If
 // the completion port received any message and the involved IO handler
 // matches |filter|, the callback is called before returning from this code;
 // if the handler is not the one that we are looking for, the callback will
 // be postponed for another time, so reentrancy problems can be avoided.
 // External use of this method should be reserved for the rare case when the
 // caller is willing to allow pausing regular task dispatching on this thread.
 bool WaitForIOCompletion(DWORD timeout, IOHandler* filter);

private:
 struct IOItem {
   IOHandler* handler;
   IOContext* context;
   DWORD bytes_transfered;
   DWORD error;
 };

 virtual void DoRunLoop();
 void WaitForWork();
 bool MatchCompletedIOItem(IOHandler* filter, IOItem* item);
 bool GetIOItem(DWORD timeout, IOItem* item);
 bool ProcessInternalIOItem(const IOItem& item);

 // The completion port associated with this thread.
 ScopedHandle port_;
 // This list will be empty almost always. It stores IO completions that have
 // not been delivered yet because somebody was doing cleanup.
 std::list<IOItem> completed_io_;
};

}  // namespace base

#endif  // BASE_MESSAGE_PUMP_WIN_H_