Changeset 1999:2ff283124dfc in lemon-0.x for lemon/bits/alteration_notifier.h

Timestamp:

03/06/06 11:28:37 (18 years ago)

Author:

Balazs Dezso

Branch:

default

Phase:

public

Convert:

svn:c9d7d8f5-90d6-0310-b91f-818b3a526b0e/lemon/trunk@2609

Message:

Clarifing alteration observing system
It is directly connected now to a container

File:

• lemon/bits/alteration_notifier.h (modified) (15 diffs)

lemon/bits/alteration_notifier.h

@@ -17 +17 @@
  */
 
-#ifndef LEMON_ALTERATION_NOTIFIER_H
-#define LEMON_ALTERATION_NOTIFIER_H
+#ifndef LEMON_BITS_ALTERATION_NOTIFIER_H
+#define LEMON_BITS_ALTERATION_NOTIFIER_H
 
 #include <vector>
-#include <algorithm>
+
+#include <lemon/bits/utility.h>
 
 ///\ingroup graphbits
 ///\file
-///\brief Observer registry for graph alteration observers.
+///\brief Observer notifier for graph alteration observers.
 
 namespace lemon {
 
-  /// \addtogroup graphbits
-  /// @{
-
-  /// \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.
+  /// \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 an other 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.
+  ///
+  /// Alteration observers try to be exception safe. This can be achived
+  /// when the observers does not throw exception on \e erase() and 
+  /// \e clear(). Less strict condition is that the \e erase() should
+  /// not throw exception after an \e add() with the same parameter and
+  /// the \e clear() should not throw exception after a \e build(). 
+  ///
+  /// 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.
   ///
   /// \author Balazs Dezso
 
-  template <typename _Item>
+  template <typename _Container, typename _Item>
   class AlterationNotifier {
   public:
@@ -55 +97 @@
     typedef True Notifier;
 
+    typedef _Container Container;
     typedef _Item Item;
 
-    /// ObserverBase is the base class for the observers.
-        
+    /// \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
@@ -76 +119 @@
     class ObserverBase {
     protected:
-      typedef AlterationNotifier Registry;
+      typedef AlterationNotifier Notifier;
 
       friend class AlterationNotifier;
@@ -84 +127 @@
       /// Default constructor for ObserverBase.
       /// 
-      ObserverBase() : registry(0) {}
-
+      ObserverBase() : notifier(0) {}
+
+      /// \brief Constructor which attach the observer into notifier.
+      ///
+      /// Constructor which attach the observer into notifier.
+      ObserverBase(AlterationNotifier& _notifier) {
+        attach(_notifier);
+      }
+
+      /// \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()) {
-          copy.getRegistry()->attach(*this);
+          attach(*copy.getNotifier());
         }
       }
         
-      virtual ~ObserverBase() {}
+      /// \brief Destructor
+      virtual ~ObserverBase() {
+        if (attached()) {
+          detach();
+        }
+      }
 
       /// \brief Attaches the observer into an AlterationNotifier.
@@ -98 +157 @@
       /// This member attaches the observer into an AlterationNotifier.
       ///
-      void attach(AlterationNotifier& r) {
-        registry = &r;
-        registry->attach(*this);
+      void attach(AlterationNotifier& _notifier) {
+        notifier = &_notifier;
+        notifier->attach(*this);
       }
 
@@ -108 +167 @@
       ///
       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
+        notifier->detach(*this);
+      }
+        
+
+      /// \brief Gives back a pointer to the notifier which the map 
       /// attached into.
       ///
-      Registry* getRegistry() const { return const_cast<Registry*>(registry); }
+      /// This function gives back a pointer to the notifier which the map
+      /// attached into.
+      ///
+      Notifier* getNotifier() const { return const_cast<Notifier*>(notifier); }
       
-      /// Gives back true when the observer is attached into a registry.
-      bool attached() const { return registry != 0; }
+      /// Gives back true when the observer is attached into a notifier.
+      bool attached() const { return notifier != 0; }
 
     private:
@@ -130 +188 @@
     protected:
       
-      Registry* registry;
-      int registry_index;
+      Notifier* notifier;
+      int notifier_index;
 
       /// \brief The member function to notificate the observer about an
@@ -150 +208 @@
 
       virtual void add(const std::vector<Item>& items) {
-        for (int i = 0; i < (int)items.size(); ++i) {
-          add(items[i]);
-        }
+        int i;
+        try {
+          for (i = 0; i < (int)items.size(); ++i) {
+            add(items[i]);
+          }
+        } catch (...) {
+          for (int j = 0; j < i; ++j) {
+            add(items[j]);
+          }          
+          throw;
+        }
       }
 
@@ -171 +237 @@
       /// subclasses.
       virtual void erase(const std::vector<Item>& items) {
-        for (int i = 0; i < (int)items.size(); ++i) {
-          erase(items[i]);
-        }
+        for (int i = 0; i < (int)items.size(); ++i) {
+          erase(items[i]);
+        }
       }
 
@@ -183 +249 @@
       /// overrided in the subclasses.
 
-      virtual void build() = 0;
+      virtual void build() {
+        Item it;
+        try {
+          for (notifier->first(it); it != INVALID; notifier->next(it)) {
+            add(it);
+          }
+        } catch (...) {
+          Item jt;
+          for (notifier->first(jt); jt != it; notifier->next(jt)) {
+            erase(jt);
+          }
+          throw;
+        }
+      }
 
       /// \brief The member function to notificate the observer about all
@@ -190 +269 @@
       /// 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;
+      /// the subclasses.      
+      virtual void clear() {
+        Item it;
+        for (notifier->first(it); it != INVALID; notifier->next(it)) {
+          erase(it);
+        }
+      }
 
     };
         
   protected:
-        
-
-    typedef std::vector<ObserverBase*> Container; 
-
-    Container container;
+
+    const Container* container;
+
+    typedef std::vector<ObserverBase*> Observers; 
+    Observers observers;
 
                 
   public:
 
-    /// Default constructor.
-        
+    /// \brief Default constructor.
     ///
     /// The default constructor of the AlterationNotifier. 
-    /// It creates an empty registry.
-    AlterationNotifier() {}
-
-    /// Copy 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 registry because the copiable
-    /// registry's observers have to be registered still into that registry.
-    AlterationNotifier(const AlterationNotifier&) {}
-
-    /// Assign operator.
+    /// 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());
+    }
                 
-    /// 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;
+      observers.push_back(&observer);
+      observer.notifier = this;
+      observer.notifier_index = observers.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;
+    void detach(ObserverBase& observer) {
+      observers.back()->notifier_index = observer.notifier_index; 
+      observers[observer.notifier_index] = observers.back();
+      observers.pop_back();
+      observer.notifier = 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 
+    /// \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 Container::iterator it;
+      typename Observers::iterator it;
       try {
-        for (it = container.begin(); it != container.end(); ++it) {
+        for (it = observers.begin(); it != observers.end(); ++it) {
           (*it)->add(item);
         }
       } catch (...) {
-        typename Container::iterator jt;
-        for (jt = container.begin(); jt != it; ++it) {
+        typename Observers::iterator jt;
+        for (jt = observers.begin(); jt != it; ++jt) {
           (*it)->erase(item);
         }
@@ -282 +404 @@
     }   
 
-    /// \brief Notifies all the registered observers about more Item added to 
-    /// the container.
-    ///
-    /// It notifies all the registered observers about more Item added to 
+    /// \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 Container::iterator it;
+      typename Observers::iterator it;
       try {
-        for (it = container.begin(); it != container.end(); ++it) {
+        for (it = observers.begin(); it != observers.end(); ++it) {
           (*it)->add(items);
         }
       } catch (...) {
-        typename Container::iterator jt;
-        for (jt = container.begin(); jt != it; ++it) {
+        typename Observers::iterator jt;
+        for (jt = observers.begin(); jt != it; ++jt) {
           (*it)->erase(items);
         }
@@ -303 +425 @@
     }   
 
-    /// \brief Notifies all the registered observers about an Item erased from 
+    /// \brief Notifies all the registed observers about an item erased from 
     /// the container.
     /// 
-    /// It notifies all the registered observers about an Item erased from 
+    /// It notifies all the registed 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) {
+      typename Observers::iterator it;
+      for (it = observers.begin(); it != observers.end(); ++it) {
         (*it)->erase(key);
       }
     }
 
-    /// \brief Notifies all the registered observers about more Item erased  
+    /// \brief Notifies all the registed observers about more item erased  
     /// from the container.
     /// 
-    /// It notifies all the registered observers about more Item erased from 
+    /// It notifies all the registed 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) {
+      typename Observers::iterator it;
+      for (it = observers.begin(); it != observers.end(); ++it) {
         (*it)->erase(items);
       }
     }
 
-    /// \brief Notifies all the registered observers about the container is 
+    /// \brief Notifies all the registed observers about the container is 
     /// built.
     ///         
-    /// Notifies all the registered observers about the container is built
+    /// Notifies all the registed observers about the container is built
     /// from an empty container.
     void build() {
-      typename Container::iterator it;
+      typename Observers::iterator it;
       try {
-        for (it = container.begin(); it != container.end(); ++it) {
+        for (it = observers.begin(); it != observers.end(); ++it) {
           (*it)->build();
         }
       } catch (...) {
-        typename Container::iterator jt;
-        for (jt = container.begin(); jt != it; ++it) {
+        typename Observers::iterator jt;
+        for (jt = observers.begin(); jt != it; ++jt) {
           (*it)->clear();
         }
@@ -350 +472 @@
 
 
-    /// \brief Notifies all the registered observers about all Items are 
+    /// \brief Notifies all the registed observers about all items are 
     /// erased.
     ///
-    /// Notifies all the registered observers about all Items are erased
+    /// Notifies all the registed observers about all items are erased
     /// from the container.
     void clear() {
-      typename Container::iterator it;
-      for (it = container.begin(); it != container.end(); ++it) {
+      typename Observers::iterator it;
+      for (it = observers.begin(); it != observers.end(); ++it) {
         (*it)->clear();
       }
@@ -363 +485 @@
   };
 
-  
-/// @}
-  
-
 }