/* -*- mode: C++; indent-tabs-mode: nil; -*-

  *

  * This file is a part of LEMON, a generic C++ optimization library.

  *

  * Copyright (C) 2003-2009

  * 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