lemon/bits/alteration_notifier.h
changeset 395 0c5dd7ceda03
parent 314 2cc60866a0c9
child 440 88ed40ad0d4f
equal deleted inserted replaced
8:b2102e1865db 9:11012a0c9de2
    33   // \ingroup graphbits
    33   // \ingroup graphbits
    34   //
    34   //
    35   // \brief Notifier class to notify observes about alterations in
    35   // \brief Notifier class to notify observes about alterations in
    36   // a container.
    36   // a container.
    37   //
    37   //
    38   // The simple graph's can be refered as two containers, one node container
    38   // The simple graphs can be refered as two containers: a node container
    39   // and one edge container. But they are not standard containers they
    39   // and an edge container. But they do not store values directly, they
    40   // does not store values directly they are just key continars for more
    40   // are just key continars for more value containers, which are the
    41   // value containers which are the node and edge maps.
    41   // node and edge maps.
    42   //
    42   //
    43   // The graph's node and edge sets can be changed as we add or erase
    43   // The node and edge sets of the graphs can be changed as we add or erase
    44   // nodes and edges in the graph. LEMON would like to handle easily
    44   // nodes and edges in the graph. LEMON would like to handle easily
    45   // that the node and edge maps should contain values for all nodes or
    45   // that the node and edge maps should contain values for all nodes or
    46   // edges. If we want to check on every indicing if the map contains
    46   // edges. If we want to check on every indicing if the map contains
    47   // the current indicing key that cause a drawback in the performance
    47   // the current indicing key that cause a drawback in the performance
    48   // in the library. We use another solution we notify all maps about
    48   // in the library. We use another solution: we notify all maps about
    49   // an alteration in the graph, which cause only drawback on the
    49   // an alteration in the graph, which cause only drawback on the
    50   // alteration of the graph.
    50   // alteration of the graph.
    51   //
    51   //
    52   // This class provides an interface to the container. The \e first() and \e
    52   // This class provides an interface to a node or edge container.
    53   // next() member functions make possible to iterate on the keys of the
    53   // The first() and next() member functions make possible
    54   // container. The \e id() function returns an integer id for each key.
    54   // to iterate on the keys of the container.
    55   // The \e maxId() function gives back an upper bound of the ids.
    55   // The id() function returns an integer id for each key.
       
    56   // The maxId() function gives back an upper bound of the ids.
    56   //
    57   //
    57   // For the proper functonality of this class, we should notify it
    58   // For the proper functonality of this class, we should notify it
    58   // about each alteration in the container. The alterations have four type
    59   // about each alteration in the container. The alterations have four type:
    59   // as \e add(), \e erase(), \e build() and \e clear(). The \e add() and
    60   // add(), erase(), build() and clear(). The add() and
    60   // \e erase() signals that only one or few items added or erased to or
    61   // erase() signal that only one or few items added or erased to or
    61   // from the graph. If all items are erased from the graph or from an empty
    62   // from the graph. If all items are erased from the graph or if a new graph
    62   // graph a new graph is builded then it can be signaled with the
    63   // is built from an empty graph, then it can be signaled with the
    63   // clear() and build() members. Important rule that if we erase items
    64   // clear() and build() members. Important rule that if we erase items
    64   // from graph we should first signal the alteration and after that erase
    65   // from graphs we should first signal the alteration and after that erase
    65   // them from the container, on the other way on item addition we should
    66   // them from the container, on the other way on item addition we should
    66   // first extend the container and just after that signal the alteration.
    67   // first extend the container and just after that signal the alteration.
    67   //
    68   //
    68   // The alteration can be observed with a class inherited from the
    69   // The alteration can be observed with a class inherited from the
    69   // \e ObserverBase nested class. The signals can be handled with
    70   // ObserverBase nested class. The signals can be handled with
    70   // overriding the virtual functions defined in the base class.  The
    71   // overriding the virtual functions defined in the base class.  The
    71   // observer base can be attached to the notifier with the
    72   // observer base can be attached to the notifier with the
    72   // \e attach() member and can be detached with detach() function. The
    73   // attach() member and can be detached with detach() function. The
    73   // alteration handlers should not call any function which signals
    74   // alteration handlers should not call any function which signals
    74   // an other alteration in the same notifier and should not
    75   // an other alteration in the same notifier and should not
    75   // detach any observer from the notifier.
    76   // detach any observer from the notifier.
    76   //
    77   //
    77   // Alteration observers try to be exception safe. If an \e add() or
    78   // Alteration observers try to be exception safe. If an add() or
    78   // a \e clear() function throws an exception then the remaining
    79   // a clear() function throws an exception then the remaining
    79   // observeres will not be notified and the fulfilled additions will
    80   // observeres will not be notified and the fulfilled additions will
    80   // be rolled back by calling the \e erase() or \e clear()
    81   // be rolled back by calling the erase() or clear() functions.
    81   // functions. Thence the \e erase() and \e clear() should not throw
    82   // Hence erase() and clear() should not throw exception.
    82   // exception. Actullay, it can be throw only \ref ImmediateDetach
    83   // Actullay, they can throw only \ref ImmediateDetach exception,
    83   // exception which detach the observer from the notifier.
    84   // which detach the observer from the notifier.
    84   //
    85   //
    85   // There are some place when the alteration observing is not completly
    86   // There are some cases, when the alteration observing is not completly
    86   // reliable. If we want to carry out the node degree in the graph
    87   // reliable. If we want to carry out the node degree in the graph
    87   // as in the \ref InDegMap and we use the reverseEdge that cause
    88   // as in the \ref InDegMap and we use the reverseArc(), then it cause
    88   // unreliable functionality. Because the alteration observing signals
    89   // unreliable functionality. Because the alteration observing signals
    89   // only erasing and adding but not the reversing it will stores bad
    90   // only erasing and adding but not the reversing, it will stores bad
    90   // degrees. The sub graph adaptors cannot signal the alterations because
    91   // degrees. Apart form that the subgraph adaptors cannot even signal
    91   // just a setting in the filter map can modify the graph and this cannot
    92   // the alterations because just a setting in the filter map can modify
    92   // be watched in any way.
    93   // the graph and this cannot be watched in any way.
    93   //
    94   //
    94   // \param _Container The container which is observed.
    95   // \param _Container The container which is observed.
    95   // \param _Item The item type which is obserbved.
    96   // \param _Item The item type which is obserbved.
    96 
    97 
    97   template <typename _Container, typename _Item>
    98   template <typename _Container, typename _Item>
   101     typedef True Notifier;
   102     typedef True Notifier;
   102 
   103 
   103     typedef _Container Container;
   104     typedef _Container Container;
   104     typedef _Item Item;
   105     typedef _Item Item;
   105 
   106 
   106     // \brief Exception which can be called from \e clear() and
   107     // \brief Exception which can be called from clear() and
   107     // \e erase().
   108     // erase().
   108     //
   109     //
   109     // From the \e clear() and \e erase() function only this
   110     // From the clear() and erase() function only this
   110     // exception is allowed to throw. The exception immediatly
   111     // exception is allowed to throw. The exception immediatly
   111     // detaches the current observer from the notifier. Because the
   112     // detaches the current observer from the notifier. Because the
   112     // \e clear() and \e erase() should not throw other exceptions
   113     // clear() and erase() should not throw other exceptions
   113     // it can be used to invalidate the observer.
   114     // it can be used to invalidate the observer.
   114     struct ImmediateDetach {};
   115     struct ImmediateDetach {};
   115 
   116 
   116     // \brief ObserverBase is the base class for the observers.
   117     // \brief ObserverBase is the base class for the observers.
   117     //
   118     //
   119     // It will be notified about an item was inserted into or
   120     // It will be notified about an item was inserted into or
   120     // erased from the graph.
   121     // erased from the graph.
   121     //
   122     //
   122     // The observer interface contains some pure virtual functions
   123     // The observer interface contains some pure virtual functions
   123     // to override. The add() and erase() functions are
   124     // to override. The add() and erase() functions are
   124     // to notify the oberver when one item is added or
   125     // to notify the oberver when one item is added or erased.
   125     // erased.
       
   126     //
   126     //
   127     // The build() and clear() members are to notify the observer
   127     // The build() and clear() members are to notify the observer
   128     // about the container is built from an empty container or
   128     // about the container is built from an empty container or
   129     // is cleared to an empty container.
   129     // is cleared to an empty container.
   130     class ObserverBase {
   130     class ObserverBase {