lemongraph 0.0.1

data/ext/lemon-1.3.1/lemon/bits/alteration_notifier.h

@@ -0,0 +1,472 @@
+/* -*- mode: C++; indent-tabs-mode: nil; -*-
+ *
+ * This file is a part of LEMON, a generic C++ optimization library.
+ *
+ * Copyright (C) 2003-2013
+ * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
+ * (Egervary Research Group on Combinatorial Optimization, EGRES).
+ *
+ * Permission to use, modify and distribute this software is granted
+ * provided that this copyright notice appears in all copies. For
+ * precise terms see the accompanying LICENSE file.
+ *
+ * This software is provided "AS IS" with no warranty of any kind,
+ * express or implied, and with no claim as to its suitability for any
+ * purpose.
+ *
+ */
+
+#ifndef LEMON_BITS_ALTERATION_NOTIFIER_H
+#define LEMON_BITS_ALTERATION_NOTIFIER_H
+
+#include <vector>
+#include <list>
+
+#include <lemon/core.h>
+#include <lemon/bits/lock.h>
+
+//\ingroup graphbits
+//\file
+//\brief Observer notifier for graph alteration observers.
+
+namespace lemon {
+
+  // \ingroup graphbits
+  //
+  // \brief Notifier class to notify observes about alterations in
+  // a container.
+  //
+  // The simple graphs can be refered as two containers: a node container
+  // and an edge container. But they do not store values directly, they
+  // are just key continars for more value containers, which are the
+  // node and edge maps.
+  //
+  // The node and edge sets of the graphs can be changed as we add or erase
+  // nodes and edges in the graph. LEMON would like to handle easily
+  // that the node and edge maps should contain values for all nodes or
+  // edges. If we want to check on every indicing if the map contains
+  // the current indicing key that cause a drawback in the performance
+  // in the library. We use another solution: we notify all maps about
+  // an alteration in the graph, which cause only drawback on the
+  // alteration of the graph.
+  //
+  // This class provides an interface to a node or edge container.
+  // The first() and next() member functions make possible
+  // to iterate on the keys of the container.
+  // The id() function returns an integer id for each key.
+  // The maxId() function gives back an upper bound of the ids.
+  //
+  // For the proper functonality of this class, we should notify it
+  // about each alteration in the container. The alterations have four type:
+  // add(), erase(), build() and clear(). The add() and
+  // erase() signal that only one or few items added or erased to or
+  // from the graph. If all items are erased from the graph or if a new graph
+  // is built from an empty graph, then it can be signaled with the
+  // clear() and build() members. Important rule that if we erase items
+  // from graphs we should first signal the alteration and after that erase
+  // them from the container, on the other way on item addition we should
+  // first extend the container and just after that signal the alteration.
+  //
+  // The alteration can be observed with a class inherited from the
+  // ObserverBase nested class. The signals can be handled with
+  // overriding the virtual functions defined in the base class.  The
+  // observer base can be attached to the notifier with the
+  // attach() member and can be detached with detach() function. The
+  // alteration handlers should not call any function which signals
+  // an other alteration in the same notifier and should not
+  // detach any observer from the notifier.
+  //
+  // Alteration observers try to be exception safe. If an add() or
+  // a clear() function throws an exception then the remaining
+  // observeres will not be notified and the fulfilled additions will
+  // be rolled back by calling the erase() or clear() functions.
+  // Hence erase() and clear() should not throw exception.
+  // Actullay, they can throw only \ref ImmediateDetach exception,
+  // which detach the observer from the notifier.
+  //
+  // There are some cases, when the alteration observing is not completly
+  // reliable. If we want to carry out the node degree in the graph
+  // as in the \ref InDegMap and we use the reverseArc(), then it cause
+  // unreliable functionality. Because the alteration observing signals
+  // only erasing and adding but not the reversing, it will stores bad
+  // degrees. Apart form that the subgraph adaptors cannot even signal
+  // the alterations because just a setting in the filter map can modify
+  // the graph and this cannot be watched in any way.
+  //
+  // \param _Container The container which is observed.
+  // \param _Item The item type which is obserbved.
+
+  template <typename _Container, typename _Item>
+  class AlterationNotifier {
+  public:
+
+    typedef True Notifier;
+
+    typedef _Container Container;
+    typedef _Item Item;
+
+    // \brief Exception which can be called from clear() and
+    // erase().
+    //
+    // From the clear() and erase() function only this
+    // exception is allowed to throw. The exception immediatly
+    // detaches the current observer from the notifier. Because the
+    // clear() and erase() should not throw other exceptions
+    // it can be used to invalidate the observer.
+    struct ImmediateDetach {};
+
+    // \brief ObserverBase is the base class for the observers.
+    //
+    // ObserverBase is the abstract base class for the observers.
+    // It will be notified about an item was inserted into or
+    // erased from the graph.
+    //
+    // The observer interface contains some pure virtual functions
+    // to override. The add() and erase() functions are
+    // to notify the oberver when one item is added or erased.
+    //
+    // The build() and clear() members are to notify the observer
+    // about the container is built from an empty container or
+    // is cleared to an empty container.
+    class ObserverBase {
+    protected:
+      typedef AlterationNotifier Notifier;
+
+      friend class AlterationNotifier;
+
+      // \brief Default constructor.
+      //
+      // Default constructor for ObserverBase.
+      ObserverBase() : _notifier(0) {}
+
+      // \brief Constructor which attach the observer into notifier.
+      //
+      // Constructor which attach the observer into notifier.
+      ObserverBase(AlterationNotifier& nf) {
+        attach(nf);
+      }
+
+      // \brief Constructor which attach the obserever to the same notifier.
+      //
+      // Constructor which attach the obserever to the same notifier as
+      // the other observer is attached to.
+      ObserverBase(const ObserverBase& copy) {
+        if (copy.attached()) {
+          attach(*copy.notifier());
+        }
+      }
+
+      // \brief Destructor
+      virtual ~ObserverBase() {
+        if (attached()) {
+          detach();
+        }
+      }
+
+      // \brief Attaches the observer into an AlterationNotifier.
+      //
+      // This member attaches the observer into an AlterationNotifier.
+      void attach(AlterationNotifier& nf) {
+        nf.attach(*this);
+      }
+
+      // \brief Detaches the observer into an AlterationNotifier.
+      //
+      // This member detaches the observer from an AlterationNotifier.
+      void detach() {
+        _notifier->detach(*this);
+      }
+
+      // \brief Gives back a pointer to the notifier which the map
+      // attached into.
+      //
+      // This function gives back a pointer to the notifier which the map
+      // attached into.
+      Notifier* notifier() const { return const_cast<Notifier*>(_notifier); }
+
+      // Gives back true when the observer is attached into a notifier.
+      bool attached() const { return _notifier != 0; }
+
+    private:
+
+      ObserverBase& operator=(const ObserverBase& copy);
+
+    protected:
+
+      Notifier* _notifier;
+      typename std::list<ObserverBase*>::iterator _index;
+
+      // \brief The member function to notificate the observer about an
+      // item is added to the container.
+      //
+      // The add() member function notificates the observer about an item
+      // is added to the container. It have to be overrided in the
+      // subclasses.
+      virtual void add(const Item&) = 0;
+
+      // \brief The member function to notificate the observer about
+      // more item is added to the container.
+      //
+      // The add() member function notificates the observer about more item
+      // is added to the container. It have to be overrided in the
+      // subclasses.
+      virtual void add(const std::vector<Item>& items) = 0;
+
+      // \brief The member function to notificate the observer about an
+      // item is erased from the container.
+      //
+      // The erase() member function notificates the observer about an
+      // item is erased from the container. It have to be overrided in
+      // the subclasses.
+      virtual void erase(const Item&) = 0;
+
+      // \brief The member function to notificate the observer about
+      // more item is erased from the container.
+      //
+      // The erase() member function notificates the observer about more item
+      // is erased from the container. It have to be overrided in the
+      // subclasses.
+      virtual void erase(const std::vector<Item>& items) = 0;
+
+      // \brief The member function to notificate the observer about the
+      // container is built.
+      //
+      // The build() member function notificates the observer about the
+      // container is built from an empty container. It have to be
+      // overrided in the subclasses.
+      virtual void build() = 0;
+
+      // \brief The member function to notificate the observer about all
+      // items are erased from the container.
+      //
+      // The clear() member function notificates the observer about all
+      // items are erased from the container. It have to be overrided in
+      // the subclasses.
+      virtual void clear() = 0;
+
+    };
+
+  protected:
+
+    const Container* container;
+
+    typedef std::list<ObserverBase*> Observers;
+    Observers _observers;
+    lemon::bits::Lock _lock;
+
+  public:
+
+    // \brief Default constructor.
+    //
+    // The default constructor of the AlterationNotifier.
+    // It creates an empty notifier.
+    AlterationNotifier()
+      : container(0) {}
+
+    // \brief Constructor.
+    //
+    // Constructor with the observed container parameter.
+    AlterationNotifier(const Container& _container)
+      : container(&_container) {}
+
+    // \brief Copy Constructor of the AlterationNotifier.
+    //
+    // Copy constructor of the AlterationNotifier.
+    // It creates only an empty notifier because the copiable
+    // notifier's observers have to be registered still into that notifier.
+    AlterationNotifier(const AlterationNotifier& _notifier)
+      : container(_notifier.container) {}
+
+    // \brief Destructor.
+    //
+    // Destructor of the AlterationNotifier.
+    ~AlterationNotifier() {
+      typename Observers::iterator it;
+      for (it = _observers.begin(); it != _observers.end(); ++it) {
+        (*it)->_notifier = 0;
+      }
+    }
+
+    // \brief Sets the container.
+    //
+    // Sets the container.
+    void setContainer(const Container& _container) {
+      container = &_container;
+    }
+
+  protected:
+
+    AlterationNotifier& operator=(const AlterationNotifier&);
+
+  public:
+
+    // \brief First item in the container.
+    //
+    // Returns the first item in the container. It is
+    // for start the iteration on the container.
+    void first(Item& item) const {
+      container->first(item);
+    }
+
+    // \brief Next item in the container.
+    //
+    // Returns the next item in the container. It is
+    // for iterate on the container.
+    void next(Item& item) const {
+      container->next(item);
+    }
+
+    // \brief Returns the id of the item.
+    //
+    // Returns the id of the item provided by the container.
+    int id(const Item& item) const {
+      return container->id(item);
+    }
+
+    // \brief Returns the maximum id of the container.
+    //
+    // Returns the maximum id of the container.
+    int maxId() const {
+      return container->maxId(Item());
+    }
+
+  protected:
+
+    void attach(ObserverBase& observer) {
+      _lock.lock();
+      observer._index = _observers.insert(_observers.begin(), &observer);
+      observer._notifier = this;
+      _lock.unlock();
+    }
+
+    void detach(ObserverBase& observer) {
+      _lock.lock();
+      _observers.erase(observer._index);
+      observer._index = _observers.end();
+      observer._notifier = 0;
+      _lock.unlock();
+    }
+
+  public:
+
+    // \brief Notifies all the registed observers about an item added to
+    // the container.
+    //
+    // It notifies all the registed observers about an item added to
+    // the container.
+    void add(const Item& item) {
+      typename Observers::reverse_iterator it;
+      try {
+        for (it = _observers.rbegin(); it != _observers.rend(); ++it) {
+          (*it)->add(item);
+        }
+      } catch (...) {
+        typename Observers::iterator jt;
+        for (jt = it.base(); jt != _observers.end(); ++jt) {
+          (*jt)->erase(item);
+        }
+        throw;
+      }
+    }
+
+    // \brief Notifies all the registed observers about more item added to
+    // the container.
+    //
+    // It notifies all the registed observers about more item added to
+    // the container.
+    void add(const std::vector<Item>& items) {
+      typename Observers::reverse_iterator it;
+      try {
+        for (it = _observers.rbegin(); it != _observers.rend(); ++it) {
+          (*it)->add(items);
+        }
+      } catch (...) {
+        typename Observers::iterator jt;
+        for (jt = it.base(); jt != _observers.end(); ++jt) {
+          (*jt)->erase(items);
+        }
+        throw;
+      }
+    }
+
+    // \brief Notifies all the registed observers about an item erased from
+    // the container.
+    //
+    // It notifies all the registed observers about an item erased from
+    // the container.
+    void erase(const Item& item) throw() {
+      typename Observers::iterator it = _observers.begin();
+      while (it != _observers.end()) {
+        try {
+          (*it)->erase(item);
+          ++it;
+        } catch (const ImmediateDetach&) {
+          (*it)->_index = _observers.end();
+          (*it)->_notifier = 0;
+          it = _observers.erase(it);
+        }
+      }
+    }
+
+    // \brief Notifies all the registed observers about more item erased
+    // from the container.
+    //
+    // It notifies all the registed observers about more item erased from
+    // the container.
+    void erase(const std::vector<Item>& items) {
+      typename Observers::iterator it = _observers.begin();
+      while (it != _observers.end()) {
+        try {
+          (*it)->erase(items);
+          ++it;
+        } catch (const ImmediateDetach&) {
+          (*it)->_index = _observers.end();
+          (*it)->_notifier = 0;
+          it = _observers.erase(it);
+        }
+      }
+    }
+
+    // \brief Notifies all the registed observers about the container is
+    // built.
+    //
+    // Notifies all the registed observers about the container is built
+    // from an empty container.
+    void build() {
+      typename Observers::reverse_iterator it;
+      try {
+        for (it = _observers.rbegin(); it != _observers.rend(); ++it) {
+          (*it)->build();
+        }
+      } catch (...) {
+        typename Observers::iterator jt;
+        for (jt = it.base(); jt != _observers.end(); ++jt) {
+          (*jt)->clear();
+        }
+        throw;
+      }
+    }
+
+    // \brief Notifies all the registed observers about all items are
+    // erased.
+    //
+    // Notifies all the registed observers about all items are erased
+    // from the container.
+    void clear() {
+      typename Observers::iterator it = _observers.begin();
+      while (it != _observers.end()) {
+        try {
+          (*it)->clear();
+          ++it;
+        } catch (const ImmediateDetach&) {
+          (*it)->_index = _observers.end();
+          (*it)->_notifier = 0;
+          it = _observers.erase(it);
+        }
+      }
+    }
+  };
+
+}
+
+#endif