LCOV - code coverage report
Current view: directory - ipc/chromium/src/base - message_pump.h (source / functions) Found Hit Coverage
Test: app.info Lines: 5 4 80.0 %
Date: 2012-06-02 Functions: 7 4 57.1 %

       1                 : // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
       2                 : // Use of this source code is governed by a BSD-style license that can be
       3                 : // found in the LICENSE file.
       4                 : 
       5                 : #ifndef BASE_MESSAGE_PUMP_H_
       6                 : #define BASE_MESSAGE_PUMP_H_
       7                 : 
       8                 : #include "base/ref_counted.h"
       9                 : 
      10                 : namespace base {
      11                 : 
      12                 : class Time;
      13                 : 
      14            2840 : class MessagePump : public RefCountedThreadSafe<MessagePump> {
      15                 :  public:
      16                 :   // Please see the comments above the Run method for an illustration of how
      17                 :   // these delegate methods are used.
      18            2840 :   class Delegate {
      19                 :    public:
      20            5676 :     virtual ~Delegate() {}
      21                 : 
      22                 :     // Called from within Run in response to ScheduleWork or when the message
      23                 :     // pump would otherwise call DoDelayedWork.  Returns true to indicate that
      24                 :     // work was done.  DoDelayedWork will not be called if DoWork returns true.
      25                 :     virtual bool DoWork() = 0;
      26                 : 
      27                 :     // Called from within Run in response to ScheduleDelayedWork or when the
      28                 :     // message pump would otherwise sleep waiting for more work.  Returns true
      29                 :     // to indicate that delayed work was done.  DoIdleWork will not be called
      30                 :     // if DoDelayedWork returns true.  Upon return |next_delayed_work_time|
      31                 :     // indicates the time when DoDelayedWork should be called again.  If
      32                 :     // |next_delayed_work_time| is null (per Time::is_null), then the queue of
      33                 :     // future delayed work (timer events) is currently empty, and no additional
      34                 :     // calls to this function need to be scheduled.
      35                 :     virtual bool DoDelayedWork(Time* next_delayed_work_time) = 0;
      36                 : 
      37                 :     // Called from within Run just before the message pump goes to sleep.
      38                 :     // Returns true to indicate that idle work was done.
      39                 :     virtual bool DoIdleWork() = 0;
      40                 :   };
      41                 : 
      42            5676 :   virtual ~MessagePump() {}
      43                 : 
      44                 :   // The Run method is called to enter the message pump's run loop.
      45                 :   //
      46                 :   // Within the method, the message pump is responsible for processing native
      47                 :   // messages as well as for giving cycles to the delegate periodically.  The
      48                 :   // message pump should take care to mix delegate callbacks with native
      49                 :   // message processing so neither type of event starves the other of cycles.
      50                 :   //
      51                 :   // The anatomy of a typical run loop:
      52                 :   //
      53                 :   //   for (;;) {
      54                 :   //     bool did_work = DoInternalWork();
      55                 :   //     if (should_quit_)
      56                 :   //       break;
      57                 :   //
      58                 :   //     did_work |= delegate_->DoWork();
      59                 :   //     if (should_quit_)
      60                 :   //       break;
      61                 :   //
      62                 :   //     did_work |= delegate_->DoDelayedWork();
      63                 :   //     if (should_quit_)
      64                 :   //       break;
      65                 :   //
      66                 :   //     if (did_work)
      67                 :   //       continue;
      68                 :   //
      69                 :   //     did_work = delegate_->DoIdleWork();
      70                 :   //     if (should_quit_)
      71                 :   //       break;
      72                 :   //
      73                 :   //     if (did_work)
      74                 :   //       continue;
      75                 :   //
      76                 :   //     WaitForWork();
      77                 :   //   }
      78                 :   //
      79                 :   // Here, DoInternalWork is some private method of the message pump that is
      80                 :   // responsible for dispatching the next UI message or notifying the next IO
      81                 :   // completion (for example).  WaitForWork is a private method that simply
      82                 :   // blocks until there is more work of any type to do.
      83                 :   //
      84                 :   // Notice that the run loop cycles between calling DoInternalWork, DoWork,
      85                 :   // and DoDelayedWork methods.  This helps ensure that neither work queue
      86                 :   // starves the other.  This is important for message pumps that are used to
      87                 :   // drive animations, for example.
      88                 :   //
      89                 :   // Notice also that after each callout to foreign code, the run loop checks
      90                 :   // to see if it should quit.  The Quit method is responsible for setting this
      91                 :   // flag.  No further work is done once the quit flag is set.
      92                 :   //
      93                 :   // NOTE: Care must be taken to handle Run being called again from within any
      94                 :   // of the callouts to foreign code.  Native message pumps may also need to
      95                 :   // deal with other native message pumps being run outside their control
      96                 :   // (e.g., the MessageBox API on Windows pumps UI messages!).  To be specific,
      97                 :   // the callouts (DoWork and DoDelayedWork) MUST still be provided even in
      98                 :   // nested sub-loops that are "seemingly" outside the control of this message
      99                 :   // pump.  DoWork in particular must never be starved for time slices unless
     100                 :   // it returns false (meaning it has run out of things to do).
     101                 :   //
     102                 :   virtual void Run(Delegate* delegate) = 0;
     103                 : 
     104                 :   // Quit immediately from the most recently entered run loop.  This method may
     105                 :   // only be used on the thread that called Run.
     106                 :   virtual void Quit() = 0;
     107                 : 
     108                 :   // Schedule a DoWork callback to happen reasonably soon.  Does nothing if a
     109                 :   // DoWork callback is already scheduled.  This method may be called from any
     110                 :   // thread.  Once this call is made, DoWork should not be "starved" at least
     111                 :   // until it returns a value of false.
     112                 :   virtual void ScheduleWork() = 0;
     113                 : 
     114                 :   // This method may only called from the thread that called Run.
     115                 :   //
     116                 :   // Ensure that DoWork will be called if a nested loop is entered.
     117                 :   // If a MessagePump can already guarantee that DoWork will be called
     118                 :   // "reasonably soon", this method can be a no-op to avoid expensive
     119                 :   // atomic tests and/or syscalls required for ScheduleWork().
     120               0 :   virtual void ScheduleWorkForNestedLoop() { ScheduleWork(); };
     121                 : 
     122                 :   // Schedule a DoDelayedWork callback to happen at the specified time,
     123                 :   // cancelling any pending DoDelayedWork callback.  This method may only be
     124                 :   // used on the thread that called Run.
     125                 :   virtual void ScheduleDelayedWork(const Time& delayed_work_time) = 0;
     126                 : };
     127                 : 
     128                 : }  // namespace base
     129                 : 
     130                 : #endif  // BASE_MESSAGE_PUMP_H_

Generated by: LCOV version 1.7