Fawkes API  Fawkes Development Version
interface_observer.cpp
1 
2 /***************************************************************************
3  * interface_observer.cpp - BlackBoard interface observer
4  *
5  * Created: Fri Jan 25 18:26:12 2008
6  * Copyright 2007-2008 Tim Niemueller [www.niemueller.de]
7  *
8  ****************************************************************************/
9 
10 /* This program is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation; either version 2 of the License, or
13  * (at your option) any later version. A runtime exception applies to
14  * this software (see LICENSE.GPL_WRE file mentioned below for details).
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Library General Public License for more details.
20  *
21  * Read the full text in the LICENSE.GPL_WRE file in the doc directory.
22  */
23 
24 #include <blackboard/interface_observer.h>
25 #include <interface/interface.h>
26 #include <cstdlib>
27 #include <cstring>
28 
29 namespace fawkes {
30 
31 /** @class BlackBoardInterfaceObserver <blackboard/interface_observer.h>
32  * BlackBoard interface observer.
33  * Derive this class if you want to be notified of specific BlackBoard
34  * events that are not tied to particular instances of interfaces like
35  * create and destroy operations.
36  *
37  * The bb_interface_* methods are called during the appropriate operation. The
38  * operation that you carry out in this event handler really has to be damn fast,
39  * or the performance of the whole system will suffer severely. For this reason use
40  * this notification facility only rarely and only register for the appropriate
41  * events.
42  *
43  * This class provides the basic infrastructure that can be used to build
44  * your own observer. During the life time of your observer you
45  * first add all the interfaces to the appropriate structures that you want
46  * to listen for and add the interface types where you want to be notified
47  * of creation events.
48  *
49  * The interface created event is raised whenever an interface of a type that
50  * you registered for is created. The destroyed event is raised if the an interface
51  * is irrecoverable deleted from the BlackBoard. This happens when the last
52  * reader or writer closes the interface. That means neither a writer nor any
53  * reader has a particular interface still opened.
54  *
55  * Here is a simple life cycle of a BlackBoard interface observer:
56  * First you add all the interface types that you want to observe with calls to
57  * bbio_add_interface_create_type() and bbio_add_interface_destroy_type(). Then
58  * you register the observer with InterfaceManager::register_observer(). From then
59  * on you are notified of the events. Afterwards you unregister your observer
60  * to no longer receive events.
61  *
62  * @author Tim Niemueller
63  * @see BlackBoardInterfaceManager::register_observer()
64  * @see BlackBoardInterfaceManager::unregister_observer()
65  */
66 
67 /** Empty constructor. */
69 {
70 }
71 
72 /** Destructor. */
74 {
75  __bbio_observed_create.clear();
76  __bbio_observed_destroy.clear();
77 }
78 
79 
80 /** BlackBoard interface created notification.
81  * This is called whenever an interface is created for a type that you registered
82  * for.
83  * @param type type of the interface. If you want to store this make a copy as it
84  * is not guaranteed that the supplied string exists for longer than the duration
85  * of the method call
86  * @param id ID of the newly created interface. If you want to store this make a
87  * copy as it is not guaranteed that the supplied string exists for longer than
88  * the duration of the method call
89  */
90 void
91 BlackBoardInterfaceObserver::bb_interface_created(const char *type, const char *id) throw()
92 {
93 }
94 
95 
96 /** BlackBoard interface destroyed notification.
97  * This is called whenever an interface is destroyed for a type that you registered
98  * for.
99  * @param type type of the interface. If you want to store this make a copy as it
100  * is not guaranteed that the supplied string exists for longer than the duration
101  * of the method call
102  * @param id ID of the newly created interface. If you want to store this make a
103  * copy as it is not guaranteed that the supplied string exists for longer than
104  * the duration of the method call
105  */
106 void
107 BlackBoardInterfaceObserver::bb_interface_destroyed(const char *type, const char *id) throw()
108 {
109 }
110 
111 
112 /** Add interface creation type to watch list.
113  * With this you add an interface type to the watch list. For any type on this list
114  * you will be notified if an interface is created.
115  * @param type_pattern pattern of interface types to watch, supports wildcards
116  * similar to filenames (*, ?, []), see "man fnmatch" for all supported.
117  * @param id_pattern pattern of interface IDs to open, supports wildcards similar
118  * to filenames (*, ?, []), see "man fnmatch" for all supported.
119  */
120 void
122  const char *id_pattern) throw()
123 {
124  __bbio_observed_create.lock();
125  __bbio_observed_create[type_pattern].push_back(id_pattern);
126  __bbio_observed_create[type_pattern].sort();
127  __bbio_observed_create[type_pattern].unique();
128  __bbio_observed_create.unlock();
129 }
130 
131 
132 /** Add interface destruction type to watch list.
133  * With this you add an interface type to the watch list. For any type on this
134  * list you will be notified if an interface is destroyed.
135  * @param type_pattern pattern of interface types to watch, supports wildcards
136  * similar to filenames (*, ?, []), see "man fnmatch" for all supported.
137  * @param id_pattern pattern of interface IDs to open, supports wildcards similar
138  * to filenames (*, ?, []), see "man fnmatch" for all supported.
139  */
140 void
142  const char *id_pattern) throw()
143 {
144  __bbio_observed_destroy.lock();
145  __bbio_observed_destroy[type_pattern].push_back(id_pattern);
146  __bbio_observed_destroy[type_pattern].sort();
147  __bbio_observed_destroy[type_pattern].unique();
148  __bbio_observed_destroy.unlock();
149 }
150 
151 
152 /** Get interface creation type watch list.
153  * @return interface type watch list
154  */
157 {
158  return &__bbio_observed_create;
159 }
160 
161 
162 /** Get interface destriction type watch list.
163  * @return interface type watch list
164  */
167 {
168  return &__bbio_observed_destroy;
169 }
170 
171 
172 } // end namespace fawkes
ObservedInterfaceLockMap * bbio_get_observed_destroy()
Get interface destriction type watch list.
void lock() const
Lock list.
Definition: lock_map.h:100
virtual void bb_interface_destroyed(const char *type, const char *id)
BlackBoard interface destroyed notification.
Fawkes library namespace.
BlackBoardInterfaceObserver()
Empty constructor.
void bbio_add_observed_destroy(const char *type_pattern, const char *id_pattern="*")
Add interface destruction type to watch list.
void bbio_add_observed_create(const char *type_pattern, const char *id_pattern="*")
Add interface creation type to watch list.
void unlock() const
Unlock list.
Definition: lock_map.h:120
virtual ~BlackBoardInterfaceObserver()
Destructor.
ObservedInterfaceLockMap * bbio_get_observed_create()
Get interface creation type watch list.
virtual void bb_interface_created(const char *type, const char *id)
BlackBoard interface created notification.