src/apps/cortex/support/observe.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 // Observe.h (cortex)
  33 // * PURPOSE
  34 //   Messages used for implementation of the Observer pattern.
  35 //
  36 // * HISTORY
  37 //   e.moon             19aug99         Begun
  38
  39 #ifndef __Observe_H__
  40 #define __Observe_H__
  41
  42 #include <Messenger.h>
  43 #include <Debug.h>
  44 #include <string.h>
  45
  46 #include "cortex_defs.h"
  47 __BEGIN_CORTEX_NAMESPACE
  48
  49 // -------------------------------------------------------- //
  50 // *** MESSAGES ***
  51 // -------------------------------------------------------- //
  52
  53 // messages sent to the Observable (source)
  54 enum observer_message_t {
  55         // Requests that an observer be added to a given
  56         // observable (target).
  57         // - "observer" (BMessenger)
  58         M_ADD_OBSERVER                                                  = Observer_message_base,
  59
  60         // Requests that a given observable (target) stop
  61         // sending notifications to a given observer.
  62         // Should be sent in response to M_RELEASE_OBSERVABLE
  63         // in order to allow the observable object to be deleted.
  64         // - "observer" (BMessenger)
  65         M_REMOVE_OBSERVER,
  66
  67         // Requests that an observable quit immediately without
  68         // waiting for its observers to acknowledge that they're done.
  69         // This should only be posted to an Observable in an
  70         // emergency
  71         M_KILL_OBSERVABLE
  72 };
  73
  74
  75 // messages sent by the Observable (target)
  76 enum target_message_t {
  77         // sent when the target is no longer needed; the
  78         // observer should reply with M_REMOVE_OBSERVER in order
  79         // to release (allow the deletion of) the target
  80         // - "target" (BMessenger)
  81         M_RELEASE_OBSERVABLE                            = Observable_message_base,
  82
  83         // SUGGESTED BUT NOT REQUIRED FOR IObservable IMPLEMENTATION:
  84         // *** IObservables are encouraged to send other replies!
  85         // sent upon successful receipt of M_ADD_OBSERVER
  86         // - "target" (BMessenger)
  87         M_OBSERVER_ADDED,
  88
  89         // SUGGESTED BUT NOT REQUIRED FOR IObservable IMPLEMENTATION:
  90         // *** IObservables are encouraged to send other replies!
  91         // sent upon successful receipt of M_REMOVE_OBSERVER
  92         // - "target" (BMessenger)
  93         M_OBSERVER_REMOVED,
  94
  95         // sent when no matching observer was found for an
  96         // M_REMOVE_OBSERVER message, or if the observer specified
  97         // in an M_ADD_OBSERVER message was previously added.
  98         // - "target" (BMessenger)
  99         // - "observer" (BMessenger)
 100         M_BAD_OBSERVER,
 101
 102         // sent when the target receiving an M_ADD_OBSERVER
 103         // or M_REMOVE_OBSERVER didn't match the target described
 104         // in the message.  also sent if the target is currently
 105         // in the process of quitting (it's already sent M_RELEASE_OBSERVABLE
 106         // to its current observers, and is waiting for them to acknowledge
 107         // with M_REMOVE_OBSERVER so that it can delete itself.)
 108         // - "target" (BMessenger)
 109         // - "observer" (BMessenger)
 110         M_BAD_TARGET
 111 };
 112
 113 // -------------------------------------------------------- //
 114 // *** FUNCTIONS ***
 115 // -------------------------------------------------------- //
 116
 117 // * Asynchronous
 118
 119 status_t add_observer(
 120         const BMessenger&                               observer,
 121         const BMessenger&                               target);
 122
 123 status_t remove_observer(
 124         const BMessenger&                               observer,
 125         const BMessenger&                               target);
 126
 127 // * Synchronous
 128
 129 status_t add_observer(
 130         const BMessenger&                               observer,
 131         const BMessenger&                               target,
 132         BMessage&                                                               reply,
 133         bigtime_t                                                               timeout =B_INFINITE_TIMEOUT);
 134
 135 status_t remove_observer(
 136         const BMessenger&                               observer,
 137         const BMessenger&                               target,
 138         BMessage&                                                               reply,
 139         bigtime_t                                                               timeout =B_INFINITE_TIMEOUT);
 140
 141 // -------------------------------------------------------- //
 142 // *** TOOL CLASSES ***
 143 // -------------------------------------------------------- //
 144
 145 template <class _observable_t>
 146 class observer_handle {
 147
 148 public:                                                                         // ctor/dtor
 149
 150         virtual ~observer_handle() {}
 151
 152         observer_handle(
 153                 const BMessenger&                       observer,
 154                 _observable_t*                          target,
 155                 bigtime_t                                                       timeout =B_INFINITE_TIMEOUT) :
 156
 157                 _observer_messenger(observer),
 158                 _target_messenger(target),
 159                 _target_cache(target),
 160                 _timeout(timeout),
 161                 _valid(false) {
 162
 163                 BMessage reply;
 164                 status_t err = add_observer(
 165                         _observer_messenger,
 166                         _target_messenger,
 167                         reply, timeout);
 168                 if(err < B_OK) {
 169                         PRINT((
 170                                 "! observer_handle<>(): add_observer() failed:\n"
 171                                 "  %s\n", strerror(err)));
 172 #if DEBUG
 173                         PRINT((
 174                                 "  * target's reply:\n"));
 175                         reply.PrintToStream();
 176 #endif
 177                 }
 178                 else _valid = true;
 179         }
 180
 181 public:                                                                         // interface
 182
 183         virtual void release() {
 184                 if(!_valid) {
 185                         PRINT((
 186                                 "! observer_handle<>::release(): invalid or already released.\n"));
 187                         return;
 188                 }
 189
 190                 BMessage reply;
 191                 status_t err = remove_observer(
 192                         _observer_messenger,
 193                         _target_messenger,
 194                         reply,
 195                         _timeout);
 196                 if(err < B_OK) {
 197                         PRINT((
 198                                 "! observer_handle<>::release(): remove_observer() failed:\n"
 199                                 "  %s\n", strerror(err)));
 200 #if DEBUG
 201                         PRINT((
 202                                 "  * target's reply:\n"));
 203                         reply.PrintToStream();
 204 #endif
 205                 }
 206
 207                 _valid = false;
 208         }
 209
 210 private:
 211         const BMessenger                                _observer_messenger;
 212         BMessenger                                                      _target_messenger;
 213         _observable_t*                                  _target_cache;
 214         bigtime_t                                                               _timeout;
 215         bool                                                                            _valid;
 216 };
 217
 218
 219 __END_CORTEX_NAMESPACE
 220 #endif /*__Observe_H__*/