The Tor Browser / file revision

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

 #define BASE_MESSAGE_PUMP_H_

 #include "base/ref_counted.h"

 namespace base {

 class TimeTicks;

 class MessagePump : public RefCountedThreadSafe<MessagePump> {

  public:

   // Please see the comments above the Run method for an illustration of how

   // these delegate methods are used.

   class Delegate {

    public:

     virtual ~Delegate() {}

     // Called from within Run in response to ScheduleWork or when the message

     // pump would otherwise call DoDelayedWork.  Returns true to indicate that

     // work was done.  DoDelayedWork will not be called if DoWork returns true.

     virtual bool DoWork() = 0;

     // Called from within Run in response to ScheduleDelayedWork or when the

     // message pump would otherwise sleep waiting for more work.  Returns true

     // to indicate that delayed work was done.  DoIdleWork will not be called

     // if DoDelayedWork returns true.  Upon return |next_delayed_work_time|

     // indicates the time when DoDelayedWork should be called again.  If

     // |next_delayed_work_time| is null (per Time::is_null), then the queue of

     // future delayed work (timer events) is currently empty, and no additional

     // calls to this function need to be scheduled.

     virtual bool DoDelayedWork(TimeTicks* next_delayed_work_time) = 0;

     // Called from within Run just before the message pump goes to sleep.

     // Returns true to indicate that idle work was done.

     virtual bool DoIdleWork() = 0;

   };

   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.

   //

   // The anatomy of a typical run loop:

   //

   //   for (;;) {

   //     bool did_work = DoInternalWork();

   //     if (should_quit_)

   //       break;

   //

   //     did_work |= delegate_->DoWork();

   //     if (should_quit_)

   //       break;

   //

   //     did_work |= delegate_->DoDelayedWork();

   //     if (should_quit_)

   //       break;

   //

   //     if (did_work)

   //       continue;

   //

   //     did_work = delegate_->DoIdleWork();

   //     if (should_quit_)

   //       break;

   //

   //     if (did_work)

   //       continue;

   //

   //     WaitForWork();

   //   }

   //

   // Here, DoInternalWork 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 DoInternalWork, DoWork,

   // and DoDelayedWork methods.  This helps ensure that neither work queue

   // starves the other.  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: Care must be taken to handle Run being called again from within any

   // of the callouts to foreign code.  Native message pumps may also need to

   // deal with other native message pumps being run outside their control

   // (e.g., the MessageBox API on Windows pumps UI messages!).  To be specific,

   // the callouts (DoWork and DoDelayedWork) MUST still be provided even in

   // nested sub-loops that are "seemingly" outside the control of this message

   // pump.  DoWork in particular must never be starved for time slices unless

   // it returns false (meaning it has run out of things to do).

   //

   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.  This method may be called from any

   // thread.  Once this call is made, DoWork should not be "starved" at least

   // until it returns a value of false.

   virtual void ScheduleWork() = 0;

   // This method may only called from the thread that called Run.

   //

   // Ensure that DoWork will be called if a nested loop is entered.

   // If a MessagePump can already guarantee that DoWork will be called

   // "reasonably soon", this method can be a no-op to avoid expensive

   // atomic tests and/or syscalls required for ScheduleWork().

   virtual void ScheduleWorkForNestedLoop() { ScheduleWork(); };

   // Schedule a DoDelayedWork callback to happen at the specified time,

   // cancelling any pending DoDelayedWork callback.  This method may only be

   // used on the thread that called Run.

   virtual void ScheduleDelayedWork(const TimeTicks& delayed_work_time) = 0;

 };

 }  // namespace base

 #endif  // BASE_MESSAGE_PUMP_H_