lemon/bits/alteration_notifier.h
author Alpar Juttner <alpar@cs.elte.hu>
Thu, 20 Mar 2008 21:59:35 +0000
changeset 104 cdbba181b786
child 107 31a2e6d28f61
permissions -rw-r--r--
Restored (and modified) StoreBoolMap (it was removed in 7ff1c348ae0c)

- also restored _maps_bits::IteratorTraits
- removes the Functor template parameter from StoreBoolMap
- doc changed a bit
deba@57
     1
/* -*- C++ -*-
deba@57
     2
 *
deba@57
     3
 * This file is a part of LEMON, a generic C++ optimization library
deba@57
     4
 *
deba@57
     5
 * Copyright (C) 2003-2007
deba@57
     6
 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
deba@57
     7
 * (Egervary Research Group on Combinatorial Optimization, EGRES).
deba@57
     8
 *
deba@57
     9
 * Permission to use, modify and distribute this software is granted
deba@57
    10
 * provided that this copyright notice appears in all copies. For
deba@57
    11
 * precise terms see the accompanying LICENSE file.
deba@57
    12
 *
deba@57
    13
 * This software is provided "AS IS" with no warranty of any kind,
deba@57
    14
 * express or implied, and with no claim as to its suitability for any
deba@57
    15
 * purpose.
deba@57
    16
 *
deba@57
    17
 */
deba@57
    18
deba@57
    19
#ifndef LEMON_BITS_ALTERATION_NOTIFIER_H
deba@57
    20
#define LEMON_BITS_ALTERATION_NOTIFIER_H
deba@57
    21
deba@57
    22
#include <vector>
deba@57
    23
#include <list>
deba@57
    24
deba@57
    25
#include <lemon/bits/utility.h>
deba@57
    26
deba@57
    27
///\ingroup graphbits
deba@57
    28
///\file
deba@57
    29
///\brief Observer notifier for graph alteration observers.
deba@57
    30
deba@57
    31
namespace lemon {
deba@57
    32
deba@57
    33
  /// \ingroup graphbits
deba@57
    34
  ///
deba@57
    35
  /// \brief Notifier class to notify observes about alterations in 
deba@57
    36
  /// a container.
deba@57
    37
  ///
deba@57
    38
  /// The simple graph's can be refered as two containers, one node container
deba@57
    39
  /// and one edge container. But they are not standard containers they
deba@57
    40
  /// does not store values directly they are just key continars for more
deba@57
    41
  /// value containers which are the node and edge maps.
deba@57
    42
  ///
deba@57
    43
  /// The graph's node and edge sets can be changed as we add or erase
deba@57
    44
  /// nodes and edges in the graph. Lemon would like to handle easily
deba@57
    45
  /// that the node and edge maps should contain values for all nodes or
deba@57
    46
  /// edges. If we want to check on every indicing if the map contains
deba@57
    47
  /// the current indicing key that cause a drawback in the performance
deba@57
    48
  /// in the library. We use another solution we notify all maps about
deba@57
    49
  /// an alteration in the graph, which cause only drawback on the
deba@57
    50
  /// alteration of the graph.
deba@57
    51
  ///
deba@57
    52
  /// This class provides an interface to the container. The \e first() and \e 
deba@57
    53
  /// next() member functions make possible to iterate on the keys of the
deba@57
    54
  /// container. The \e id() function returns an integer id for each key.
deba@57
    55
  /// The \e maxId() function gives back an upper bound of the ids.
deba@57
    56
  ///
deba@57
    57
  /// For the proper functonality of this class, we should notify it
deba@57
    58
  /// about each alteration in the container. The alterations have four type
deba@57
    59
  /// as \e add(), \e erase(), \e build() and \e clear(). The \e add() and
deba@57
    60
  /// \e erase() signals that only one or few items added or erased to or
deba@57
    61
  /// from the graph. If all items are erased from the graph or from an empty
deba@57
    62
  /// graph a new graph is builded then it can be signaled with the
deba@57
    63
  /// clear() and build() members. Important rule that if we erase items 
deba@57
    64
  /// from graph we should first signal the alteration and after that erase
deba@57
    65
  /// them from the container, on the other way on item addition we should
deba@57
    66
  /// first extend the container and just after that signal the alteration.
deba@57
    67
  ///
deba@57
    68
  /// The alteration can be observed with a class inherited from the
deba@57
    69
  /// \e ObserverBase nested class. The signals can be handled with
deba@57
    70
  /// overriding the virtual functions defined in the base class.  The
deba@57
    71
  /// observer base can be attached to the notifier with the 
deba@57
    72
  /// \e attach() member and can be detached with detach() function. The
deba@57
    73
  /// alteration handlers should not call any function which signals
deba@57
    74
  /// an other alteration in the same notifier and should not
deba@57
    75
  /// detach any observer from the notifier.
deba@57
    76
  ///
deba@57
    77
  /// Alteration observers try to be exception safe. If an \e add() or
deba@57
    78
  /// a \e clear() function throws an exception then the remaining
deba@57
    79
  /// observeres will not be notified and the fulfilled additions will
deba@57
    80
  /// be rolled back by calling the \e erase() or \e clear()
deba@57
    81
  /// functions. Thence the \e erase() and \e clear() should not throw
deba@57
    82
  /// exception. Actullay, it can be throw only 
deba@57
    83
  /// \ref AlterationObserver::ImmediateDetach ImmediateDetach
deba@57
    84
  /// exception which detach the observer from the notifier.
deba@57
    85
  ///
deba@57
    86
  /// There are some place when the alteration observing is not completly
deba@57
    87
  /// reliable. If we want to carry out the node degree in the graph
deba@57
    88
  /// as in the \ref InDegMap and we use the reverseEdge that cause 
deba@57
    89
  /// unreliable functionality. Because the alteration observing signals
deba@57
    90
  /// only erasing and adding but not the reversing it will stores bad
deba@57
    91
  /// degrees. The sub graph adaptors cannot signal the alterations because
deba@57
    92
  /// just a setting in the filter map can modify the graph and this cannot
deba@57
    93
  /// be watched in any way.
deba@57
    94
  ///
deba@57
    95
  /// \param _Container The container which is observed.
deba@57
    96
  /// \param _Item The item type which is obserbved.
deba@57
    97
  ///
deba@57
    98
  /// \author Balazs Dezso
deba@57
    99
deba@57
   100
  template <typename _Container, typename _Item>
deba@57
   101
  class AlterationNotifier {
deba@57
   102
  public:
deba@57
   103
deba@57
   104
    typedef True Notifier;
deba@57
   105
deba@57
   106
    typedef _Container Container;
deba@57
   107
    typedef _Item Item;
deba@57
   108
deba@57
   109
    /// \brief Exception which can be called from \e clear() and 
deba@57
   110
    /// \e erase().
deba@57
   111
    ///
deba@57
   112
    /// From the \e clear() and \e erase() function only this
deba@57
   113
    /// exception is allowed to throw. The exception immediatly
deba@57
   114
    /// detaches the current observer from the notifier. Because the
deba@57
   115
    /// \e clear() and \e erase() should not throw other exceptions
deba@57
   116
    /// it can be used to invalidate the observer.
deba@57
   117
    struct ImmediateDetach {};
deba@57
   118
deba@57
   119
    /// \brief ObserverBase is the base class for the observers.
deba@57
   120
    ///
deba@57
   121
    /// ObserverBase is the abstract base class for the observers.
deba@57
   122
    /// It will be notified about an item was inserted into or
deba@57
   123
    /// erased from the graph.
deba@57
   124
    ///
deba@57
   125
    /// The observer interface contains some pure virtual functions
deba@57
   126
    /// to override. The add() and erase() functions are
deba@57
   127
    /// to notify the oberver when one item is added or
deba@57
   128
    /// erased.
deba@57
   129
    ///
deba@57
   130
    /// The build() and clear() members are to notify the observer
deba@57
   131
    /// about the container is built from an empty container or
deba@57
   132
    /// is cleared to an empty container. 
deba@57
   133
    /// 
deba@57
   134
    /// \author Balazs Dezso
deba@57
   135
deba@57
   136
    class ObserverBase {
deba@57
   137
    protected:
deba@57
   138
      typedef AlterationNotifier Notifier;
deba@57
   139
deba@57
   140
      friend class AlterationNotifier;
deba@57
   141
deba@57
   142
      /// \brief Default constructor.
deba@57
   143
      ///
deba@57
   144
      /// Default constructor for ObserverBase.
deba@57
   145
      /// 
deba@57
   146
      ObserverBase() : _notifier(0) {}
deba@57
   147
deba@57
   148
      /// \brief Constructor which attach the observer into notifier.
deba@57
   149
      ///
deba@57
   150
      /// Constructor which attach the observer into notifier.
deba@57
   151
      ObserverBase(AlterationNotifier& nf) {
deba@57
   152
        attach(nf);
deba@57
   153
      }
deba@57
   154
deba@57
   155
      /// \brief Constructor which attach the obserever to the same notifier.
deba@57
   156
      ///
deba@57
   157
      /// Constructor which attach the obserever to the same notifier as
deba@57
   158
      /// the other observer is attached to. 
deba@57
   159
      ObserverBase(const ObserverBase& copy) {
deba@57
   160
	if (copy.attached()) {
deba@57
   161
          attach(*copy.notifier());
deba@57
   162
	}
deba@57
   163
      }
deba@57
   164
	
deba@57
   165
      /// \brief Destructor
deba@57
   166
      virtual ~ObserverBase() {
deba@57
   167
        if (attached()) {
deba@57
   168
          detach();
deba@57
   169
        }
deba@57
   170
      }
deba@57
   171
deba@57
   172
      /// \brief Attaches the observer into an AlterationNotifier.
deba@57
   173
      ///
deba@57
   174
      /// This member attaches the observer into an AlterationNotifier.
deba@57
   175
      ///
deba@57
   176
      void attach(AlterationNotifier& nf) {
deba@57
   177
	nf.attach(*this);
deba@57
   178
      }
deba@57
   179
      
deba@57
   180
      /// \brief Detaches the observer into an AlterationNotifier.
deba@57
   181
      ///
deba@57
   182
      /// This member detaches the observer from an AlterationNotifier.
deba@57
   183
      ///
deba@57
   184
      void detach() {
deba@57
   185
        _notifier->detach(*this);
deba@57
   186
      }
deba@57
   187
      
deba@57
   188
      /// \brief Gives back a pointer to the notifier which the map 
deba@57
   189
      /// attached into.
deba@57
   190
      ///
deba@57
   191
      /// This function gives back a pointer to the notifier which the map
deba@57
   192
      /// attached into.
deba@57
   193
      ///
deba@57
   194
      Notifier* notifier() const { return const_cast<Notifier*>(_notifier); }
deba@57
   195
      
deba@57
   196
      /// Gives back true when the observer is attached into a notifier.
deba@57
   197
      bool attached() const { return _notifier != 0; }
deba@57
   198
deba@57
   199
    private:
deba@57
   200
deba@57
   201
      ObserverBase& operator=(const ObserverBase& copy);
deba@57
   202
deba@57
   203
    protected:
deba@57
   204
      
deba@57
   205
      Notifier* _notifier;
deba@57
   206
      typename std::list<ObserverBase*>::iterator _index;
deba@57
   207
deba@57
   208
      /// \brief The member function to notificate the observer about an
deba@57
   209
      /// item is added to the container.
deba@57
   210
      ///
deba@57
   211
      /// The add() member function notificates the observer about an item
deba@57
   212
      /// is added to the container. It have to be overrided in the
deba@57
   213
      /// subclasses.
deba@57
   214
      virtual void add(const Item&) = 0;
deba@57
   215
deba@57
   216
      /// \brief The member function to notificate the observer about 
deba@57
   217
      /// more item is added to the container.
deba@57
   218
      ///
deba@57
   219
      /// The add() member function notificates the observer about more item
deba@57
   220
      /// is added to the container. It have to be overrided in the
deba@57
   221
      /// subclasses.
deba@57
   222
      virtual void add(const std::vector<Item>& items) = 0;
deba@57
   223
deba@57
   224
      /// \brief The member function to notificate the observer about an
deba@57
   225
      /// item is erased from the container.
deba@57
   226
      ///
deba@57
   227
      /// The erase() member function notificates the observer about an
deba@57
   228
      /// item is erased from the container. It have to be overrided in
deba@57
   229
      /// the subclasses.	
deba@57
   230
      virtual void erase(const Item&) = 0;
deba@57
   231
deba@57
   232
      /// \brief The member function to notificate the observer about 
deba@57
   233
      /// more item is erased from the container.
deba@57
   234
      ///
deba@57
   235
      /// The erase() member function notificates the observer about more item
deba@57
   236
      /// is erased from the container. It have to be overrided in the
deba@57
   237
      /// subclasses.
deba@57
   238
      virtual void erase(const std::vector<Item>& items) = 0;
deba@57
   239
deba@57
   240
      /// \brief The member function to notificate the observer about the
deba@57
   241
      /// container is built.
deba@57
   242
      ///
deba@57
   243
      /// The build() member function notificates the observer about the
deba@57
   244
      /// container is built from an empty container. It have to be
deba@57
   245
      /// overrided in the subclasses.
deba@57
   246
deba@57
   247
      virtual void build() = 0;
deba@57
   248
deba@57
   249
      /// \brief The member function to notificate the observer about all
deba@57
   250
      /// items are erased from the container.
deba@57
   251
      ///
deba@57
   252
      /// The clear() member function notificates the observer about all
deba@57
   253
      /// items are erased from the container. It have to be overrided in
deba@57
   254
      /// the subclasses.      
deba@57
   255
      virtual void clear() = 0;
deba@57
   256
deba@57
   257
    };
deba@57
   258
	
deba@57
   259
  protected:
deba@57
   260
deba@57
   261
    const Container* container;
deba@57
   262
deba@57
   263
    typedef std::list<ObserverBase*> Observers; 
deba@57
   264
    Observers _observers;
deba@57
   265
deba@57
   266
		
deba@57
   267
  public:
deba@57
   268
deba@57
   269
    /// \brief Default constructor.
deba@57
   270
    ///
deba@57
   271
    /// The default constructor of the AlterationNotifier. 
deba@57
   272
    /// It creates an empty notifier.
deba@57
   273
    AlterationNotifier() 
deba@57
   274
      : container(0) {}
deba@57
   275
deba@57
   276
    /// \brief Constructor.
deba@57
   277
    ///
deba@57
   278
    /// Constructor with the observed container parameter.
deba@57
   279
    AlterationNotifier(const Container& _container) 
deba@57
   280
      : container(&_container) {}
deba@57
   281
deba@57
   282
    /// \brief Copy Constructor of the AlterationNotifier. 
deba@57
   283
    ///
deba@57
   284
    /// Copy constructor of the AlterationNotifier. 
deba@57
   285
    /// It creates only an empty notifier because the copiable
deba@57
   286
    /// notifier's observers have to be registered still into that notifier.
deba@57
   287
    AlterationNotifier(const AlterationNotifier& _notifier) 
deba@57
   288
      : container(_notifier.container) {}
deba@57
   289
deba@57
   290
    /// \brief Destructor.
deba@57
   291
    ///		
deba@57
   292
    /// Destructor of the AlterationNotifier.
deba@57
   293
    ///
deba@57
   294
    ~AlterationNotifier() {
deba@57
   295
      typename Observers::iterator it;
deba@57
   296
      for (it = _observers.begin(); it != _observers.end(); ++it) {
deba@57
   297
	(*it)->_notifier = 0;
deba@57
   298
      }
deba@57
   299
    }
deba@57
   300
deba@57
   301
    /// \brief Sets the container.
deba@57
   302
    ///
deba@57
   303
    /// Sets the container.
deba@57
   304
    void setContainer(const Container& _container) {
deba@57
   305
      container = &_container;
deba@57
   306
    }
deba@57
   307
deba@57
   308
  protected:
deba@57
   309
deba@57
   310
    AlterationNotifier& operator=(const AlterationNotifier&);
deba@57
   311
deba@57
   312
  public:
deba@57
   313
deba@57
   314
deba@57
   315
deba@57
   316
    /// \brief First item in the container.
deba@57
   317
    ///
deba@57
   318
    /// Returns the first item in the container. It is
deba@57
   319
    /// for start the iteration on the container.
deba@57
   320
    void first(Item& item) const {
deba@57
   321
      container->first(item);
deba@57
   322
    }
deba@57
   323
deba@57
   324
    /// \brief Next item in the container.
deba@57
   325
    ///
deba@57
   326
    /// Returns the next item in the container. It is
deba@57
   327
    /// for iterate on the container.
deba@57
   328
    void next(Item& item) const {
deba@57
   329
      container->next(item);
deba@57
   330
    }
deba@57
   331
deba@57
   332
    /// \brief Returns the id of the item.
deba@57
   333
    ///
deba@57
   334
    /// Returns the id of the item provided by the container.
deba@57
   335
    int id(const Item& item) const {
deba@57
   336
      return container->id(item);
deba@57
   337
    }
deba@57
   338
deba@57
   339
    /// \brief Returns the maximum id of the container.
deba@57
   340
    ///
deba@57
   341
    /// Returns the maximum id of the container.
deba@57
   342
    int maxId() const {
deba@57
   343
      return container->maxId(Item());
deba@57
   344
    }
deba@57
   345
		
deba@57
   346
  protected:
deba@57
   347
deba@57
   348
    void attach(ObserverBase& observer) {
deba@57
   349
      observer._index = _observers.insert(_observers.begin(), &observer);
deba@57
   350
      observer._notifier = this;
deba@57
   351
    } 
deba@57
   352
deba@57
   353
    void detach(ObserverBase& observer) {
deba@57
   354
      _observers.erase(observer._index);
deba@57
   355
      observer._index = _observers.end();
deba@57
   356
      observer._notifier = 0;
deba@57
   357
    }
deba@57
   358
deba@57
   359
  public:
deba@57
   360
	
deba@57
   361
    /// \brief Notifies all the registed observers about an item added to 
deba@57
   362
    /// the container.
deba@57
   363
    ///
deba@57
   364
    /// It notifies all the registed observers about an item added to 
deba@57
   365
    /// the container.
deba@57
   366
    /// 
deba@57
   367
    void add(const Item& item) {
deba@57
   368
      typename Observers::reverse_iterator it;
deba@57
   369
      try {
deba@57
   370
        for (it = _observers.rbegin(); it != _observers.rend(); ++it) {
deba@57
   371
          (*it)->add(item);
deba@57
   372
        }
deba@57
   373
      } catch (...) {
deba@57
   374
        typename Observers::iterator jt;
deba@57
   375
        for (jt = it.base(); jt != _observers.end(); ++jt) {
deba@57
   376
          (*jt)->erase(item);
deba@57
   377
        }
deba@57
   378
        throw;
deba@57
   379
      }
deba@57
   380
    }	
deba@57
   381
deba@57
   382
    /// \brief Notifies all the registed observers about more item added to 
deba@57
   383
    /// the container.
deba@57
   384
    ///
deba@57
   385
    /// It notifies all the registed observers about more item added to 
deba@57
   386
    /// the container.
deba@57
   387
    /// 
deba@57
   388
    void add(const std::vector<Item>& items) {
deba@57
   389
      typename Observers::reverse_iterator it;
deba@57
   390
      try {
deba@57
   391
        for (it = _observers.rbegin(); it != _observers.rend(); ++it) {
deba@57
   392
          (*it)->add(items);
deba@57
   393
        }
deba@57
   394
      } catch (...) {
deba@57
   395
        typename Observers::iterator jt;
deba@57
   396
        for (jt = it.base(); jt != _observers.end(); ++jt) {
deba@57
   397
          (*jt)->erase(items);
deba@57
   398
        }
deba@57
   399
        throw;
deba@57
   400
      }
deba@57
   401
    }	
deba@57
   402
deba@57
   403
    /// \brief Notifies all the registed observers about an item erased from 
deba@57
   404
    /// the container.
deba@57
   405
    ///	
deba@57
   406
    /// It notifies all the registed observers about an item erased from 
deba@57
   407
    /// the container.
deba@57
   408
    /// 
deba@57
   409
    void erase(const Item& item) throw() {
deba@57
   410
      typename Observers::iterator it = _observers.begin();
deba@57
   411
      while (it != _observers.end()) {
deba@57
   412
        try {
deba@57
   413
          (*it)->erase(item);
deba@57
   414
          ++it;
deba@57
   415
        } catch (const ImmediateDetach&) {
deba@57
   416
          it = _observers.erase(it);
deba@57
   417
          (*it)->_index = _observers.end();
deba@57
   418
          (*it)->_notifier = 0;
deba@57
   419
        }
deba@57
   420
      }
deba@57
   421
    }
deba@57
   422
deba@57
   423
    /// \brief Notifies all the registed observers about more item erased  
deba@57
   424
    /// from the container.
deba@57
   425
    ///	
deba@57
   426
    /// It notifies all the registed observers about more item erased from 
deba@57
   427
    /// the container.
deba@57
   428
    /// 
deba@57
   429
    void erase(const std::vector<Item>& items) {
deba@57
   430
      typename Observers::iterator it = _observers.begin();
deba@57
   431
      while (it != _observers.end()) {
deba@57
   432
        try {
deba@57
   433
          (*it)->erase(items);
deba@57
   434
          ++it;
deba@57
   435
        } catch (const ImmediateDetach&) {
deba@57
   436
          it = _observers.erase(it);
deba@57
   437
          (*it)->_index = _observers.end();
deba@57
   438
          (*it)->_notifier = 0;
deba@57
   439
        }
deba@57
   440
      }
deba@57
   441
    }
deba@57
   442
deba@57
   443
    /// \brief Notifies all the registed observers about the container is 
deba@57
   444
    /// built.
deba@57
   445
    ///		
deba@57
   446
    /// Notifies all the registed observers about the container is built
deba@57
   447
    /// from an empty container.
deba@57
   448
    void build() {
deba@57
   449
      typename Observers::reverse_iterator it;
deba@57
   450
      try {
deba@57
   451
        for (it = _observers.rbegin(); it != _observers.rend(); ++it) {
deba@57
   452
          (*it)->build();
deba@57
   453
        }
deba@57
   454
      } catch (...) {
deba@57
   455
        typename Observers::iterator jt;
deba@57
   456
        for (jt = it.base(); jt != _observers.end(); ++jt) {
deba@57
   457
          (*jt)->clear();
deba@57
   458
        }
deba@57
   459
        throw;
deba@57
   460
      }
deba@57
   461
    }
deba@57
   462
deba@57
   463
    /// \brief Notifies all the registed observers about all items are 
deba@57
   464
    /// erased.
deba@57
   465
    ///
deba@57
   466
    /// Notifies all the registed observers about all items are erased
deba@57
   467
    /// from the container.
deba@57
   468
    void clear() {
deba@57
   469
      typename Observers::iterator it = _observers.begin();
deba@57
   470
      while (it != _observers.end()) {
deba@57
   471
        try {
deba@57
   472
          (*it)->clear();
deba@57
   473
          ++it;
deba@57
   474
        } catch (const ImmediateDetach&) {
deba@57
   475
          it = _observers.erase(it);
deba@57
   476
          (*it)->_index = _observers.end();
deba@57
   477
          (*it)->_notifier = 0;
deba@57
   478
        }
deba@57
   479
      }
deba@57
   480
    }
deba@57
   481
  };
deba@57
   482
deba@57
   483
}
deba@57
   484
deba@57
   485
#endif