michael@0: // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
michael@0: // Use of this source code is governed by a BSD-style license that can be
michael@0: // found in the LICENSE file.
michael@0: 
michael@0: #ifndef BASE_MESSAGE_PUMP_H_
michael@0: #define BASE_MESSAGE_PUMP_H_
michael@0: 
michael@0: #include "base/ref_counted.h"
michael@0: 
michael@0: namespace base {
michael@0: 
michael@0: class TimeTicks;
michael@0: 
michael@0: class MessagePump : public RefCountedThreadSafe<MessagePump> {
michael@0:  public:
michael@0:   // Please see the comments above the Run method for an illustration of how
michael@0:   // these delegate methods are used.
michael@0:   class Delegate {
michael@0:    public:
michael@0:     virtual ~Delegate() {}
michael@0: 
michael@0:     // Called from within Run in response to ScheduleWork or when the message
michael@0:     // pump would otherwise call DoDelayedWork.  Returns true to indicate that
michael@0:     // work was done.  DoDelayedWork will not be called if DoWork returns true.
michael@0:     virtual bool DoWork() = 0;
michael@0: 
michael@0:     // Called from within Run in response to ScheduleDelayedWork or when the
michael@0:     // message pump would otherwise sleep waiting for more work.  Returns true
michael@0:     // to indicate that delayed work was done.  DoIdleWork will not be called
michael@0:     // if DoDelayedWork returns true.  Upon return |next_delayed_work_time|
michael@0:     // indicates the time when DoDelayedWork should be called again.  If
michael@0:     // |next_delayed_work_time| is null (per Time::is_null), then the queue of
michael@0:     // future delayed work (timer events) is currently empty, and no additional
michael@0:     // calls to this function need to be scheduled.
michael@0:     virtual bool DoDelayedWork(TimeTicks* next_delayed_work_time) = 0;
michael@0: 
michael@0:     // Called from within Run just before the message pump goes to sleep.
michael@0:     // Returns true to indicate that idle work was done.
michael@0:     virtual bool DoIdleWork() = 0;
michael@0:   };
michael@0: 
michael@0:   virtual ~MessagePump() {}
michael@0: 
michael@0:   // The Run method is called to enter the message pump's run loop.
michael@0:   //
michael@0:   // Within the method, the message pump is responsible for processing native
michael@0:   // messages as well as for giving cycles to the delegate periodically.  The
michael@0:   // message pump should take care to mix delegate callbacks with native
michael@0:   // message processing so neither type of event starves the other of cycles.
michael@0:   //
michael@0:   // The anatomy of a typical run loop:
michael@0:   //
michael@0:   //   for (;;) {
michael@0:   //     bool did_work = DoInternalWork();
michael@0:   //     if (should_quit_)
michael@0:   //       break;
michael@0:   //
michael@0:   //     did_work |= delegate_->DoWork();
michael@0:   //     if (should_quit_)
michael@0:   //       break;
michael@0:   //
michael@0:   //     did_work |= delegate_->DoDelayedWork();
michael@0:   //     if (should_quit_)
michael@0:   //       break;
michael@0:   //
michael@0:   //     if (did_work)
michael@0:   //       continue;
michael@0:   //
michael@0:   //     did_work = delegate_->DoIdleWork();
michael@0:   //     if (should_quit_)
michael@0:   //       break;
michael@0:   //
michael@0:   //     if (did_work)
michael@0:   //       continue;
michael@0:   //
michael@0:   //     WaitForWork();
michael@0:   //   }
michael@0:   //
michael@0:   // Here, DoInternalWork is some private method of the message pump that is
michael@0:   // responsible for dispatching the next UI message or notifying the next IO
michael@0:   // completion (for example).  WaitForWork is a private method that simply
michael@0:   // blocks until there is more work of any type to do.
michael@0:   //
michael@0:   // Notice that the run loop cycles between calling DoInternalWork, DoWork,
michael@0:   // and DoDelayedWork methods.  This helps ensure that neither work queue
michael@0:   // starves the other.  This is important for message pumps that are used to
michael@0:   // drive animations, for example.
michael@0:   //
michael@0:   // Notice also that after each callout to foreign code, the run loop checks
michael@0:   // to see if it should quit.  The Quit method is responsible for setting this
michael@0:   // flag.  No further work is done once the quit flag is set.
michael@0:   //
michael@0:   // NOTE: Care must be taken to handle Run being called again from within any
michael@0:   // of the callouts to foreign code.  Native message pumps may also need to
michael@0:   // deal with other native message pumps being run outside their control
michael@0:   // (e.g., the MessageBox API on Windows pumps UI messages!).  To be specific,
michael@0:   // the callouts (DoWork and DoDelayedWork) MUST still be provided even in
michael@0:   // nested sub-loops that are "seemingly" outside the control of this message
michael@0:   // pump.  DoWork in particular must never be starved for time slices unless
michael@0:   // it returns false (meaning it has run out of things to do).
michael@0:   //
michael@0:   virtual void Run(Delegate* delegate) = 0;
michael@0: 
michael@0:   // Quit immediately from the most recently entered run loop.  This method may
michael@0:   // only be used on the thread that called Run.
michael@0:   virtual void Quit() = 0;
michael@0: 
michael@0:   // Schedule a DoWork callback to happen reasonably soon.  Does nothing if a
michael@0:   // DoWork callback is already scheduled.  This method may be called from any
michael@0:   // thread.  Once this call is made, DoWork should not be "starved" at least
michael@0:   // until it returns a value of false.
michael@0:   virtual void ScheduleWork() = 0;
michael@0: 
michael@0:   // This method may only called from the thread that called Run.
michael@0:   //
michael@0:   // Ensure that DoWork will be called if a nested loop is entered.
michael@0:   // If a MessagePump can already guarantee that DoWork will be called
michael@0:   // "reasonably soon", this method can be a no-op to avoid expensive
michael@0:   // atomic tests and/or syscalls required for ScheduleWork().
michael@0:   virtual void ScheduleWorkForNestedLoop() { ScheduleWork(); };
michael@0: 
michael@0:   // Schedule a DoDelayedWork callback to happen at the specified time,
michael@0:   // cancelling any pending DoDelayedWork callback.  This method may only be
michael@0:   // used on the thread that called Run.
michael@0:   virtual void ScheduleDelayedWork(const TimeTicks& delayed_work_time) = 0;
michael@0: };
michael@0: 
michael@0: }  // namespace base
michael@0: 
michael@0: #endif  // BASE_MESSAGE_PUMP_H_