1.1 --- a/lemon/bits/alteration_notifier.h Thu Oct 09 16:47:01 2008 +0200
1.2 +++ b/lemon/bits/alteration_notifier.h Thu Oct 09 16:20:37 2008 +0100
1.3 @@ -24,76 +24,75 @@
1.4
1.5 #include <lemon/core.h>
1.6
1.7 -///\ingroup graphbits
1.8 -///\file
1.9 -///\brief Observer notifier for graph alteration observers.
1.10 +//\ingroup graphbits
1.11 +//\file
1.12 +//\brief Observer notifier for graph alteration observers.
1.13
1.14 namespace lemon {
1.15
1.16 - /// \ingroup graphbits
1.17 - ///
1.18 - /// \brief Notifier class to notify observes about alterations in
1.19 - /// a container.
1.20 - ///
1.21 - /// The simple graph's can be refered as two containers, one node container
1.22 - /// and one edge container. But they are not standard containers they
1.23 - /// does not store values directly they are just key continars for more
1.24 - /// value containers which are the node and edge maps.
1.25 - ///
1.26 - /// The graph's node and edge sets can be changed as we add or erase
1.27 - /// nodes and edges in the graph. LEMON would like to handle easily
1.28 - /// that the node and edge maps should contain values for all nodes or
1.29 - /// edges. If we want to check on every indicing if the map contains
1.30 - /// the current indicing key that cause a drawback in the performance
1.31 - /// in the library. We use another solution we notify all maps about
1.32 - /// an alteration in the graph, which cause only drawback on the
1.33 - /// alteration of the graph.
1.34 - ///
1.35 - /// This class provides an interface to the container. The \e first() and \e
1.36 - /// next() member functions make possible to iterate on the keys of the
1.37 - /// container. The \e id() function returns an integer id for each key.
1.38 - /// The \e maxId() function gives back an upper bound of the ids.
1.39 - ///
1.40 - /// For the proper functonality of this class, we should notify it
1.41 - /// about each alteration in the container. The alterations have four type
1.42 - /// as \e add(), \e erase(), \e build() and \e clear(). The \e add() and
1.43 - /// \e erase() signals that only one or few items added or erased to or
1.44 - /// from the graph. If all items are erased from the graph or from an empty
1.45 - /// graph a new graph is builded then it can be signaled with the
1.46 - /// clear() and build() members. Important rule that if we erase items
1.47 - /// from graph we should first signal the alteration and after that erase
1.48 - /// them from the container, on the other way on item addition we should
1.49 - /// first extend the container and just after that signal the alteration.
1.50 - ///
1.51 - /// The alteration can be observed with a class inherited from the
1.52 - /// \e ObserverBase nested class. The signals can be handled with
1.53 - /// overriding the virtual functions defined in the base class. The
1.54 - /// observer base can be attached to the notifier with the
1.55 - /// \e attach() member and can be detached with detach() function. The
1.56 - /// alteration handlers should not call any function which signals
1.57 - /// an other alteration in the same notifier and should not
1.58 - /// detach any observer from the notifier.
1.59 - ///
1.60 - /// Alteration observers try to be exception safe. If an \e add() or
1.61 - /// a \e clear() function throws an exception then the remaining
1.62 - /// observeres will not be notified and the fulfilled additions will
1.63 - /// be rolled back by calling the \e erase() or \e clear()
1.64 - /// functions. Thence the \e erase() and \e clear() should not throw
1.65 - /// exception. Actullay, it can be throw only
1.66 - /// \ref AlterationObserver::ImmediateDetach ImmediateDetach
1.67 - /// exception which detach the observer from the notifier.
1.68 - ///
1.69 - /// There are some place when the alteration observing is not completly
1.70 - /// reliable. If we want to carry out the node degree in the graph
1.71 - /// as in the \ref InDegMap and we use the reverseEdge that cause
1.72 - /// unreliable functionality. Because the alteration observing signals
1.73 - /// only erasing and adding but not the reversing it will stores bad
1.74 - /// degrees. The sub graph adaptors cannot signal the alterations because
1.75 - /// just a setting in the filter map can modify the graph and this cannot
1.76 - /// be watched in any way.
1.77 - ///
1.78 - /// \param _Container The container which is observed.
1.79 - /// \param _Item The item type which is obserbved.
1.80 + // \ingroup graphbits
1.81 + //
1.82 + // \brief Notifier class to notify observes about alterations in
1.83 + // a container.
1.84 + //
1.85 + // The simple graph's can be refered as two containers, one node container
1.86 + // and one edge container. But they are not standard containers they
1.87 + // does not store values directly they are just key continars for more
1.88 + // value containers which are the node and edge maps.
1.89 + //
1.90 + // The graph's node and edge sets can be changed as we add or erase
1.91 + // nodes and edges in the graph. LEMON would like to handle easily
1.92 + // that the node and edge maps should contain values for all nodes or
1.93 + // edges. If we want to check on every indicing if the map contains
1.94 + // the current indicing key that cause a drawback in the performance
1.95 + // in the library. We use another solution we notify all maps about
1.96 + // an alteration in the graph, which cause only drawback on the
1.97 + // alteration of the graph.
1.98 + //
1.99 + // This class provides an interface to the container. The \e first() and \e
1.100 + // next() member functions make possible to iterate on the keys of the
1.101 + // container. The \e id() function returns an integer id for each key.
1.102 + // The \e maxId() function gives back an upper bound of the ids.
1.103 + //
1.104 + // For the proper functonality of this class, we should notify it
1.105 + // about each alteration in the container. The alterations have four type
1.106 + // as \e add(), \e erase(), \e build() and \e clear(). The \e add() and
1.107 + // \e erase() signals that only one or few items added or erased to or
1.108 + // from the graph. If all items are erased from the graph or from an empty
1.109 + // graph a new graph is builded then it can be signaled with the
1.110 + // clear() and build() members. Important rule that if we erase items
1.111 + // from graph we should first signal the alteration and after that erase
1.112 + // them from the container, on the other way on item addition we should
1.113 + // first extend the container and just after that signal the alteration.
1.114 + //
1.115 + // The alteration can be observed with a class inherited from the
1.116 + // \e ObserverBase nested class. The signals can be handled with
1.117 + // overriding the virtual functions defined in the base class. The
1.118 + // observer base can be attached to the notifier with the
1.119 + // \e attach() member and can be detached with detach() function. The
1.120 + // alteration handlers should not call any function which signals
1.121 + // an other alteration in the same notifier and should not
1.122 + // detach any observer from the notifier.
1.123 + //
1.124 + // Alteration observers try to be exception safe. If an \e add() or
1.125 + // a \e clear() function throws an exception then the remaining
1.126 + // observeres will not be notified and the fulfilled additions will
1.127 + // be rolled back by calling the \e erase() or \e clear()
1.128 + // functions. Thence the \e erase() and \e clear() should not throw
1.129 + // exception. Actullay, it can be throw only \ref ImmediateDetach
1.130 + // exception which detach the observer from the notifier.
1.131 + //
1.132 + // There are some place when the alteration observing is not completly
1.133 + // reliable. If we want to carry out the node degree in the graph
1.134 + // as in the \ref InDegMap and we use the reverseEdge that cause
1.135 + // unreliable functionality. Because the alteration observing signals
1.136 + // only erasing and adding but not the reversing it will stores bad
1.137 + // degrees. The sub graph adaptors cannot signal the alterations because
1.138 + // just a setting in the filter map can modify the graph and this cannot
1.139 + // be watched in any way.
1.140 + //
1.141 + // \param _Container The container which is observed.
1.142 + // \param _Item The item type which is obserbved.
1.143
1.144 template <typename _Container, typename _Item>
1.145 class AlterationNotifier {
1.146 @@ -104,92 +103,87 @@
1.147 typedef _Container Container;
1.148 typedef _Item Item;
1.149
1.150 - /// \brief Exception which can be called from \e clear() and
1.151 - /// \e erase().
1.152 - ///
1.153 - /// From the \e clear() and \e erase() function only this
1.154 - /// exception is allowed to throw. The exception immediatly
1.155 - /// detaches the current observer from the notifier. Because the
1.156 - /// \e clear() and \e erase() should not throw other exceptions
1.157 - /// it can be used to invalidate the observer.
1.158 + // \brief Exception which can be called from \e clear() and
1.159 + // \e erase().
1.160 + //
1.161 + // From the \e clear() and \e erase() function only this
1.162 + // exception is allowed to throw. The exception immediatly
1.163 + // detaches the current observer from the notifier. Because the
1.164 + // \e clear() and \e erase() should not throw other exceptions
1.165 + // it can be used to invalidate the observer.
1.166 struct ImmediateDetach {};
1.167
1.168 - /// \brief ObserverBase is the base class for the observers.
1.169 - ///
1.170 - /// ObserverBase is the abstract base class for the observers.
1.171 - /// It will be notified about an item was inserted into or
1.172 - /// erased from the graph.
1.173 - ///
1.174 - /// The observer interface contains some pure virtual functions
1.175 - /// to override. The add() and erase() functions are
1.176 - /// to notify the oberver when one item is added or
1.177 - /// erased.
1.178 - ///
1.179 - /// The build() and clear() members are to notify the observer
1.180 - /// about the container is built from an empty container or
1.181 - /// is cleared to an empty container.
1.182 -
1.183 + // \brief ObserverBase is the base class for the observers.
1.184 + //
1.185 + // ObserverBase is the abstract base class for the observers.
1.186 + // It will be notified about an item was inserted into or
1.187 + // erased from the graph.
1.188 + //
1.189 + // The observer interface contains some pure virtual functions
1.190 + // to override. The add() and erase() functions are
1.191 + // to notify the oberver when one item is added or
1.192 + // erased.
1.193 + //
1.194 + // The build() and clear() members are to notify the observer
1.195 + // about the container is built from an empty container or
1.196 + // is cleared to an empty container.
1.197 class ObserverBase {
1.198 protected:
1.199 typedef AlterationNotifier Notifier;
1.200
1.201 friend class AlterationNotifier;
1.202
1.203 - /// \brief Default constructor.
1.204 - ///
1.205 - /// Default constructor for ObserverBase.
1.206 - ///
1.207 + // \brief Default constructor.
1.208 + //
1.209 + // Default constructor for ObserverBase.
1.210 ObserverBase() : _notifier(0) {}
1.211
1.212 - /// \brief Constructor which attach the observer into notifier.
1.213 - ///
1.214 - /// Constructor which attach the observer into notifier.
1.215 + // \brief Constructor which attach the observer into notifier.
1.216 + //
1.217 + // Constructor which attach the observer into notifier.
1.218 ObserverBase(AlterationNotifier& nf) {
1.219 attach(nf);
1.220 }
1.221
1.222 - /// \brief Constructor which attach the obserever to the same notifier.
1.223 - ///
1.224 - /// Constructor which attach the obserever to the same notifier as
1.225 - /// the other observer is attached to.
1.226 + // \brief Constructor which attach the obserever to the same notifier.
1.227 + //
1.228 + // Constructor which attach the obserever to the same notifier as
1.229 + // the other observer is attached to.
1.230 ObserverBase(const ObserverBase& copy) {
1.231 if (copy.attached()) {
1.232 attach(*copy.notifier());
1.233 }
1.234 }
1.235
1.236 - /// \brief Destructor
1.237 + // \brief Destructor
1.238 virtual ~ObserverBase() {
1.239 if (attached()) {
1.240 detach();
1.241 }
1.242 }
1.243
1.244 - /// \brief Attaches the observer into an AlterationNotifier.
1.245 - ///
1.246 - /// This member attaches the observer into an AlterationNotifier.
1.247 - ///
1.248 + // \brief Attaches the observer into an AlterationNotifier.
1.249 + //
1.250 + // This member attaches the observer into an AlterationNotifier.
1.251 void attach(AlterationNotifier& nf) {
1.252 nf.attach(*this);
1.253 }
1.254
1.255 - /// \brief Detaches the observer into an AlterationNotifier.
1.256 - ///
1.257 - /// This member detaches the observer from an AlterationNotifier.
1.258 - ///
1.259 + // \brief Detaches the observer into an AlterationNotifier.
1.260 + //
1.261 + // This member detaches the observer from an AlterationNotifier.
1.262 void detach() {
1.263 _notifier->detach(*this);
1.264 }
1.265
1.266 - /// \brief Gives back a pointer to the notifier which the map
1.267 - /// attached into.
1.268 - ///
1.269 - /// This function gives back a pointer to the notifier which the map
1.270 - /// attached into.
1.271 - ///
1.272 + // \brief Gives back a pointer to the notifier which the map
1.273 + // attached into.
1.274 + //
1.275 + // This function gives back a pointer to the notifier which the map
1.276 + // attached into.
1.277 Notifier* notifier() const { return const_cast<Notifier*>(_notifier); }
1.278
1.279 - /// Gives back true when the observer is attached into a notifier.
1.280 + // Gives back true when the observer is attached into a notifier.
1.281 bool attached() const { return _notifier != 0; }
1.282
1.283 private:
1.284 @@ -201,53 +195,52 @@
1.285 Notifier* _notifier;
1.286 typename std::list<ObserverBase*>::iterator _index;
1.287
1.288 - /// \brief The member function to notificate the observer about an
1.289 - /// item is added to the container.
1.290 - ///
1.291 - /// The add() member function notificates the observer about an item
1.292 - /// is added to the container. It have to be overrided in the
1.293 - /// subclasses.
1.294 + // \brief The member function to notificate the observer about an
1.295 + // item is added to the container.
1.296 + //
1.297 + // The add() member function notificates the observer about an item
1.298 + // is added to the container. It have to be overrided in the
1.299 + // subclasses.
1.300 virtual void add(const Item&) = 0;
1.301
1.302 - /// \brief The member function to notificate the observer about
1.303 - /// more item is added to the container.
1.304 - ///
1.305 - /// The add() member function notificates the observer about more item
1.306 - /// is added to the container. It have to be overrided in the
1.307 - /// subclasses.
1.308 + // \brief The member function to notificate the observer about
1.309 + // more item is added to the container.
1.310 + //
1.311 + // The add() member function notificates the observer about more item
1.312 + // is added to the container. It have to be overrided in the
1.313 + // subclasses.
1.314 virtual void add(const std::vector<Item>& items) = 0;
1.315
1.316 - /// \brief The member function to notificate the observer about an
1.317 - /// item is erased from the container.
1.318 - ///
1.319 - /// The erase() member function notificates the observer about an
1.320 - /// item is erased from the container. It have to be overrided in
1.321 - /// the subclasses.
1.322 + // \brief The member function to notificate the observer about an
1.323 + // item is erased from the container.
1.324 + //
1.325 + // The erase() member function notificates the observer about an
1.326 + // item is erased from the container. It have to be overrided in
1.327 + // the subclasses.
1.328 virtual void erase(const Item&) = 0;
1.329
1.330 - /// \brief The member function to notificate the observer about
1.331 - /// more item is erased from the container.
1.332 - ///
1.333 - /// The erase() member function notificates the observer about more item
1.334 - /// is erased from the container. It have to be overrided in the
1.335 - /// subclasses.
1.336 + // \brief The member function to notificate the observer about
1.337 + // more item is erased from the container.
1.338 + //
1.339 + // The erase() member function notificates the observer about more item
1.340 + // is erased from the container. It have to be overrided in the
1.341 + // subclasses.
1.342 virtual void erase(const std::vector<Item>& items) = 0;
1.343
1.344 - /// \brief The member function to notificate the observer about the
1.345 - /// container is built.
1.346 - ///
1.347 - /// The build() member function notificates the observer about the
1.348 - /// container is built from an empty container. It have to be
1.349 - /// overrided in the subclasses.
1.350 -
1.351 + // \brief The member function to notificate the observer about the
1.352 + // container is built.
1.353 + //
1.354 + // The build() member function notificates the observer about the
1.355 + // container is built from an empty container. It have to be
1.356 + // overrided in the subclasses.
1.357 virtual void build() = 0;
1.358
1.359 - /// \brief The member function to notificate the observer about all
1.360 - /// items are erased from the container.
1.361 - ///
1.362 - /// The clear() member function notificates the observer about all
1.363 - /// items are erased from the container. It have to be overrided in
1.364 - /// the subclasses.
1.365 + // \brief The member function to notificate the observer about all
1.366 + // items are erased from the container.
1.367 + //
1.368 + // The clear() member function notificates the observer about all
1.369 + // items are erased from the container. It have to be overrided in
1.370 + // the subclasses.
1.371 virtual void clear() = 0;
1.372
1.373 };
1.374 @@ -262,31 +255,30 @@
1.375
1.376 public:
1.377
1.378 - /// \brief Default constructor.
1.379 - ///
1.380 - /// The default constructor of the AlterationNotifier.
1.381 - /// It creates an empty notifier.
1.382 + // \brief Default constructor.
1.383 + //
1.384 + // The default constructor of the AlterationNotifier.
1.385 + // It creates an empty notifier.
1.386 AlterationNotifier()
1.387 : container(0) {}
1.388
1.389 - /// \brief Constructor.
1.390 - ///
1.391 - /// Constructor with the observed container parameter.
1.392 + // \brief Constructor.
1.393 + //
1.394 + // Constructor with the observed container parameter.
1.395 AlterationNotifier(const Container& _container)
1.396 : container(&_container) {}
1.397
1.398 - /// \brief Copy Constructor of the AlterationNotifier.
1.399 - ///
1.400 - /// Copy constructor of the AlterationNotifier.
1.401 - /// It creates only an empty notifier because the copiable
1.402 - /// notifier's observers have to be registered still into that notifier.
1.403 + // \brief Copy Constructor of the AlterationNotifier.
1.404 + //
1.405 + // Copy constructor of the AlterationNotifier.
1.406 + // It creates only an empty notifier because the copiable
1.407 + // notifier's observers have to be registered still into that notifier.
1.408 AlterationNotifier(const AlterationNotifier& _notifier)
1.409 : container(_notifier.container) {}
1.410
1.411 - /// \brief Destructor.
1.412 - ///
1.413 - /// Destructor of the AlterationNotifier.
1.414 - ///
1.415 + // \brief Destructor.
1.416 + //
1.417 + // Destructor of the AlterationNotifier.
1.418 ~AlterationNotifier() {
1.419 typename Observers::iterator it;
1.420 for (it = _observers.begin(); it != _observers.end(); ++it) {
1.421 @@ -294,9 +286,9 @@
1.422 }
1.423 }
1.424
1.425 - /// \brief Sets the container.
1.426 - ///
1.427 - /// Sets the container.
1.428 + // \brief Sets the container.
1.429 + //
1.430 + // Sets the container.
1.431 void setContainer(const Container& _container) {
1.432 container = &_container;
1.433 }
1.434 @@ -307,34 +299,32 @@
1.435
1.436 public:
1.437
1.438 -
1.439 -
1.440 - /// \brief First item in the container.
1.441 - ///
1.442 - /// Returns the first item in the container. It is
1.443 - /// for start the iteration on the container.
1.444 + // \brief First item in the container.
1.445 + //
1.446 + // Returns the first item in the container. It is
1.447 + // for start the iteration on the container.
1.448 void first(Item& item) const {
1.449 container->first(item);
1.450 }
1.451
1.452 - /// \brief Next item in the container.
1.453 - ///
1.454 - /// Returns the next item in the container. It is
1.455 - /// for iterate on the container.
1.456 + // \brief Next item in the container.
1.457 + //
1.458 + // Returns the next item in the container. It is
1.459 + // for iterate on the container.
1.460 void next(Item& item) const {
1.461 container->next(item);
1.462 }
1.463
1.464 - /// \brief Returns the id of the item.
1.465 - ///
1.466 - /// Returns the id of the item provided by the container.
1.467 + // \brief Returns the id of the item.
1.468 + //
1.469 + // Returns the id of the item provided by the container.
1.470 int id(const Item& item) const {
1.471 return container->id(item);
1.472 }
1.473
1.474 - /// \brief Returns the maximum id of the container.
1.475 - ///
1.476 - /// Returns the maximum id of the container.
1.477 + // \brief Returns the maximum id of the container.
1.478 + //
1.479 + // Returns the maximum id of the container.
1.480 int maxId() const {
1.481 return container->maxId(Item());
1.482 }
1.483 @@ -354,12 +344,11 @@
1.484
1.485 public:
1.486
1.487 - /// \brief Notifies all the registed observers about an item added to
1.488 - /// the container.
1.489 - ///
1.490 - /// It notifies all the registed observers about an item added to
1.491 - /// the container.
1.492 - ///
1.493 + // \brief Notifies all the registed observers about an item added to
1.494 + // the container.
1.495 + //
1.496 + // It notifies all the registed observers about an item added to
1.497 + // the container.
1.498 void add(const Item& item) {
1.499 typename Observers::reverse_iterator it;
1.500 try {
1.501 @@ -375,12 +364,11 @@
1.502 }
1.503 }
1.504
1.505 - /// \brief Notifies all the registed observers about more item added to
1.506 - /// the container.
1.507 - ///
1.508 - /// It notifies all the registed observers about more item added to
1.509 - /// the container.
1.510 - ///
1.511 + // \brief Notifies all the registed observers about more item added to
1.512 + // the container.
1.513 + //
1.514 + // It notifies all the registed observers about more item added to
1.515 + // the container.
1.516 void add(const std::vector<Item>& items) {
1.517 typename Observers::reverse_iterator it;
1.518 try {
1.519 @@ -396,12 +384,11 @@
1.520 }
1.521 }
1.522
1.523 - /// \brief Notifies all the registed observers about an item erased from
1.524 - /// the container.
1.525 - ///
1.526 - /// It notifies all the registed observers about an item erased from
1.527 - /// the container.
1.528 - ///
1.529 + // \brief Notifies all the registed observers about an item erased from
1.530 + // the container.
1.531 + //
1.532 + // It notifies all the registed observers about an item erased from
1.533 + // the container.
1.534 void erase(const Item& item) throw() {
1.535 typename Observers::iterator it = _observers.begin();
1.536 while (it != _observers.end()) {
1.537 @@ -416,12 +403,11 @@
1.538 }
1.539 }
1.540
1.541 - /// \brief Notifies all the registed observers about more item erased
1.542 - /// from the container.
1.543 - ///
1.544 - /// It notifies all the registed observers about more item erased from
1.545 - /// the container.
1.546 - ///
1.547 + // \brief Notifies all the registed observers about more item erased
1.548 + // from the container.
1.549 + //
1.550 + // It notifies all the registed observers about more item erased from
1.551 + // the container.
1.552 void erase(const std::vector<Item>& items) {
1.553 typename Observers::iterator it = _observers.begin();
1.554 while (it != _observers.end()) {
1.555 @@ -436,11 +422,11 @@
1.556 }
1.557 }
1.558
1.559 - /// \brief Notifies all the registed observers about the container is
1.560 - /// built.
1.561 - ///
1.562 - /// Notifies all the registed observers about the container is built
1.563 - /// from an empty container.
1.564 + // \brief Notifies all the registed observers about the container is
1.565 + // built.
1.566 + //
1.567 + // Notifies all the registed observers about the container is built
1.568 + // from an empty container.
1.569 void build() {
1.570 typename Observers::reverse_iterator it;
1.571 try {
1.572 @@ -456,11 +442,11 @@
1.573 }
1.574 }
1.575
1.576 - /// \brief Notifies all the registed observers about all items are
1.577 - /// erased.
1.578 - ///
1.579 - /// Notifies all the registed observers about all items are erased
1.580 - /// from the container.
1.581 + // \brief Notifies all the registed observers about all items are
1.582 + // erased.
1.583 + //
1.584 + // Notifies all the registed observers about all items are erased
1.585 + // from the container.
1.586 void clear() {
1.587 typename Observers::iterator it = _observers.begin();
1.588 while (it != _observers.end()) {