src/Observable.h

   1 //
   2 // This file is part of the aMule Project.
   3 //
   4 // Copyright (c) 2005-2008 Mikkel Schubert ( xaignar@users.sourceforge.net )
   5 // Copyright (c) 2005-2008 aMule Team ( admin@amule.org / http://www.amule.org )
   6 //
   7 // Any parts of this program derived from the xMule, lMule or eMule project,
   8 // or contributed by third-party developers are copyrighted by their
   9 // respective authors.
  10 //
  11 // This program is free software; you can redistribute it and/or modify
  12 // it under the terms of the GNU General Public License as published by
  13 // the Free Software Foundation; either version 2 of the License, or
  14 // (at your option) any later version.
  15 //
  16 // This program is distributed in the hope that it will be useful,
  17 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 // GNU General Public License for more details.
  20 //
  21 // You should have received a copy of the GNU General Public License
  22 // along with this program; if not, write to the Free Software
  23 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
  24 //
  25
  26 #ifndef OBSERVABLE_H
  27 #define OBSERVABLE_H
  28
  29
  30 #include <set>
  31
  32 #include "OtherFunctions.h"             // Needed for CMutexUnlocker
  33
  34
  35 template <typename TEST> class CObservable;
  36
  37
  38 /**
  39  * This class implements the observable part of an Observer/Observable pattern.
  40  *
  41  * The EventType paramter is used to specify a protocol for the event-type used
  42  * by a particular Observer/Observable set and allows for any level of
  43  * information passing to be used, depending on the context.
  44  *
  45  * In order to simplify matters for subclasses, both the Observer and the
  46  * Observable class keep track of which objects are observing what, so that
  47  * instances can safely be created and destroyed without having to manually
  48  * keep the observers and observables in sync.
  49  */
  50 template <typename EventType>
  51 class CObserver
  52 {
  53         friend class CObservable<EventType>;
  54 public:
  55         typedef CObservable<EventType> ObservableType;
  56
  57         /**
  58          * Destructor.
  59          *
  60          * All observables which has this object registered are notified
  61          * as to avoid dangling pointers. This will not result in actual
  62          * events.
  63          */
  64         virtual ~CObserver();
  65
  66
  67 protected:
  68         /**
  69          * This function is called when an observed subject publishes an event.
  70          *
  71          * @param o The publisher of the event.
  72          * @param e The actual event.
  73          */
  74         virtual void ReceiveNotification( const ObservableType* o, const EventType& e ) = 0;
  75
  76
  77 private:
  78         //! Mutex used to make access to the list of observed objects thread safe.
  79         wxMutex m_mutex;
  80
  81         typedef std::set<ObservableType*> ObservableSetType;
  82         //! List of objects being observed.
  83         ObservableSetType m_list;
  84 };
  85
  86
  87
  88 /**
  89  * This class implements the Observable part of the Observer/Observable pattern.
  90  */
  91 template <typename EventType>
  92 class CObservable
  93 {
  94         friend class CObserver<EventType>;
  95
  96 public:
  97         //! The observer-type accepted by this class
  98         typedef CObserver<EventType> ObserverType;
  99
 100
 101         /**
 102          * Destructor.
 103          */
 104         virtual ~CObservable();
 105
 106
 107         /**
 108          * This function subscribes an observer to events from this observable.
 109          *
 110          * @param o The observer that wishes to observe this object.
 111          * @return True if it succesfully subscribed, false otherwise.
 112          *
 113          * If the subscription was succesful, ObserverAdded() will be called
 114          * on "o", allowing the subclass to initialize the the observer's state.
 115          */
 116         bool AddObserver( ObserverType* o );
 117
 118         /**
 119          * This function removes an observer from the list of subscribers.
 120          *
 121          * @param o The observer to unsubscribe from this observable.
 122          * @return True if the observer was removed, false otherwise.
 123          *
 124          * ObserverRemoved() will be called for the observer "o", allowing
 125          * the subclass to take steps to avoid outdated data being kept.
 126          */
 127         bool RemoveObserver( ObserverType* o );
 128
 129 protected:
 130         /**
 131          * This function notifies all or an specific observer of an event.
 132          *
 133          * @param e The event to be published.
 134          * @param o A specific subscribing observer or NULL for all subscribers.
 135          *
 136          * The purpose of the second parameter is to allow notifications of
 137          * specific observers when the ObserverAdded() or ObserverRemoved()
 138          * functions are called and it should not be used outside of these
 139          * functions.
 140          */
 141         void NotifyObservers( const EventType& e, ObserverType* o = NULL );
 142
 143
 144         /**
 145          * This function removes all observers from this object.
 146          *
 147          * ObserverRemoved is called on each observer.
 148          */
 149         void RemoveAllObservers();
 150
 151
 152         /**
 153          * This function is called when an observer has been added to the observable.
 154          */
 155         virtual void ObserverAdded( ObserverType* ) {};
 156
 157
 158         /**
 159          * This function is called when observers are removed from the observable.
 160          *
 161          * Exceptions to this are:
 162          *  - When the Observable is being destroyed.
 163          *  - When the Observer is being destroyed.
 164          */
 165         virtual void ObserverRemoved( ObserverType* ) {};
 166
 167
 168 private:
 169         //! Mutex used to ensure thread-safety of the basic operations.
 170         wxMutex m_mutex;
 171
 172         typedef std::set<ObserverType*> ObserverSetType;
 173         typedef typename ObserverSetType::iterator myIteratorType;
 174
 175         //! Set of all observers subscribing to this observable.
 176         ObserverSetType m_list;
 177 };
 178
 179
 180
 181
 182 ///////////////////////////////////////////////////////////////////////////////
 183
 184
 185
 186
 187 template <typename EventType>
 188 CObserver<EventType>::~CObserver()
 189 {
 190         wxMutexLocker lock( m_mutex );
 191
 192         while ( !m_list.empty() ) {
 193                 ObservableType* o = *m_list.begin();
 194
 195                 {
 196                         wxMutexLocker oLock(o->m_mutex);
 197                         o->m_list.erase( this );
 198                 }
 199
 200                 m_list.erase( m_list.begin() );
 201         }
 202 }
 203
 204
 205 template <typename EventType>
 206 CObservable<EventType>::~CObservable()
 207 {
 208         wxMutexLocker lock( m_mutex );
 209
 210         while ( !m_list.empty() ) {
 211                 ObserverType* o = *m_list.begin();
 212
 213                 {
 214                         wxMutexLocker oLock(o->m_mutex);
 215                         o->m_list.erase( this );
 216                 }
 217
 218                 m_list.erase( m_list.begin() );
 219         }
 220 }
 221
 222
 223 template <typename EventType>
 224 bool CObservable<EventType>::AddObserver( CObserver<EventType>* o )
 225 {
 226         wxASSERT( o );
 227
 228         {
 229                 wxMutexLocker lock(m_mutex);
 230                 if ( !m_list.insert( o ).second ) {
 231                         return false;
 232                 }
 233         }
 234
 235         {
 236                 wxMutexLocker oLock(o->m_mutex);
 237                 o->m_list.insert( this );
 238         }
 239
 240         ObserverAdded( o );
 241
 242         return true;
 243 }
 244
 245
 246 template <typename EventType>
 247 bool CObservable<EventType>::RemoveObserver( CObserver<EventType>* o )
 248 {
 249         wxASSERT( o );
 250
 251         {
 252                 wxMutexLocker lock(m_mutex);
 253                 if ( !m_list.erase( o ) ) {
 254                         return false;
 255                 }
 256         }
 257
 258         {
 259                 wxMutexLocker oLock(o->m_mutex);
 260                 o->m_list.erase( this );
 261         }
 262
 263         ObserverRemoved( o );
 264
 265         return true;
 266 }
 267
 268
 269 template <typename EventType>
 270 void CObservable<EventType>::NotifyObservers( const EventType& e, ObserverType* o )
 271 {
 272         wxMutexLocker lock(m_mutex);
 273
 274         if ( o ) {
 275                 o->ReceiveNotification( this, e );
 276         } else {
 277                 myIteratorType it = m_list.begin();
 278                 for ( ; it != m_list.end(); ) {
 279                         CMutexUnlocker unlocker(m_mutex);
 280                         (*it++)->ReceiveNotification( this, e );
 281                 }
 282         }
 283 }
 284
 285
 286 template <typename EventType>
 287 void CObservable<EventType>::RemoveAllObservers()
 288 {
 289         wxMutexLocker lock(m_mutex);
 290
 291         while ( !m_list.empty() ) {
 292                 ObserverType* o = *m_list.begin();
 293                 m_list.erase( m_list.begin() );
 294                 CMutexUnlocker unlocker(m_mutex);
 295
 296                 {
 297                         wxMutexLocker oLock(o->m_mutex);
 298                         o->m_list.erase( this );
 299                 }
 300
 301                 ObserverRemoved( o );
 302         }
 303 }
 304
 305
 306 #endif
 307 // File_checked_for_headers