source: lemon-0.x/lemon/bits/alteration_notifier.h @ 1718:6a958ab38386

/* -*- C++ -*-
 * lemon/notifier.h - Part of LEMON, a generic C++ optimization library
 *
 * Copyright (C) 2005 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_ALTERATION_OBSERVER_REGISTRY_H
#define LEMON_ALTERATION_OBSERVER_REGISTRY_H

#include <vector>
#include <algorithm>

///\ingroup graphmapfactory
///\file
///\brief Observer registry for graph alteration observers.

namespace lemon {

  /// \addtogroup graphmapfactory
  /// @{

  /// \brief Registry class to register objects observes alterations in 
  /// the graph.
  ///
  /// This class is a registry for the objects which observe the
  /// alterations in a container. The alteration observers can be attached
  /// to and detached from the registry. The observers have to inherit
  /// from the \ref AlterationNotifier::ObserverBase and override
  /// the virtual functions in that.
  ///
  /// The most important application of the alteration observing is the
  /// dynamic map implementation.
  ///
  /// \param _Item The item type what the observers are observing, usually
  /// edge or node.
  ///
  /// \author Balazs Dezso

  template <typename _Item>
  class AlterationNotifier {
  public:
    typedef _Item Item;

    /// 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. 
    /// 
    /// \author Balazs Dezso

    class ObserverBase {
    protected:
      typedef AlterationNotifier Registry;

      friend class AlterationNotifier;

      /// \brief Default constructor.
      ///
      /// Default constructor for ObserverBase.
      /// 
      ObserverBase() : registry(0) {}

      ObserverBase(const ObserverBase& copy) {
        if (copy.attached()) {
          copy.getRegistry()->attach(*this);
        }
      }
        
      virtual ~ObserverBase() {}

      /// \brief Attaches the observer into an AlterationNotifier.
      ///
      /// This member attaches the observer into an AlterationNotifier.
      ///
      void attach(AlterationNotifier& r) {
        registry = &r;
        registry->attach(*this);
      }

      /// \brief Detaches the observer into an AlterationNotifier.
      ///
      /// This member detaches the observer from an AlterationNotifier.
      ///
      void detach() {
        if (registry) {
          registry->detach(*this);
        }
      }
        

      /// Gives back a pointer to the registry what the map attached into.

      /// This function gives back a pointer to the registry what the map
      /// attached into.
      ///
      Registry* getRegistry() const { return const_cast<Registry*>(registry); }
      
      /// Gives back true when the observer is attached into a registry.
      bool attached() const { return registry != 0; }

    private:

      ObserverBase& operator=(const ObserverBase& copy);

    protected:
      
      Registry* registry;
      int registry_index;

    public:

      /// \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) {
        for (int i = 0; i < (int)items.size(); ++i) {
          add(items[i]);
        }
      }

      /// \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) {
        for (int i = 0; i < (int)items.size(); ++i) {
          erase(items[i]);
        }
      }

      /// \brief Signal a property change on the given item.
      ///
      /// Signal a property change on the given item. It should
      /// be used always with the commitChange() function.
      /// This function is called always the property change.
      /// The commitChange() is called always after the change.
      virtual void signalChange(const Item&) {}

      /// \brief Commit the property change on the given item.
      ///
      /// Commit the property change on the given item. It should
      /// be used always with the signalChange() function.
      /// This function is called always the property change.
      /// The commitChange() is called always after the change.
      virtual void commitChange(const Item&) {}

      /// \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:
        

    typedef std::vector<ObserverBase*> Container; 

    Container container;

                
  public:

    /// Default constructor.
        
    ///
    /// The default constructor of the AlterationNotifier. 
    /// It creates an empty registry.
    AlterationNotifier() {}

    /// Copy Constructor of the AlterationNotifier. 
        
    /// Copy constructor of the AlterationNotifier. 
    /// It creates only an empty registry because the copiable
    /// registry's observers have to be registered still into that registry.
    AlterationNotifier(const AlterationNotifier&) {}

    /// Assign operator.
                
    /// Assign operator for the AlterationNotifier. 
    /// It makes the notifier only empty because the copiable
    /// notifier's observers have to be registered still into that registry.
    AlterationNotifier& operator=(const AlterationNotifier&) {
      typename Container::iterator it;
      for (it = container.begin(); it != container.end(); ++it) {
        (*it)->registry = 0;
      }
    }

    /// Destructor.
                                
    /// Destructor of the AlterationNotifier.
    ///
    ~AlterationNotifier() {
      typename Container::iterator it;
      for (it = container.begin(); it != container.end(); ++it) {
        (*it)->registry = 0;
      }
    }
        
        
  protected:

    void attach(ObserverBase& observer) {
      container.push_back(&observer);
      observer.registry = this;
      observer.registry_index = container.size()-1;
    } 

    void detach(ObserverBase& base) {
      container.back()->registry_index = base.registry_index; 
      container[base.registry_index] = container.back();
      container.pop_back();
      base.registry = 0;
    }

  public:
        
    /// \brief Notifies all the registered observers about an Item added to 
    /// the container.
    ///
    /// It notifies all the registered observers about an Item added to 
    /// the container.
    /// 
    void add(const Item& item) {
      typename Container::iterator it;
      for (it = container.begin(); it != container.end(); ++it) {
        (*it)->add(item);
      }
    }   

    /// \brief Notifies all the registered observers about more Item added to 
    /// the container.
    ///
    /// It notifies all the registered observers about more Item added to 
    /// the container.
    /// 
    void add(const std::vector<Item>& items) {
      typename Container::iterator it;
      for (it = container.begin(); it != container.end(); ++it) {
        (*it)->add(items);
      }
    }   

    /// \brief Notifies all the registered observers about an Item erased from 
    /// the container.
    /// 
    /// It notifies all the registered observers about an Item erased from 
    /// the container.
    /// 
    void erase(const Item& key) {
      typename Container::iterator it;
      for (it = container.begin(); it != container.end(); ++it) {
        (*it)->erase(key);
      }
    }

    /// \brief Notifies all the registered observers about more Item erased  
    /// from the container.
    /// 
    /// It notifies all the registered observers about more Item erased from 
    /// the container.
    /// 
    void erase(const std::vector<Item>& items) {
      typename Container::iterator it;
      for (it = container.begin(); it != container.end(); ++it) {
        (*it)->erase(items);
      }
    }
    
    /// \brief Signal a property change on the given item.
    ///
    /// Signal a property change on the given item. It should
    /// be used always with the commitChange() function.
    /// This function is called always the property change.
    /// The commitChange() is called always after the change.
    void signalChange(const Item& item) {
      typename Container::iterator it;
      for (it = container.begin(); it != container.end(); ++it) {
        (*it)->signalChange(item);
      }
    }
    
    /// \brief Commit the property change on the given item.
    ///
    /// Commit the property change on the given item. It should
    /// be used always with the signalChange() function.
    /// This function is called always the property change.
    /// The commitChange() is called always after the change.
    void commitChange(const Item& item) {
      typename Container::iterator it;
      for (it = container.begin(); it != container.end(); ++it) {
        (*it)->commitChange(item);
      }
    }

    /// \brief Notifies all the registered observers about the container is 
    /// built.
    ///         
    /// Notifies all the registered observers about the container is built
    /// from an empty container.
    void build() {
      typename Container::iterator it;
      for (it = container.begin(); it != container.end(); ++it) {
        (*it)->build();
      }
    }


    /// \brief Notifies all the registered observers about all Items are 
    /// erased.
    ///
    /// Notifies all the registered observers about all Items are erased
    /// from the container.
    void clear() {
      typename Container::iterator it;
      for (it = container.begin(); it != container.end(); ++it) {
        (*it)->clear();
      }
    }
  };


  /// \brief Class to extend a graph with the functionality of alteration
  /// observing.
  ///
  /// AlterableGraphExtender extends the _Base graphs functionality with
  /// the possibility of alteration observing. It defines two observer
  /// registrys for the nodes and mapes.
  /// 
  /// \todo Document what "alteration observing" is. And probably find a
  /// better (shorter) name.
  ///
  /// \param _Base is the base class to extend.
  ///
  /// \pre _Base is conform to the BaseGraphComponent concept.
  ///
  /// \post AlterableGraphExtender<_Base> is conform to the
  /// AlterableGraphComponent concept.
  ///
  /// \author Balazs Dezso

  template <typename _Base> 
  class AlterableGraphExtender : public _Base {
  public:

    typedef AlterableGraphExtender Graph;
    typedef _Base Parent;

    typedef typename Parent::Node Node;
    typedef typename Parent::Edge Edge;

    /// The edge observer registry.
    typedef AlterationNotifier<Edge> EdgeNotifier;
    /// The node observer registry.
    typedef AlterationNotifier<Node> NodeNotifier;


  protected:

    mutable EdgeNotifier edge_notifier;

    mutable NodeNotifier node_notifier;

  public:

    /// \brief Gives back the edge alteration notifier.
    ///
    /// Gives back the edge alteration notifier.
    EdgeNotifier& getNotifier(Edge) const {
      return edge_notifier;
    }

    /// \brief Gives back the node alteration notifier.
    ///
    /// Gives back the node alteration notifier.
    NodeNotifier& getNotifier(Node) const {
      return node_notifier;
    }

    ~AlterableGraphExtender() {
      node_notifier.clear();
      edge_notifier.clear();
    }
    
  };

  /// \brief Class to extend an undirected graph with the functionality of
  /// alteration observing.
  ///
  /// \todo Document.
  ///
  /// \sa AlterableGraphExtender
  ///
  /// \bug This should be done some other way. Possibilities: template
  /// specialization (not very easy, if at all possible); some kind of
  /// enable_if boost technique?

  template <typename _Base> 
  class AlterableUndirGraphExtender
    : public AlterableGraphExtender<_Base> {
  public:

    typedef AlterableUndirGraphExtender Graph;
    typedef AlterableGraphExtender<_Base> Parent;

    typedef typename Parent::UndirEdge UndirEdge;

    /// The edge observer registry.
    typedef AlterationNotifier<UndirEdge> UndirEdgeNotifier;

  protected:

    mutable UndirEdgeNotifier undir_edge_notifier;

  public:

    using Parent::getNotifier;
    UndirEdgeNotifier& getNotifier(UndirEdge) const {
      return undir_edge_notifier;
    }

    ~AlterableUndirGraphExtender() {
      undir_edge_notifier.clear();
    }
  };
  
/// @}
  

}

#endif