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> |