diff --git a/lemon/bits/alteration_notifier.h b/lemon/bits/alteration_notifier.h --- a/lemon/bits/alteration_notifier.h +++ b/lemon/bits/alteration_notifier.h @@ -24,76 +24,75 @@ #include -///\ingroup graphbits -///\file -///\brief Observer notifier for graph alteration observers. +//\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. + // \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 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 class AlterationNotifier { @@ -104,92 +103,87 @@ 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. + // \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. - + // \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. - /// + // \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. + // \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. + // \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 + // \brief Destructor virtual ~ObserverBase() { if (attached()) { detach(); } } - /// \brief Attaches the observer into an AlterationNotifier. - /// - /// This member attaches the observer into an AlterationNotifier. - /// + // \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. - /// + // \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. - /// + // \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); } - /// Gives back true when the observer is attached into a notifier. + // Gives back true when the observer is attached into a notifier. bool attached() const { return _notifier != 0; } private: @@ -201,53 +195,52 @@ Notifier* _notifier; typename std::list::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. + // \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. + // \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& 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. + // \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. + // \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& 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. - + // \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. + // \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; }; @@ -262,31 +255,30 @@ public: - /// \brief Default constructor. - /// - /// The default constructor of the AlterationNotifier. - /// It creates an empty notifier. + // \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. + // \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. + // \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. - /// + // \brief Destructor. + // + // Destructor of the AlterationNotifier. ~AlterationNotifier() { typename Observers::iterator it; for (it = _observers.begin(); it != _observers.end(); ++it) { @@ -294,9 +286,9 @@ } } - /// \brief Sets the container. - /// - /// Sets the container. + // \brief Sets the container. + // + // Sets the container. void setContainer(const Container& _container) { container = &_container; } @@ -307,34 +299,32 @@ public: - - - /// \brief First item in the container. - /// - /// Returns the first item in the container. It is - /// for start the iteration on the container. + // \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. + // \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. + // \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. + // \brief Returns the maximum id of the container. + // + // Returns the maximum id of the container. int maxId() const { return container->maxId(Item()); } @@ -354,12 +344,11 @@ 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. - /// + // \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 { @@ -375,12 +364,11 @@ } } - /// \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. - /// + // \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& items) { typename Observers::reverse_iterator it; try { @@ -396,12 +384,11 @@ } } - /// \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. - /// + // \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()) { @@ -416,12 +403,11 @@ } } - /// \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. - /// + // \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& items) { typename Observers::iterator it = _observers.begin(); while (it != _observers.end()) { @@ -436,11 +422,11 @@ } } - /// \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. + // \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 { @@ -456,11 +442,11 @@ } } - /// \brief Notifies all the registed observers about all items are - /// erased. - /// - /// Notifies all the registed observers about all items are erased - /// from the container. + // \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()) {