COIN-OR::LEMON - Graph Library

source: lemon-1.2/lemon/bits/alteration_notifier.h @ 313:64f8f7cc6168

Last change on this file since 313:64f8f7cc6168 was 313:64f8f7cc6168, checked in by Peter Kovacs <kpeter@…>, 11 years ago

Fix several doxygen warnings

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