1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/lemon/bits/alteration_notifier.h Sun Jan 20 20:43:48 2008 +0100
1.3 @@ -0,0 +1,485 @@
1.4 +/* -*- C++ -*-
1.5 + *
1.6 + * This file is a part of LEMON, a generic C++ optimization library
1.7 + *
1.8 + * Copyright (C) 2003-2007
1.9 + * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
1.10 + * (Egervary Research Group on Combinatorial Optimization, EGRES).
1.11 + *
1.12 + * Permission to use, modify and distribute this software is granted
1.13 + * provided that this copyright notice appears in all copies. For
1.14 + * precise terms see the accompanying LICENSE file.
1.15 + *
1.16 + * This software is provided "AS IS" with no warranty of any kind,
1.17 + * express or implied, and with no claim as to its suitability for any
1.18 + * purpose.
1.19 + *
1.20 + */
1.21 +
1.22 +#ifndef LEMON_BITS_ALTERATION_NOTIFIER_H
1.23 +#define LEMON_BITS_ALTERATION_NOTIFIER_H
1.24 +
1.25 +#include <vector>
1.26 +#include <list>
1.27 +
1.28 +#include <lemon/bits/utility.h>
1.29 +
1.30 +///\ingroup graphbits
1.31 +///\file
1.32 +///\brief Observer notifier for graph alteration observers.
1.33 +
1.34 +namespace lemon {
1.35 +
1.36 + /// \ingroup graphbits
1.37 + ///
1.38 + /// \brief Notifier class to notify observes about alterations in
1.39 + /// a container.
1.40 + ///
1.41 + /// The simple graph's can be refered as two containers, one node container
1.42 + /// and one edge container. But they are not standard containers they
1.43 + /// does not store values directly they are just key continars for more
1.44 + /// value containers which are the node and edge maps.
1.45 + ///
1.46 + /// The graph's node and edge sets can be changed as we add or erase
1.47 + /// nodes and edges in the graph. Lemon would like to handle easily
1.48 + /// that the node and edge maps should contain values for all nodes or
1.49 + /// edges. If we want to check on every indicing if the map contains
1.50 + /// the current indicing key that cause a drawback in the performance
1.51 + /// in the library. We use another solution we notify all maps about
1.52 + /// an alteration in the graph, which cause only drawback on the
1.53 + /// alteration of the graph.
1.54 + ///
1.55 + /// This class provides an interface to the container. The \e first() and \e
1.56 + /// next() member functions make possible to iterate on the keys of the
1.57 + /// container. The \e id() function returns an integer id for each key.
1.58 + /// The \e maxId() function gives back an upper bound of the ids.
1.59 + ///
1.60 + /// For the proper functonality of this class, we should notify it
1.61 + /// about each alteration in the container. The alterations have four type
1.62 + /// as \e add(), \e erase(), \e build() and \e clear(). The \e add() and
1.63 + /// \e erase() signals that only one or few items added or erased to or
1.64 + /// from the graph. If all items are erased from the graph or from an empty
1.65 + /// graph a new graph is builded then it can be signaled with the
1.66 + /// clear() and build() members. Important rule that if we erase items
1.67 + /// from graph we should first signal the alteration and after that erase
1.68 + /// them from the container, on the other way on item addition we should
1.69 + /// first extend the container and just after that signal the alteration.
1.70 + ///
1.71 + /// The alteration can be observed with a class inherited from the
1.72 + /// \e ObserverBase nested class. The signals can be handled with
1.73 + /// overriding the virtual functions defined in the base class. The
1.74 + /// observer base can be attached to the notifier with the
1.75 + /// \e attach() member and can be detached with detach() function. The
1.76 + /// alteration handlers should not call any function which signals
1.77 + /// an other alteration in the same notifier and should not
1.78 + /// detach any observer from the notifier.
1.79 + ///
1.80 + /// Alteration observers try to be exception safe. If an \e add() or
1.81 + /// a \e clear() function throws an exception then the remaining
1.82 + /// observeres will not be notified and the fulfilled additions will
1.83 + /// be rolled back by calling the \e erase() or \e clear()
1.84 + /// functions. Thence the \e erase() and \e clear() should not throw
1.85 + /// exception. Actullay, it can be throw only
1.86 + /// \ref AlterationObserver::ImmediateDetach ImmediateDetach
1.87 + /// exception which detach the observer from the notifier.
1.88 + ///
1.89 + /// There are some place when the alteration observing is not completly
1.90 + /// reliable. If we want to carry out the node degree in the graph
1.91 + /// as in the \ref InDegMap and we use the reverseEdge that cause
1.92 + /// unreliable functionality. Because the alteration observing signals
1.93 + /// only erasing and adding but not the reversing it will stores bad
1.94 + /// degrees. The sub graph adaptors cannot signal the alterations because
1.95 + /// just a setting in the filter map can modify the graph and this cannot
1.96 + /// be watched in any way.
1.97 + ///
1.98 + /// \param _Container The container which is observed.
1.99 + /// \param _Item The item type which is obserbved.
1.100 + ///
1.101 + /// \author Balazs Dezso
1.102 +
1.103 + template <typename _Container, typename _Item>
1.104 + class AlterationNotifier {
1.105 + public:
1.106 +
1.107 + typedef True Notifier;
1.108 +
1.109 + typedef _Container Container;
1.110 + typedef _Item Item;
1.111 +
1.112 + /// \brief Exception which can be called from \e clear() and
1.113 + /// \e erase().
1.114 + ///
1.115 + /// From the \e clear() and \e erase() function only this
1.116 + /// exception is allowed to throw. The exception immediatly
1.117 + /// detaches the current observer from the notifier. Because the
1.118 + /// \e clear() and \e erase() should not throw other exceptions
1.119 + /// it can be used to invalidate the observer.
1.120 + struct ImmediateDetach {};
1.121 +
1.122 + /// \brief ObserverBase is the base class for the observers.
1.123 + ///
1.124 + /// ObserverBase is the abstract base class for the observers.
1.125 + /// It will be notified about an item was inserted into or
1.126 + /// erased from the graph.
1.127 + ///
1.128 + /// The observer interface contains some pure virtual functions
1.129 + /// to override. The add() and erase() functions are
1.130 + /// to notify the oberver when one item is added or
1.131 + /// erased.
1.132 + ///
1.133 + /// The build() and clear() members are to notify the observer
1.134 + /// about the container is built from an empty container or
1.135 + /// is cleared to an empty container.
1.136 + ///
1.137 + /// \author Balazs Dezso
1.138 +
1.139 + class ObserverBase {
1.140 + protected:
1.141 + typedef AlterationNotifier Notifier;
1.142 +
1.143 + friend class AlterationNotifier;
1.144 +
1.145 + /// \brief Default constructor.
1.146 + ///
1.147 + /// Default constructor for ObserverBase.
1.148 + ///
1.149 + ObserverBase() : _notifier(0) {}
1.150 +
1.151 + /// \brief Constructor which attach the observer into notifier.
1.152 + ///
1.153 + /// Constructor which attach the observer into notifier.
1.154 + ObserverBase(AlterationNotifier& nf) {
1.155 + attach(nf);
1.156 + }
1.157 +
1.158 + /// \brief Constructor which attach the obserever to the same notifier.
1.159 + ///
1.160 + /// Constructor which attach the obserever to the same notifier as
1.161 + /// the other observer is attached to.
1.162 + ObserverBase(const ObserverBase& copy) {
1.163 + if (copy.attached()) {
1.164 + attach(*copy.notifier());
1.165 + }
1.166 + }
1.167 +
1.168 + /// \brief Destructor
1.169 + virtual ~ObserverBase() {
1.170 + if (attached()) {
1.171 + detach();
1.172 + }
1.173 + }
1.174 +
1.175 + /// \brief Attaches the observer into an AlterationNotifier.
1.176 + ///
1.177 + /// This member attaches the observer into an AlterationNotifier.
1.178 + ///
1.179 + void attach(AlterationNotifier& nf) {
1.180 + nf.attach(*this);
1.181 + }
1.182 +
1.183 + /// \brief Detaches the observer into an AlterationNotifier.
1.184 + ///
1.185 + /// This member detaches the observer from an AlterationNotifier.
1.186 + ///
1.187 + void detach() {
1.188 + _notifier->detach(*this);
1.189 + }
1.190 +
1.191 + /// \brief Gives back a pointer to the notifier which the map
1.192 + /// attached into.
1.193 + ///
1.194 + /// This function gives back a pointer to the notifier which the map
1.195 + /// attached into.
1.196 + ///
1.197 + Notifier* notifier() const { return const_cast<Notifier*>(_notifier); }
1.198 +
1.199 + /// Gives back true when the observer is attached into a notifier.
1.200 + bool attached() const { return _notifier != 0; }
1.201 +
1.202 + private:
1.203 +
1.204 + ObserverBase& operator=(const ObserverBase& copy);
1.205 +
1.206 + protected:
1.207 +
1.208 + Notifier* _notifier;
1.209 + typename std::list<ObserverBase*>::iterator _index;
1.210 +
1.211 + /// \brief The member function to notificate the observer about an
1.212 + /// item is added to the container.
1.213 + ///
1.214 + /// The add() member function notificates the observer about an item
1.215 + /// is added to the container. It have to be overrided in the
1.216 + /// subclasses.
1.217 + virtual void add(const Item&) = 0;
1.218 +
1.219 + /// \brief The member function to notificate the observer about
1.220 + /// more item is added to the container.
1.221 + ///
1.222 + /// The add() member function notificates the observer about more item
1.223 + /// is added to the container. It have to be overrided in the
1.224 + /// subclasses.
1.225 + virtual void add(const std::vector<Item>& items) = 0;
1.226 +
1.227 + /// \brief The member function to notificate the observer about an
1.228 + /// item is erased from the container.
1.229 + ///
1.230 + /// The erase() member function notificates the observer about an
1.231 + /// item is erased from the container. It have to be overrided in
1.232 + /// the subclasses.
1.233 + virtual void erase(const Item&) = 0;
1.234 +
1.235 + /// \brief The member function to notificate the observer about
1.236 + /// more item is erased from the container.
1.237 + ///
1.238 + /// The erase() member function notificates the observer about more item
1.239 + /// is erased from the container. It have to be overrided in the
1.240 + /// subclasses.
1.241 + virtual void erase(const std::vector<Item>& items) = 0;
1.242 +
1.243 + /// \brief The member function to notificate the observer about the
1.244 + /// container is built.
1.245 + ///
1.246 + /// The build() member function notificates the observer about the
1.247 + /// container is built from an empty container. It have to be
1.248 + /// overrided in the subclasses.
1.249 +
1.250 + virtual void build() = 0;
1.251 +
1.252 + /// \brief The member function to notificate the observer about all
1.253 + /// items are erased from the container.
1.254 + ///
1.255 + /// The clear() member function notificates the observer about all
1.256 + /// items are erased from the container. It have to be overrided in
1.257 + /// the subclasses.
1.258 + virtual void clear() = 0;
1.259 +
1.260 + };
1.261 +
1.262 + protected:
1.263 +
1.264 + const Container* container;
1.265 +
1.266 + typedef std::list<ObserverBase*> Observers;
1.267 + Observers _observers;
1.268 +
1.269 +
1.270 + public:
1.271 +
1.272 + /// \brief Default constructor.
1.273 + ///
1.274 + /// The default constructor of the AlterationNotifier.
1.275 + /// It creates an empty notifier.
1.276 + AlterationNotifier()
1.277 + : container(0) {}
1.278 +
1.279 + /// \brief Constructor.
1.280 + ///
1.281 + /// Constructor with the observed container parameter.
1.282 + AlterationNotifier(const Container& _container)
1.283 + : container(&_container) {}
1.284 +
1.285 + /// \brief Copy Constructor of the AlterationNotifier.
1.286 + ///
1.287 + /// Copy constructor of the AlterationNotifier.
1.288 + /// It creates only an empty notifier because the copiable
1.289 + /// notifier's observers have to be registered still into that notifier.
1.290 + AlterationNotifier(const AlterationNotifier& _notifier)
1.291 + : container(_notifier.container) {}
1.292 +
1.293 + /// \brief Destructor.
1.294 + ///
1.295 + /// Destructor of the AlterationNotifier.
1.296 + ///
1.297 + ~AlterationNotifier() {
1.298 + typename Observers::iterator it;
1.299 + for (it = _observers.begin(); it != _observers.end(); ++it) {
1.300 + (*it)->_notifier = 0;
1.301 + }
1.302 + }
1.303 +
1.304 + /// \brief Sets the container.
1.305 + ///
1.306 + /// Sets the container.
1.307 + void setContainer(const Container& _container) {
1.308 + container = &_container;
1.309 + }
1.310 +
1.311 + protected:
1.312 +
1.313 + AlterationNotifier& operator=(const AlterationNotifier&);
1.314 +
1.315 + public:
1.316 +
1.317 +
1.318 +
1.319 + /// \brief First item in the container.
1.320 + ///
1.321 + /// Returns the first item in the container. It is
1.322 + /// for start the iteration on the container.
1.323 + void first(Item& item) const {
1.324 + container->first(item);
1.325 + }
1.326 +
1.327 + /// \brief Next item in the container.
1.328 + ///
1.329 + /// Returns the next item in the container. It is
1.330 + /// for iterate on the container.
1.331 + void next(Item& item) const {
1.332 + container->next(item);
1.333 + }
1.334 +
1.335 + /// \brief Returns the id of the item.
1.336 + ///
1.337 + /// Returns the id of the item provided by the container.
1.338 + int id(const Item& item) const {
1.339 + return container->id(item);
1.340 + }
1.341 +
1.342 + /// \brief Returns the maximum id of the container.
1.343 + ///
1.344 + /// Returns the maximum id of the container.
1.345 + int maxId() const {
1.346 + return container->maxId(Item());
1.347 + }
1.348 +
1.349 + protected:
1.350 +
1.351 + void attach(ObserverBase& observer) {
1.352 + observer._index = _observers.insert(_observers.begin(), &observer);
1.353 + observer._notifier = this;
1.354 + }
1.355 +
1.356 + void detach(ObserverBase& observer) {
1.357 + _observers.erase(observer._index);
1.358 + observer._index = _observers.end();
1.359 + observer._notifier = 0;
1.360 + }
1.361 +
1.362 + public:
1.363 +
1.364 + /// \brief Notifies all the registed observers about an item added to
1.365 + /// the container.
1.366 + ///
1.367 + /// It notifies all the registed observers about an item added to
1.368 + /// the container.
1.369 + ///
1.370 + void add(const Item& item) {
1.371 + typename Observers::reverse_iterator it;
1.372 + try {
1.373 + for (it = _observers.rbegin(); it != _observers.rend(); ++it) {
1.374 + (*it)->add(item);
1.375 + }
1.376 + } catch (...) {
1.377 + typename Observers::iterator jt;
1.378 + for (jt = it.base(); jt != _observers.end(); ++jt) {
1.379 + (*jt)->erase(item);
1.380 + }
1.381 + throw;
1.382 + }
1.383 + }
1.384 +
1.385 + /// \brief Notifies all the registed observers about more item added to
1.386 + /// the container.
1.387 + ///
1.388 + /// It notifies all the registed observers about more item added to
1.389 + /// the container.
1.390 + ///
1.391 + void add(const std::vector<Item>& items) {
1.392 + typename Observers::reverse_iterator it;
1.393 + try {
1.394 + for (it = _observers.rbegin(); it != _observers.rend(); ++it) {
1.395 + (*it)->add(items);
1.396 + }
1.397 + } catch (...) {
1.398 + typename Observers::iterator jt;
1.399 + for (jt = it.base(); jt != _observers.end(); ++jt) {
1.400 + (*jt)->erase(items);
1.401 + }
1.402 + throw;
1.403 + }
1.404 + }
1.405 +
1.406 + /// \brief Notifies all the registed observers about an item erased from
1.407 + /// the container.
1.408 + ///
1.409 + /// It notifies all the registed observers about an item erased from
1.410 + /// the container.
1.411 + ///
1.412 + void erase(const Item& item) throw() {
1.413 + typename Observers::iterator it = _observers.begin();
1.414 + while (it != _observers.end()) {
1.415 + try {
1.416 + (*it)->erase(item);
1.417 + ++it;
1.418 + } catch (const ImmediateDetach&) {
1.419 + it = _observers.erase(it);
1.420 + (*it)->_index = _observers.end();
1.421 + (*it)->_notifier = 0;
1.422 + }
1.423 + }
1.424 + }
1.425 +
1.426 + /// \brief Notifies all the registed observers about more item erased
1.427 + /// from the container.
1.428 + ///
1.429 + /// It notifies all the registed observers about more item erased from
1.430 + /// the container.
1.431 + ///
1.432 + void erase(const std::vector<Item>& items) {
1.433 + typename Observers::iterator it = _observers.begin();
1.434 + while (it != _observers.end()) {
1.435 + try {
1.436 + (*it)->erase(items);
1.437 + ++it;
1.438 + } catch (const ImmediateDetach&) {
1.439 + it = _observers.erase(it);
1.440 + (*it)->_index = _observers.end();
1.441 + (*it)->_notifier = 0;
1.442 + }
1.443 + }
1.444 + }
1.445 +
1.446 + /// \brief Notifies all the registed observers about the container is
1.447 + /// built.
1.448 + ///
1.449 + /// Notifies all the registed observers about the container is built
1.450 + /// from an empty container.
1.451 + void build() {
1.452 + typename Observers::reverse_iterator it;
1.453 + try {
1.454 + for (it = _observers.rbegin(); it != _observers.rend(); ++it) {
1.455 + (*it)->build();
1.456 + }
1.457 + } catch (...) {
1.458 + typename Observers::iterator jt;
1.459 + for (jt = it.base(); jt != _observers.end(); ++jt) {
1.460 + (*jt)->clear();
1.461 + }
1.462 + throw;
1.463 + }
1.464 + }
1.465 +
1.466 + /// \brief Notifies all the registed observers about all items are
1.467 + /// erased.
1.468 + ///
1.469 + /// Notifies all the registed observers about all items are erased
1.470 + /// from the container.
1.471 + void clear() {
1.472 + typename Observers::iterator it = _observers.begin();
1.473 + while (it != _observers.end()) {
1.474 + try {
1.475 + (*it)->clear();
1.476 + ++it;
1.477 + } catch (const ImmediateDetach&) {
1.478 + it = _observers.erase(it);
1.479 + (*it)->_index = _observers.end();
1.480 + (*it)->_notifier = 0;
1.481 + }
1.482 + }
1.483 + }
1.484 + };
1.485 +
1.486 +}
1.487 +
1.488 +#endif