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