1.1 --- a/lemon/bits/alteration_notifier.h Fri Oct 16 10:21:37 2009 +0200
1.2 +++ b/lemon/bits/alteration_notifier.h Thu Nov 05 15:50:01 2009 +0100
1.3 @@ -2,7 +2,7 @@
1.4 *
1.5 * This file is a part of LEMON, a generic C++ optimization library.
1.6 *
1.7 - * Copyright (C) 2003-2008
1.8 + * Copyright (C) 2003-2009
1.9 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
1.10 * (Egervary Research Group on Combinatorial Optimization, EGRES).
1.11 *
1.12 @@ -35,61 +35,62 @@
1.13 // \brief Notifier class to notify observes about alterations in
1.14 // a container.
1.15 //
1.16 - // The simple graph's can be refered as two containers, one node container
1.17 - // and one edge container. But they are not standard containers they
1.18 - // does not store values directly they are just key continars for more
1.19 - // value containers which are the node and edge maps.
1.20 + // The simple graphs can be refered as two containers: a node container
1.21 + // and an edge container. But they do not store values directly, they
1.22 + // are just key continars for more value containers, which are the
1.23 + // node and edge maps.
1.24 //
1.25 - // The graph's node and edge sets can be changed as we add or erase
1.26 + // The node and edge sets of the graphs 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 + // in the library. We use another solution: we notify all maps about
1.33 // an alteration in the graph, which cause only drawback on the
1.34 // alteration of the graph.
1.35 //
1.36 - // This class provides an interface to the container. The \e first() and \e
1.37 - // next() member functions make possible to iterate on the keys of the
1.38 - // container. The \e id() function returns an integer id for each key.
1.39 - // The \e maxId() function gives back an upper bound of the ids.
1.40 + // This class provides an interface to a node or edge container.
1.41 + // The first() and next() member functions make possible
1.42 + // to iterate on the keys of the container.
1.43 + // The id() function returns an integer id for each key.
1.44 + // The maxId() function gives back an upper bound of the ids.
1.45 //
1.46 // For the proper functonality of this class, we should notify it
1.47 - // about each alteration in the container. The alterations have four type
1.48 - // as \e add(), \e erase(), \e build() and \e clear(). The \e add() and
1.49 - // \e erase() signals that only one or few items added or erased to or
1.50 - // from the graph. If all items are erased from the graph or from an empty
1.51 - // graph a new graph is builded then it can be signaled with the
1.52 + // about each alteration in the container. The alterations have four type:
1.53 + // add(), erase(), build() and clear(). The add() and
1.54 + // erase() signal that only one or few items added or erased to or
1.55 + // from the graph. If all items are erased from the graph or if a new graph
1.56 + // is built from an empty graph, then it can be signaled with the
1.57 // clear() and build() members. Important rule that if we erase items
1.58 - // from graph we should first signal the alteration and after that erase
1.59 + // from graphs we should first signal the alteration and after that erase
1.60 // them from the container, on the other way on item addition we should
1.61 // first extend the container and just after that signal the alteration.
1.62 //
1.63 // The alteration can be observed with a class inherited from the
1.64 - // \e ObserverBase nested class. The signals can be handled with
1.65 + // ObserverBase nested class. The signals can be handled with
1.66 // overriding the virtual functions defined in the base class. The
1.67 // observer base can be attached to the notifier with the
1.68 - // \e attach() member and can be detached with detach() function. The
1.69 + // attach() member and can be detached with detach() function. The
1.70 // alteration handlers should not call any function which signals
1.71 // an other alteration in the same notifier and should not
1.72 // detach any observer from the notifier.
1.73 //
1.74 - // Alteration observers try to be exception safe. If an \e add() or
1.75 - // a \e clear() function throws an exception then the remaining
1.76 + // Alteration observers try to be exception safe. If an add() or
1.77 + // a clear() function throws an exception then the remaining
1.78 // observeres will not be notified and the fulfilled additions will
1.79 - // be rolled back by calling the \e erase() or \e clear()
1.80 - // functions. Thence the \e erase() and \e clear() should not throw
1.81 - // exception. Actullay, it can be throw only \ref ImmediateDetach
1.82 - // exception which detach the observer from the notifier.
1.83 + // be rolled back by calling the erase() or clear() functions.
1.84 + // Hence erase() and clear() should not throw exception.
1.85 + // Actullay, they can throw only \ref ImmediateDetach exception,
1.86 + // which detach the observer from the notifier.
1.87 //
1.88 - // There are some place when the alteration observing is not completly
1.89 + // There are some cases, 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 + // as in the \ref InDegMap and we use the reverseArc(), then it cause
1.93 // unreliable functionality. Because the alteration observing signals
1.94 - // only erasing and adding but not the reversing it will stores bad
1.95 - // degrees. The sub graph adaptors cannot signal the alterations because
1.96 - // just a setting in the filter map can modify the graph and this cannot
1.97 - // be watched in any way.
1.98 + // only erasing and adding but not the reversing, it will stores bad
1.99 + // degrees. Apart form that the subgraph adaptors cannot even signal
1.100 + // the alterations because just a setting in the filter map can modify
1.101 + // the graph and this cannot be watched in any way.
1.102 //
1.103 // \param _Container The container which is observed.
1.104 // \param _Item The item type which is obserbved.
1.105 @@ -103,13 +104,13 @@
1.106 typedef _Container Container;
1.107 typedef _Item Item;
1.108
1.109 - // \brief Exception which can be called from \e clear() and
1.110 - // \e erase().
1.111 + // \brief Exception which can be called from clear() and
1.112 + // erase().
1.113 //
1.114 - // From the \e clear() and \e erase() function only this
1.115 + // From the clear() and 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 + // clear() and erase() should not throw other exceptions
1.120 // it can be used to invalidate the observer.
1.121 struct ImmediateDetach {};
1.122
1.123 @@ -121,8 +122,7 @@
1.124 //
1.125 // The observer interface contains some pure virtual functions
1.126 // to override. The add() and erase() functions are
1.127 - // to notify the oberver when one item is added or
1.128 - // erased.
1.129 + // to notify the oberver when one item is added or erased.
1.130 //
1.131 // The build() and clear() members are to notify the observer
1.132 // about the container is built from an empty container or