src/apps/cortex/support/ObservableLooper.h

   1 /*
   2  * Copyright (c) 1999-2000, Eric Moon.
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions, and the following disclaimer.
  11  *
  12  * 2. Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions, and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * 3. The name of the author may not be used to endorse or promote products
  17  *    derived from this software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
  20  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  21  * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  22  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  23  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  26  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
  27  * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  */
  30
  31
  32 // ObservableLooper.h
  33 // * PURPOSE
  34 //   Implementation of an observable (target) derived
  35 //   from BLooper.
  36 //
  37 // * HISTORY
  38 //   e.moon             18aug99         Begun
  39
  40 #ifndef __ObservableLooper_H__
  41 #define __ObservableLooper_H__
  42
  43 #include <Looper.h>
  44 class BMessageRunner;
  45
  46 #include "observe.h"
  47 #include "IObservable.h"
  48 #include "MultiInvoker.h"
  49
  50 #include "cortex_defs.h"
  51 __BEGIN_CORTEX_NAMESPACE
  52
  53 class ObservableLooper :
  54         public  BLooper,
  55         public  IObservable,
  56         private MultiInvoker {
  57
  58         typedef BLooper _inherited;
  59
  60 public:                                                                                 // *** deletion
  61         // clients must call release() rather than deleting,
  62         // to ensure that all observers are notified of the
  63         // object's demise.  if the object has already been
  64         // released, return an error.
  65
  66         virtual status_t release();
  67
  68 public:                                                                                 // *** ctor/dtor
  69         virtual ~ObservableLooper();
  70         ObservableLooper(
  71                 const char*                                                     name=0,
  72                 int32                                                                           priority=B_NORMAL_PRIORITY,
  73                 int32                                                                           portCapacity=B_LOOPER_PORT_DEFAULT_CAPACITY,
  74                 bigtime_t                                                               quitTimeout=B_INFINITE_TIMEOUT);
  75         ObservableLooper(
  76                 BMessage*                                                               archive);
  77
  78 public:                                                                                 // *** accessors
  79         // return true if release() has been called, false otherwise.
  80         bool isReleased() const;
  81
  82 protected:                                                                      // *** hooks
  83         // sends M_OBSERVER_ADDED to the newly-added observer
  84         virtual void observerAdded(
  85                 const BMessenger&                               observer);
  86
  87         // sends M_OBSERVER_REMOVED to the newly-removed observer
  88         virtual void observerRemoved(
  89                 const BMessenger&                               observer);
  90
  91 protected:                                                                      // *** internal operations
  92         // call to send the given message to all observers.
  93         // Responsibility for deletion of the message remains with
  94         // the caller.
  95         // * LOCKING: the BLooper must be locked.
  96         virtual status_t notify(
  97                 BMessage*                                                               message);
  98
  99         // sends M_RELEASE_OBSERVABLE
 100         virtual void notifyRelease();
 101
 102 public:                                                                                 // *** BLooper
 103         virtual void Quit();
 104         virtual bool QuitRequested();
 105
 106 public:                                                                                 // *** BHandler
 107         virtual void MessageReceived(
 108                 BMessage*                                                               message);
 109
 110 public:                                                                                 // *** BArchivable
 111         // * LOCKING: the BLooper must be locked.
 112         virtual status_t Archive(
 113                 BMessage*                                                               archive,
 114                 bool                                                                            deep=true) const;
 115
 116 private:                                                                                // implementation
 117         void _handleAddObserver(
 118                 BMessage*                                                               message);
 119
 120         void _handleRemoveObserver(
 121                 BMessage*                                                               message);
 122
 123 private:                                                                                // members
 124         // how long to wait after being requested to shut down
 125         // before giving up on stuck observers
 126         bigtime_t                                                                       m_quitTimeout;
 127         BMessageRunner*                                         m_executioner;
 128
 129         // true if a quit has been requested
 130         bool                                                                                    m_quitting;
 131 };
 132
 133 __END_CORTEX_NAMESPACE
 134 #endif /*__ObservableLooper_H__*/
 135