base/message_loop/message_pump.h - chromiumos/platform/libchrome - Git at Google

 // 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_H_
 #define BASE_MESSAGE_LOOP_MESSAGE_PUMP_H_

 #include <memory>
 #include <utility>

 #include "base/base_export.h"
 #include "base/check.h"
 #include "base/check_op.h"
 #include "base/memory/raw_ptr_exclusion.h"
 #include "base/message_loop/message_pump_type.h"
 #include "base/sequence_checker.h"
 #include "base/time/time.h"
 #include "build/build_config.h"

 namespace base {

 class TimeTicks;

 class BASE_EXPORT MessagePump {
  public:
   using MessagePumpFactory = std::unique_ptr<MessagePump>();
   // Uses the given base::MessagePumpFactory to override the default MessagePump
   // implementation for 'MessagePumpType::UI'. May only be called once.
   static void OverrideMessagePumpForUIFactory(MessagePumpFactory* factory);

   // Returns true if the MessagePumpForUI has been overidden.
   static bool IsMessagePumpForUIFactoryOveridden();

   static void InitializeFeatures();

   // Manage the state of |kAlignWakeUps| and the leeway of the process.
   static void OverrideAlignWakeUpsState(bool enabled, TimeDelta leeway);
   static void ResetAlignWakeUpsState();
   static bool GetAlignWakeUpsEnabled();
   static TimeDelta GetLeewayIgnoringThreadOverride();
   static TimeDelta GetLeewayForCurrentThread();

   // Creates the default MessagePump based on |type|. Caller owns return value.
   static std::unique_ptr<MessagePump> Create(MessagePumpType type);

   // Please see the comments above the Run method for an illustration of how
   // these delegate methods are used.
   class BASE_EXPORT Delegate {
    public:
     virtual ~Delegate() = default;

     struct NextWorkInfo {
       // Helper to extract a TimeDelta for pumps that need a
       // timeout-till-next-task.
       TimeDelta remaining_delay() const {
         DCHECK(!delayed_run_time.is_null() && !delayed_run_time.is_max());
         DCHECK_GE(TimeTicks::Now(), recent_now);
         return delayed_run_time - recent_now;
       }

       // Helper to verify if the next task is ready right away.
       bool is_immediate() const { return delayed_run_time.is_null(); }

       // The next PendingTask's |delayed_run_time|. is_null() if there's extra
       // work to run immediately. is_max() if there are no more immediate nor
       // delayed tasks.
       TimeTicks delayed_run_time;

       // |leeway| determines the preferred time range for scheduling
       // work. A larger leeway provides more freedom to schedule work at
       // an optimal time for power consumption. This field is ignored
       // for immediate work.
       TimeDelta leeway;

       // A recent view of TimeTicks::Now(). Only valid if |delayed_run_time|
       // isn't null nor max. MessagePump impls should use remaining_delay()
       // instead of resampling Now() if they wish to sleep for a TimeDelta.
       TimeTicks recent_now;

       // If true, native messages should be processed before executing more work
       // from the Delegate. This is an optional hint; not all message pumps
       // implement this.
       bool yield_to_native = false;
     };

     // Executes an immediate task or a ripe delayed task. Returns information
     // about when DoWork() should be called again. If the returned NextWorkInfo
     // is_immediate(), DoWork() must be invoked again shortly. Else, DoWork()
     // must be invoked at |NextWorkInfo::delayed_run_time| or when
     // ScheduleWork() is invoked, whichever comes first. Redundant/spurious
     // invocations of DoWork() outside of those requirements are tolerated.
     // DoIdleWork() will not be called so long as this returns a NextWorkInfo
     // which is_immediate().
     virtual NextWorkInfo DoWork() = 0;

     // Called from within Run just before the message pump goes to sleep.
     // Returns true to indicate that idle work was done; in which case Run()
     // should resume with calling DoWork(). Returning false means the pump
     // should now wait.
     virtual bool DoIdleWork() = 0;

     class ScopedDoWorkItem {
      public:
       ScopedDoWorkItem() : outer_(nullptr), work_item_depth_(0) {}

       ~ScopedDoWorkItem() {
         if (outer_) {
           outer_->OnEndWorkItem(work_item_depth_);
         }
       }

       ScopedDoWorkItem(ScopedDoWorkItem&& rhs)
           : outer_(std::exchange(rhs.outer_, nullptr)),
             work_item_depth_(rhs.work_item_depth_) {}
       ScopedDoWorkItem& operator=(ScopedDoWorkItem&& rhs) {
         // We should only ever go from an empty ScopedDoWorkItem to an
         // initialized one, or from an initialized one to an empty one.
         CHECK_NE(IsNull(), rhs.IsNull());
         // Since we're overwriting this ScopedDoWorkItem, we need to record its
         // destruction.
         if (outer_) {
           outer_->OnEndWorkItem(work_item_depth_);
         }

         work_item_depth_ = rhs.work_item_depth_;
         outer_ = std::exchange(rhs.outer_, nullptr);
         return *this;
       }

       bool IsNull() { return !outer_; }

      private:
       friend Delegate;

       explicit ScopedDoWorkItem(Delegate* outer) : outer_(outer) {
         outer_->OnBeginWorkItem();
         work_item_depth_ = outer_->RunDepth();
       }

       // `outer_` is not a raw_ptr<...> for performance reasons (based on
       // analysis of sampling profiler data and tab_search:top100:2020).
       RAW_PTR_EXCLUSION Delegate* outer_;

       // Records the run level at which this DoWorkItem was created to allow
       // detection of exits of nested loops.
       int work_item_depth_;
     };

     // Called before a unit of work is executed. This allows reports
     // about individual units of work to be produced. The unit of work ends when
     // the returned ScopedDoWorkItem goes out of scope.
     // TODO(crbug.com/40580088): Place calls for all platforms. Without this,
     // some state like the top-level "ThreadController active" trace event will
     // not be correct when work is performed.
     [[nodiscard]] ScopedDoWorkItem BeginWorkItem() {
       return ScopedDoWorkItem(this);
     }

     // Called before the message pump starts waiting for work. This indicates
     // that the message pump is idle (out of application work and ideally out of
     // native work -- if it can tell).
     virtual void BeforeWait() = 0;

     // May be called when starting to process native work and it is guaranteed
     // that DoWork() will be called again before sleeping. Allows the delegate
     // to skip unnecessary ScheduleWork() calls.
     virtual void BeginNativeWorkBeforeDoWork() = 0;

     // Returns the nesting level at which the Delegate is currently running.
     virtual int RunDepth() = 0;

    private:
     // Called upon entering/exiting a ScopedDoWorkItem.
     virtual void OnBeginWorkItem() = 0;
     virtual void OnEndWorkItem(int work_item_depth) = 0;
   };

   MessagePump();
   virtual ~MessagePump();

   // The Run method is called to enter the message pump's run loop.
   //
   // Within the method, the message pump is responsible for processing native
   // messages as well as for giving cycles to the delegate periodically. The
   // message pump should take care to mix delegate callbacks with native message
   // processing so neither type of event starves the other of cycles. Each call
   // to a delegate function is considered the beginning of a new "unit of work".
   //
   // The anatomy of a typical run loop:
   //
   //   for (;;) {
   //     bool did_native_work = false;
   //     {
   //       auto scoped_do_work_item = state_->delegate->BeginWorkItem();
   //       did_native_work = DoNativeWork();
   //     }
   //     if (should_quit_)
   //       break;
   //
   //     Delegate::NextWorkInfo next_work_info = delegate->DoWork();
   //     if (should_quit_)
   //       break;
   //
   //     if (did_native_work || next_work_info.is_immediate())
   //       continue;
   //
   //     bool did_idle_work = delegate_->DoIdleWork();
   //     if (should_quit_)
   //       break;
   //
   //     if (did_idle_work)
   //       continue;
   //
   //     WaitForWork();
   //   }
   //

   // Here, DoNativeWork is some private method of the message pump that is
   // responsible for dispatching the next UI message or notifying the next IO
   // completion (for example).  WaitForWork is a private method that simply
   // blocks until there is more work of any type to do.
   //
   // Notice that the run loop cycles between calling DoNativeWork and DoWork
   // methods. This helps ensure that none of these work queues starve the
   // others. This is important for message pumps that are used to drive
   // animations, for example.
   //
   // Notice also that after each callout to foreign code, the run loop checks to
   // see if it should quit.  The Quit method is responsible for setting this
   // flag.  No further work is done once the quit flag is set.
   //
   // NOTE 1: Run may be called reentrantly from any of the callouts to foreign
   // code (internal work, DoWork, DoIdleWork). As a result, DoWork and
   // DoIdleWork must be reentrant.
   //
   // NOTE 2: Run implementations must arrange for DoWork to be invoked as
   // expected if a callout to foreign code enters a message pump outside their
   // control. For example, the MessageBox API on Windows pumps UI messages. If
   // the MessageBox API is called (indirectly) from within Run, it is expected
   // that DoWork will be invoked from within that call in response to
   // ScheduleWork or as requested by the last NextWorkInfo returned by DoWork.
   // The MessagePump::Delegate may then elect to do nested work or not depending
   // on its policy in that context. Regardless of that decision (and return
   // value of the nested DoWork() call), DoWork() will be invoked again when the
   // nested loop unwinds.
   virtual void Run(Delegate* delegate) = 0;

   // Quit immediately from the most recently entered run loop.  This method may
   // only be used on the thread that called Run.
   virtual void Quit() = 0;

   // Schedule a DoWork callback to happen reasonably soon.  Does nothing if a
   // DoWork callback is already scheduled. Once this call is made, DoWork is
   // guaranteed to be called repeatedly at least until it returns a
   // non-immediate NextWorkInfo. This call can be expensive and callers should
   // attempt not to invoke it again before a non-immediate NextWorkInfo was
   // returned from DoWork(). Thread-safe (and callers should avoid holding a
   // Lock at all cost while making this call as some platforms' priority
   // boosting features have been observed to cause the caller to get descheduled
   // : https://crbug.com/890978).
   virtual void ScheduleWork() = 0;

   // Schedule a DoWork callback to happen at the specified time, cancelling any
   // pending callback scheduled by this method. This method may only be used on
   // the thread that called Run.
   //
   // It isn't necessary to call this during normal execution, as the pump wakes
   // up as requested by the return value of DoWork().
   // TODO(crbug.com/40594269): Determine if this must be called to ensure that
   // delayed tasks run when a message pump outside the control of Run is
   // entered.
   virtual void ScheduleDelayedWork(
       const Delegate::NextWorkInfo& next_work_info) = 0;

   // Returns an adjusted |run_time| based on alignment policies of the pump.
   virtual TimeTicks AdjustDelayedRunTime(TimeTicks earliest_time,
                                          TimeTicks run_time,
                                          TimeTicks latest_time);

   // Requests the pump to handle either the likely imminent creation (`true`) or
   // destruction (`false`) of a native nested loop in which application tasks
   // are desired to be run. The pump should override and return `true` if it
   // supports this call and has scheduled work in response. The default
   // implementation returns `false` and does nothing.
   virtual bool HandleNestedNativeLoopWithApplicationTasks(
       bool application_tasks_desired);
 };

 }  // namespace base

 #endif  // BASE_MESSAGE_LOOP_MESSAGE_PUMP_H_
	// 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_H_
	#define BASE_MESSAGE_LOOP_MESSAGE_PUMP_H_

	#include <memory>
	#include <utility>

	#include "base/base_export.h"
	#include "base/check.h"
	#include "base/check_op.h"
	#include "base/memory/raw_ptr_exclusion.h"
	#include "base/message_loop/message_pump_type.h"
	#include "base/sequence_checker.h"
	#include "base/time/time.h"
	#include "build/build_config.h"

	namespace base {

	class TimeTicks;

	class BASE_EXPORT MessagePump {
	public:
	using MessagePumpFactory = std::unique_ptr<MessagePump>();
	// Uses the given base::MessagePumpFactory to override the default MessagePump
	// implementation for 'MessagePumpType::UI'. May only be called once.
	static void OverrideMessagePumpForUIFactory(MessagePumpFactory* factory);

	// Returns true if the MessagePumpForUI has been overidden.
	static bool IsMessagePumpForUIFactoryOveridden();

	static void InitializeFeatures();

	// Manage the state of \|kAlignWakeUps\| and the leeway of the process.
	static void OverrideAlignWakeUpsState(bool enabled, TimeDelta leeway);
	static void ResetAlignWakeUpsState();
	static bool GetAlignWakeUpsEnabled();
	static TimeDelta GetLeewayIgnoringThreadOverride();
	static TimeDelta GetLeewayForCurrentThread();

	// Creates the default MessagePump based on \|type\|. Caller owns return value.
	static std::unique_ptr<MessagePump> Create(MessagePumpType type);

	// Please see the comments above the Run method for an illustration of how
	// these delegate methods are used.
	class BASE_EXPORT Delegate {
	public:
	virtual ~Delegate() = default;

	struct NextWorkInfo {
	// Helper to extract a TimeDelta for pumps that need a
	// timeout-till-next-task.
	TimeDelta remaining_delay() const {
	DCHECK(!delayed_run_time.is_null() && !delayed_run_time.is_max());
	DCHECK_GE(TimeTicks::Now(), recent_now);
	return delayed_run_time - recent_now;
	}

	// Helper to verify if the next task is ready right away.
	bool is_immediate() const { return delayed_run_time.is_null(); }

	// The next PendingTask's \|delayed_run_time\|. is_null() if there's extra
	// work to run immediately. is_max() if there are no more immediate nor
	// delayed tasks.
	TimeTicks delayed_run_time;

	// \|leeway\| determines the preferred time range for scheduling
	// work. A larger leeway provides more freedom to schedule work at
	// an optimal time for power consumption. This field is ignored
	// for immediate work.
	TimeDelta leeway;

	// A recent view of TimeTicks::Now(). Only valid if \|delayed_run_time\|
	// isn't null nor max. MessagePump impls should use remaining_delay()
	// instead of resampling Now() if they wish to sleep for a TimeDelta.
	TimeTicks recent_now;

	// If true, native messages should be processed before executing more work
	// from the Delegate. This is an optional hint; not all message pumps
	// implement this.
	bool yield_to_native = false;
	};

	// Executes an immediate task or a ripe delayed task. Returns information
	// about when DoWork() should be called again. If the returned NextWorkInfo
	// is_immediate(), DoWork() must be invoked again shortly. Else, DoWork()
	// must be invoked at \|NextWorkInfo::delayed_run_time\| or when
	// ScheduleWork() is invoked, whichever comes first. Redundant/spurious
	// invocations of DoWork() outside of those requirements are tolerated.
	// DoIdleWork() will not be called so long as this returns a NextWorkInfo
	// which is_immediate().
	virtual NextWorkInfo DoWork() = 0;

	// Called from within Run just before the message pump goes to sleep.
	// Returns true to indicate that idle work was done; in which case Run()
	// should resume with calling DoWork(). Returning false means the pump
	// should now wait.
	virtual bool DoIdleWork() = 0;

	class ScopedDoWorkItem {
	public:
	ScopedDoWorkItem() : outer_(nullptr), work_item_depth_(0) {}

	~ScopedDoWorkItem() {
	if (outer_) {
	outer_->OnEndWorkItem(work_item_depth_);
	}
	}

	ScopedDoWorkItem(ScopedDoWorkItem&& rhs)
	: outer_(std::exchange(rhs.outer_, nullptr)),
	work_item_depth_(rhs.work_item_depth_) {}
	ScopedDoWorkItem& operator=(ScopedDoWorkItem&& rhs) {
	// We should only ever go from an empty ScopedDoWorkItem to an
	// initialized one, or from an initialized one to an empty one.
	CHECK_NE(IsNull(), rhs.IsNull());
	// Since we're overwriting this ScopedDoWorkItem, we need to record its
	// destruction.
	if (outer_) {
	outer_->OnEndWorkItem(work_item_depth_);
	}

	work_item_depth_ = rhs.work_item_depth_;
	outer_ = std::exchange(rhs.outer_, nullptr);
	return *this;
	}

	bool IsNull() { return !outer_; }

	private:
	friend Delegate;

	explicit ScopedDoWorkItem(Delegate* outer) : outer_(outer) {
	outer_->OnBeginWorkItem();
	work_item_depth_ = outer_->RunDepth();
	}

	// `outer_` is not a raw_ptr<...> for performance reasons (based on
	// analysis of sampling profiler data and tab_search:top100:2020).
	RAW_PTR_EXCLUSION Delegate* outer_;

	// Records the run level at which this DoWorkItem was created to allow
	// detection of exits of nested loops.
	int work_item_depth_;
	};

	// Called before a unit of work is executed. This allows reports
	// about individual units of work to be produced. The unit of work ends when
	// the returned ScopedDoWorkItem goes out of scope.
	// TODO(crbug.com/40580088): Place calls for all platforms. Without this,
	// some state like the top-level "ThreadController active" trace event will
	// not be correct when work is performed.
	[[nodiscard]] ScopedDoWorkItem BeginWorkItem() {
	return ScopedDoWorkItem(this);
	}

	// Called before the message pump starts waiting for work. This indicates
	// that the message pump is idle (out of application work and ideally out of
	// native work -- if it can tell).
	virtual void BeforeWait() = 0;

	// May be called when starting to process native work and it is guaranteed
	// that DoWork() will be called again before sleeping. Allows the delegate
	// to skip unnecessary ScheduleWork() calls.
	virtual void BeginNativeWorkBeforeDoWork() = 0;

	// Returns the nesting level at which the Delegate is currently running.
	virtual int RunDepth() = 0;

	private:
	// Called upon entering/exiting a ScopedDoWorkItem.
	virtual void OnBeginWorkItem() = 0;
	virtual void OnEndWorkItem(int work_item_depth) = 0;
	};

	MessagePump();
	virtual ~MessagePump();

	// The Run method is called to enter the message pump's run loop.
	//
	// Within the method, the message pump is responsible for processing native
	// messages as well as for giving cycles to the delegate periodically. The
	// message pump should take care to mix delegate callbacks with native message
	// processing so neither type of event starves the other of cycles. Each call
	// to a delegate function is considered the beginning of a new "unit of work".
	//
	// The anatomy of a typical run loop:
	//
	// for (;;) {
	// bool did_native_work = false;
	// {
	// auto scoped_do_work_item = state_->delegate->BeginWorkItem();
	// did_native_work = DoNativeWork();
	// }
	// if (should_quit_)
	// break;
	//
	// Delegate::NextWorkInfo next_work_info = delegate->DoWork();
	// if (should_quit_)
	// break;
	//
	// if (did_native_work \|\| next_work_info.is_immediate())
	// continue;
	//
	// bool did_idle_work = delegate_->DoIdleWork();
	// if (should_quit_)
	// break;
	//
	// if (did_idle_work)
	// continue;
	//
	// WaitForWork();
	// }
	//

	// Here, DoNativeWork is some private method of the message pump that is
	// responsible for dispatching the next UI message or notifying the next IO
	// completion (for example). WaitForWork is a private method that simply
	// blocks until there is more work of any type to do.
	//
	// Notice that the run loop cycles between calling DoNativeWork and DoWork
	// methods. This helps ensure that none of these work queues starve the
	// others. This is important for message pumps that are used to drive
	// animations, for example.
	//
	// Notice also that after each callout to foreign code, the run loop checks to
	// see if it should quit. The Quit method is responsible for setting this
	// flag. No further work is done once the quit flag is set.
	//
	// NOTE 1: Run may be called reentrantly from any of the callouts to foreign
	// code (internal work, DoWork, DoIdleWork). As a result, DoWork and
	// DoIdleWork must be reentrant.
	//
	// NOTE 2: Run implementations must arrange for DoWork to be invoked as
	// expected if a callout to foreign code enters a message pump outside their
	// control. For example, the MessageBox API on Windows pumps UI messages. If
	// the MessageBox API is called (indirectly) from within Run, it is expected
	// that DoWork will be invoked from within that call in response to
	// ScheduleWork or as requested by the last NextWorkInfo returned by DoWork.
	// The MessagePump::Delegate may then elect to do nested work or not depending
	// on its policy in that context. Regardless of that decision (and return
	// value of the nested DoWork() call), DoWork() will be invoked again when the
	// nested loop unwinds.
	virtual void Run(Delegate* delegate) = 0;

	// Quit immediately from the most recently entered run loop. This method may
	// only be used on the thread that called Run.
	virtual void Quit() = 0;

	// Schedule a DoWork callback to happen reasonably soon. Does nothing if a
	// DoWork callback is already scheduled. Once this call is made, DoWork is
	// guaranteed to be called repeatedly at least until it returns a
	// non-immediate NextWorkInfo. This call can be expensive and callers should
	// attempt not to invoke it again before a non-immediate NextWorkInfo was
	// returned from DoWork(). Thread-safe (and callers should avoid holding a
	// Lock at all cost while making this call as some platforms' priority
	// boosting features have been observed to cause the caller to get descheduled
	// : https://crbug.com/890978).
	virtual void ScheduleWork() = 0;

	// Schedule a DoWork callback to happen at the specified time, cancelling any
	// pending callback scheduled by this method. This method may only be used on
	// the thread that called Run.
	//
	// It isn't necessary to call this during normal execution, as the pump wakes
	// up as requested by the return value of DoWork().
	// TODO(crbug.com/40594269): Determine if this must be called to ensure that
	// delayed tasks run when a message pump outside the control of Run is
	// entered.
	virtual void ScheduleDelayedWork(
	const Delegate::NextWorkInfo& next_work_info) = 0;

	// Returns an adjusted \|run_time\| based on alignment policies of the pump.
	virtual TimeTicks AdjustDelayedRunTime(TimeTicks earliest_time,
	TimeTicks run_time,
	TimeTicks latest_time);

	// Requests the pump to handle either the likely imminent creation (`true`) or
	// destruction (`false`) of a native nested loop in which application tasks
	// are desired to be run. The pump should override and return `true` if it
	// supports this call and has scheduled work in response. The default
	// implementation returns `false` and does nothing.
	virtual bool HandleNestedNativeLoopWithApplicationTasks(
	bool application_tasks_desired);
	};

	} // namespace base

	#endif // BASE_MESSAGE_LOOP_MESSAGE_PUMP_H_