source: lemon-main/lemon/bits/alteration_notifier.h @ 168:8ceb318224b1

/* -*- C++ -*-
 *
 * This file is a part of LEMON, a generic C++ optimization library
 *
 * Copyright (C) 2003-2008
 * 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/bits/utility.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 graph's can be refered as two containers, one node container
  /// and one edge container. But they are not standard containers they
  /// does not store values directly they are just key continars for more
  /// value containers which are the node and edge maps.
  ///
  /// The graph's node and edge sets 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 the container. The \e first() and \e 
  /// next() member functions make possible to iterate on the keys of the
  /// container. The \e id() function returns an integer id for each key.
  /// The \e 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
  /// as \e add(), \e erase(), \e build() and \e clear(). The \e add() and
  /// \e erase() signals that only one or few items added or erased to or
  /// from the graph. If all items are erased from the graph or from an empty
  /// graph a new graph is builded then it can be signaled with the
  /// clear() and build() members. Important rule that if we erase items 
  /// from graph 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
  /// \e 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 
  /// \e 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 \e add() or
  /// a \e clear() function throws an exception then the remaining
  /// observeres will not be notified and the fulfilled additions will
  /// be rolled back by calling the \e erase() or \e clear()
  /// functions. Thence the \e erase() and \e clear() should not throw
  /// exception. Actullay, it can be throw only 
  /// \ref AlterationObserver::ImmediateDetach ImmediateDetach
  /// exception which detach the observer from the notifier.
  ///
  /// There are some place 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 reverseEdge that cause 
  /// unreliable functionality. Because the alteration observing signals
  /// only erasing and adding but not the reversing it will stores bad
  /// degrees. The sub graph adaptors cannot 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 \e clear() and 
    /// \e erase().
    ///
    /// From the \e clear() and \e erase() function only this
    /// exception is allowed to throw. The exception immediatly
    /// detaches the current observer from the notifier. Because the
    /// \e clear() and \e 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;

                
  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) {
      observer._index = _observers.insert(_observers.begin(), &observer);
      observer._notifier = this;
    } 

    void detach(ObserverBase& observer) {
      _observers.erase(observer._index);
      observer._index = _observers.end();
      observer._notifier = 0;
    }

  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 = _observers.erase(it);
          (*it)->_index = _observers.end();
          (*it)->_notifier = 0;
        }
      }
    }

    /// \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 = _observers.erase(it);
          (*it)->_index = _observers.end();
          (*it)->_notifier = 0;
        }
      }
    }

    /// \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 = _observers.erase(it);
          (*it)->_index = _observers.end();
          (*it)->_notifier = 0;
        }
      }
    }
  };

}

#endif