tor-browser

message_pump_win.h (12028B)

---

// Copyright 2012 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef BASE_MESSAGE_LOOP_MESSAGE_PUMP_WIN_H_
#define BASE_MESSAGE_LOOP_MESSAGE_PUMP_WIN_H_

#include <windows.h>

#include <atomic>
#include <memory>

#include "base/base_export.h"
#include "base/compiler_specific.h"
#include "base/location.h"
#include "base/memory/raw_ptr.h"
#include "base/memory/raw_ptr_exclusion.h"
#include "base/message_loop/message_pump.h"
#include "base/observer_list.h"
#include "base/threading/thread_checker.h"
#include "base/time/time.h"
#include "base/win/message_window.h"
#include "base/win/scoped_handle.h"
#include "third_party/abseil-cpp/absl/types/optional.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 BASE_EXPORT MessagePumpWin : public MessagePump {
public:
 MessagePumpWin();
 ~MessagePumpWin() override;

 // MessagePump methods:
 void Run(Delegate* delegate) override;
 void Quit() override;

protected:
 struct RunState {
   explicit RunState(Delegate* delegate_in) : delegate(delegate_in) {}

   const raw_ptr<Delegate> delegate;

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

   // Set to true if this Run() is nested within another Run().
   bool is_nested = false;
 };

 virtual void DoRunLoop() = 0;

 // True iff:
 //   * MessagePumpForUI: there's a kMsgDoWork message pending in the Windows
 //     Message queue. i.e. when:
 //      a. The pump is about to wakeup from idle.
 //      b. The pump is about to enter a nested native loop and a
 //         ScopedAllowApplicationTasksInNativeNestedLoop was instantiated to
 //         allow application tasks to execute in that nested loop
 //         (ScopedAllowApplicationTasksInNativeNestedLoop invokes
 //         ScheduleWork()).
 //      c. While in a native (nested) loop : HandleWorkMessage() =>
 //         ProcessPumpReplacementMessage() invokes ScheduleWork() before
 //         processing a native message to guarantee this pump will get another
 //         time slice if it goes into native Windows code and enters a native
 //         nested loop. This is different from (b.) because we're not yet
 //         processing an application task at the current run level and
 //         therefore are expected to keep pumping application tasks without
 //         necessitating a ScopedAllowApplicationTasksInNativeNestedLoop.
 //
 //   * MessagePumpforIO: there's a dummy IO completion item with |this| as an
 //     lpCompletionKey in the queue which is about to wakeup
 //     WaitForIOCompletion(). MessagePumpForIO doesn't support nesting so
 //     this is simpler than MessagePumpForUI.
 std::atomic_bool work_scheduled_{false};

 // State for the current invocation of Run(). null if not running.
 // This field is not a raw_ptr<> because it was filtered by the rewriter for:
 // #addr-of
 RAW_PTR_EXCLUSION RunState* run_state_ = nullptr;

 THREAD_CHECKER(bound_thread_);
};

//-----------------------------------------------------------------------------
// 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. 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 (referred 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 BASE_EXPORT MessagePumpForUI : public MessagePumpWin {
public:
 MessagePumpForUI();
 ~MessagePumpForUI() override;

 // MessagePump methods:
 void ScheduleWork() override;
 void ScheduleDelayedWork(
     const Delegate::NextWorkInfo& next_work_info) override;

 // An observer interface to give the scheduler an opportunity to log
 // information about MSGs before and after they are dispatched.
 class BASE_EXPORT Observer {
  public:
   virtual void WillDispatchMSG(const MSG& msg) = 0;
   virtual void DidDispatchMSG(const MSG& msg) = 0;
 };

 void AddObserver(Observer* observer);
 void RemoveObserver(Observer* obseerver);

private:
 bool MessageCallback(UINT message,
                      WPARAM wparam,
                      LPARAM lparam,
                      LRESULT* result);
 void DoRunLoop() override;
 NOINLINE NOT_TAIL_CALLED void WaitForWork(
     Delegate::NextWorkInfo next_work_info);
 void HandleWorkMessage();
 void HandleTimerMessage();
 void ScheduleNativeTimer(Delegate::NextWorkInfo next_work_info);
 void KillNativeTimer();
 bool ProcessNextWindowsMessage();
 bool ProcessMessageHelper(const MSG& msg);
 bool ProcessPumpReplacementMessage();

 base::win::MessageWindow message_window_;

 // Non-nullopt if there's currently a native timer installed. If so, it
 // indicates when the timer is set to fire and can be used to avoid setting
 // redundant timers.
 absl::optional<TimeTicks> installed_native_timer_;

 // This will become true when a native loop takes our kMsgHaveWork out of the
 // system queue. It will be reset to false whenever DoRunLoop regains control.
 // Used to decide whether ScheduleDelayedWork() should start a native timer.
 bool in_native_loop_ = false;

 ObserverList<Observer>::Unchecked observers_;
};

//-----------------------------------------------------------------------------
// 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 BASE_EXPORT MessagePumpForIO : public MessagePumpWin {
public:
 struct BASE_EXPORT IOContext {
   IOContext();
   OVERLAPPED overlapped;
 };

 // 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:
 //   class MyFile : public IOHandler {
 //     MyFile() : IOHandler(FROM_HERE) {
 //       ...
 //       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;
 //       ReadFile(file_, buffer, num_bytes, &read, &context);
 //     }
 //     HANDLE file_;
 //   };
 //
 // Typical use #2:
 // 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 BASE_EXPORT IOHandler {
  public:
   explicit IOHandler(const Location& from_here);
   virtual ~IOHandler();

   IOHandler(const IOHandler&) = delete;
   IOHandler& operator=(const IOHandler&) = delete;

   // 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;

   const Location& io_handler_location() { return io_handler_location_; }

  private:
   const Location io_handler_location_;
 };

 MessagePumpForIO();
 ~MessagePumpForIO() override;

 // MessagePump methods:
 void ScheduleWork() override;
 void ScheduleDelayedWork(
     const Delegate::NextWorkInfo& next_work_info) override;

 // 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.
 HRESULT RegisterIOHandler(HANDLE file_handle, IOHandler* handler);

 // Register the handler to be used to process job events. The registration
 // persists as long as the job object is live, so |handler| must be valid
 // until the job object is destroyed. Returns true if the registration
 // succeeded, and false otherwise.
 bool RegisterJobObject(HANDLE job_handle, IOHandler* handler);

private:
 struct IOItem {
   raw_ptr<IOHandler> handler;
   raw_ptr<IOContext> context;
   DWORD bytes_transfered;
   DWORD error;
 };

 void DoRunLoop() override;
 NOINLINE NOT_TAIL_CALLED void WaitForWork(
     Delegate::NextWorkInfo next_work_info);
 bool GetIOItem(DWORD timeout, IOItem* item);
 bool ProcessInternalIOItem(const IOItem& item);
 // Waits for the next IO completion for up to |timeout| milliseconds.
 // Return true if any IO operation completed, and false if the timeout
 // expired. If the completion port received any messages, the associated
 // handlers will have been invoked before returning from this code.
 bool WaitForIOCompletion(DWORD timeout);

 // The completion port associated with this thread.
 win::ScopedHandle port_;
};

}  // namespace base

#endif  // BASE_MESSAGE_LOOP_MESSAGE_PUMP_WIN_H_