Fawkes API Fawkes Development Version
blackboard.h
1
2/***************************************************************************
3 * blackboard.h - BlackBoard Interface
4 *
5 * Created: Sat Sep 16 17:09:15 2006 (on train to Cologne)
6 * Copyright 2006-2015 Tim Niemueller [www.niemueller.de]
7 ****************************************************************************/
8
9/* This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version. A runtime exception applies to
13 * this software (see LICENSE.GPL_WRE file mentioned below for details).
14 *
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU Library General Public License for more details.
19 *
20 * Read the full text in the LICENSE.GPL_WRE file in the doc directory.
21 */
22
23#ifndef _BLACKBOARD_BLACKBOARD_H_
24#define _BLACKBOARD_BLACKBOARD_H_
25
26#include <core/exceptions/software.h>
27#include <interface/interface.h>
28
29#include <list>
30#include <string>
31#include <typeinfo>
32
33namespace fawkes {
34
35class BlackBoardInterfaceManager;
36class BlackBoardMemoryManager;
37class BlackBoardMessageManager;
38class BlackBoardNetworkHandler;
39class BlackBoardNotifier;
40class InterfaceInfoList;
41class BlackBoardInterfaceListener;
42class BlackBoardInterfaceObserver;
43class FawkesNetworkHub;
44
46{
47public:
48 virtual ~BlackBoard();
49
50 virtual Interface *open_for_reading(const char *interface_type,
51 const char *identifier,
52 const char *owner = NULL) = 0;
53 virtual Interface *open_for_writing(const char *interface_type,
54 const char *identifier,
55 const char *owner = NULL) = 0;
56 virtual void close(Interface *interface) = 0;
57
58 virtual Interface *open_for_reading_f(const char *interface_type, const char *identifier, ...);
59 virtual Interface *open_for_writing_f(const char *interface_type, const char *identifier, ...);
60
62 virtual InterfaceInfoList *list(const char *type_pattern, const char *id_pattern) = 0;
63 virtual bool is_alive() const noexcept = 0;
64 virtual bool try_aliveness_restore() noexcept = 0;
65
66 virtual std::list<Interface *> open_multiple_for_reading(const char *type_pattern,
67 const char *id_pattern = "*",
68 const char *owner = NULL) = 0;
69
70 template <class InterfaceType>
71 std::list<InterfaceType *> open_multiple_for_reading(const char *id_pattern = "*",
72 const char *owner = NULL);
73
74 template <class InterfaceType>
75 InterfaceType *open_for_reading(const char *identifier, const char *owner = NULL);
76
77 template <class InterfaceType>
78 InterfaceType *open_for_writing(const char *identifier, const char *owner = NULL);
79
80 template <class InterfaceType>
81 InterfaceType *open_for_reading_f(const char *identifier, ...);
82
83 template <class InterfaceType>
84 InterfaceType *open_for_writing_f(const char *identifier, ...);
85
86 /** Flags to constrain listener registration/updates. */
87 typedef enum {
88 BBIL_FLAG_DATA = 1, ///< consider data events
89 BBIL_FLAG_MESSAGES = 2, ///< consider message received events
90 BBIL_FLAG_READER = 4, ///< consider reader events
91 BBIL_FLAG_WRITER = 8, ///< consider writer events
92 BBIL_FLAG_ALL = 15, ///< consider all events
94
97 virtual void update_listener(BlackBoardInterfaceListener *listener,
100
101 virtual void register_observer(BlackBoardInterfaceObserver *observer);
102 virtual void unregister_observer(BlackBoardInterfaceObserver *observer);
103
104 std::string demangle_fawkes_interface_name(const char *type);
105 std::string format_identifier(const char *identifier_format, va_list arg);
106
107protected:
108 BlackBoard(bool create_notifier = true);
109
110protected:
111 BlackBoardNotifier *notifier_; ///< Notifier for BB events.
112};
113
114/** Get interface of given type.
115 * This will open a new interface for reading just like the
116 * non-template version of open_for_reading(). But with the template
117 * method you will get a correctly typed object that you can use. An
118 * TypeMismatchException is thrown if the string representation of the
119 * type and the actual class type of the interface do not match.
120 * @param identifier identifier of the interface
121 * @param owner name of entity which opened this interface. If using the BlackBoardAspect
122 * to access the blackboard leave this untouched unless you have a good reason.
123 * @return new fully initialized interface instance of requested type
124 * @exception OutOfMemoryException thrown if there is not enough free space for
125 * the requested interface.
126 * @exception TypeMismatchException thrown if type in interface_type
127 * and the actual class type do not fit.
128 */
129template <class InterfaceType>
130InterfaceType *
131BlackBoard::open_for_reading(const char *identifier, const char *owner)
132{
133 std::string type_name = demangle_fawkes_interface_name(typeid(InterfaceType).name());
134 Interface * interface = open_for_reading(type_name.c_str(), identifier, owner);
135 return static_cast<InterfaceType *>(interface);
136}
137
138/** Get interface of given type with identifier format string.
139 * This will open a new interface for reading just like the
140 * non-template version of open_for_reading(). But with the template
141 * method you will get a correctly typed object that you can use. An
142 * TypeMismatchException is thrown if the string representation of the
143 * type and the actual class type of the interface do not match.
144 * @param identifier identifier of the interface
145 * @return new fully initialized interface instance of requested type
146 * @exception OutOfMemoryException thrown if there is not enough free space for
147 * the requested interface.
148 * @exception TypeMismatchException thrown if type in interface_type
149 * and the actual class type do not fit.
150 */
151template <class InterfaceType>
152InterfaceType *
153BlackBoard::open_for_reading_f(const char *identifier, ...)
154{
155 va_list arg;
156 va_start(arg, identifier);
157 std::string type_name = demangle_fawkes_interface_name(typeid(InterfaceType).name());
158 std::string identifier_s = format_identifier(identifier, arg);
159 va_end(arg);
160 Interface *interface = open_for_reading(type_name.c_str(), identifier_s.c_str());
161 return static_cast<InterfaceType *>(interface);
162}
163
164/** Open all interfaces of given type for reading.
165 * This will create interface instances for all currently registered interfaces of
166 * the given type. The result can be casted to the appropriate type.
167 * @param id_pattern pattern of interface IDs to open, supports wildcards similar
168 * to filenames (*, ?, []), see "man fnmatch" for all supported.
169 * @param owner name of entity which opened this interface. If using the BlackBoardAspect
170 * to access the blackboard leave this untouched unless you have a good reason.
171 * @return list of new fully initialized interface instances of requested type. The
172 * is allocated using new and you have to free it using delete after you are done
173 * with it!
174 */
175template <class InterfaceType>
176std::list<InterfaceType *>
177BlackBoard::open_multiple_for_reading(const char *id_pattern, const char *owner)
178{
179 std::string type_name = demangle_fawkes_interface_name(typeid(InterfaceType).name());
180 std::list<Interface *> il = open_multiple_for_reading(type_name.c_str(), id_pattern, owner);
181 std::list<InterfaceType *> rv;
182 for (std::list<Interface *>::iterator i = il.begin(); i != il.end(); ++i) {
183 rv.push_back(static_cast<InterfaceType *>(*i));
184 }
185
186 return rv;
187}
188
189/** Get writer interface of given type.
190 * This will open a new interface for writing just like the
191 * non-template version of open_for_writing(). But with the template
192 * method you will get a correctly typed object that you can use. An
193 * TypeMismatchException is thrown if the string representation of the
194 * type and the actual class type of the interface do not match.
195 * @param identifier identifier of the interface
196 * @param owner name of entity which opened this interface. If using the BlackBoardAspect
197 * to access the blackboard leave this untouched unless you have a good reason.
198 * @return new fully initialized interface instance of requested type
199 * @exception OutOfMemoryException thrown if there is not enough free space for
200 * the requested interface.
201 * @exception BlackBoardWriterActiveException thrown if there is already a writing
202 * instance with the same type/id
203 * @exception TypeMismatchException thrown if type in interface_type
204 * and the actual class type do not fit.
205 */
206template <class InterfaceType>
207InterfaceType *
208BlackBoard::open_for_writing(const char *identifier, const char *owner)
209{
210 std::string type_name = demangle_fawkes_interface_name(typeid(InterfaceType).name());
211 Interface * interface = open_for_writing(type_name.c_str(), identifier, owner);
212 return static_cast<InterfaceType *>(interface);
213 ;
214}
215
216/** Get writer interface of given type with identifier format string.
217 * This will open a new interface for writing just like the
218 * non-template version of open_for_writing(). But with the template
219 * method you will get a correctly typed object that you can use. An
220 * TypeMismatchException is thrown if the string representation of the
221 * type and the actual class type of the interface do not match.
222 * @param identifier identifier of the interface
223 * @return new fully initialized interface instance of requested type
224 * @exception OutOfMemoryException thrown if there is not enough free space for
225 * the requested interface.
226 * @exception BlackBoardWriterActiveException thrown if there is already a writing
227 * instance with the same type/id
228 * @exception TypeMismatchException thrown if type in interface_type
229 * and the actual class type do not fit.
230 */
231template <class InterfaceType>
232InterfaceType *
233BlackBoard::open_for_writing_f(const char *identifier, ...)
234{
235 va_list arg;
236 va_start(arg, identifier);
237 std::string type_name = demangle_fawkes_interface_name(typeid(InterfaceType).name());
238 std::string identifier_s = format_identifier(identifier, arg);
239 va_end(arg);
240 Interface *interface = open_for_writing(type_name.c_str(), identifier_s.c_str());
241 return static_cast<InterfaceType *>(interface);
242 ;
243}
244
245/** Concatenation of register flags.
246 * @param a flags to concatenate
247 * @param b other flags to concatenate
248 * @return concatenated flags
249 */
252{
253 return (BlackBoard::ListenerRegisterFlag)((int)a | (int)b);
254}
255
256/** Testing of register flags.
257 * @param a flags to test
258 * @param b flags to test for
259 * @return resulting flags
260 */
263{
264 return (BlackBoard::ListenerRegisterFlag)((int)a & (int)b);
265}
266
267} // end namespace fawkes
268
269#endif
BlackBoard interface listener.
BlackBoard interface observer.
BlackBoard notifier.
Definition: notifier.h:44
The BlackBoard abstract class.
Definition: blackboard.h:46
BlackBoardNotifier * notifier_
Notifier for BB events.
Definition: blackboard.h:111
virtual bool is_alive() const noexcept=0
Check if the BlackBoard is still alive.
virtual void unregister_observer(BlackBoardInterfaceObserver *observer)
Unregister BB interface observer.
Definition: blackboard.cpp:240
std::string format_identifier(const char *identifier_format, va_list arg)
Get formatted identifier string.
Definition: blackboard.cpp:272
virtual Interface * open_for_reading(const char *interface_type, const char *identifier, const char *owner=NULL)=0
Open interface for reading.
virtual void update_listener(BlackBoardInterfaceListener *listener, ListenerRegisterFlag flag=BBIL_FLAG_ALL)
Update BB event listener.
Definition: blackboard.cpp:197
virtual InterfaceInfoList * list_all()=0
Get list of all currently existing interfaces.
virtual InterfaceInfoList * list(const char *type_pattern, const char *id_pattern)=0
Get list of interfaces matching type and ID patterns.
virtual Interface * open_for_reading_f(const char *interface_type, const char *identifier,...)
Open interface for reading with identifier format string.
Definition: blackboard.cpp:295
ListenerRegisterFlag
Flags to constrain listener registration/updates.
Definition: blackboard.h:87
@ BBIL_FLAG_READER
consider reader events
Definition: blackboard.h:90
@ BBIL_FLAG_DATA
consider data events
Definition: blackboard.h:88
@ BBIL_FLAG_WRITER
consider writer events
Definition: blackboard.h:91
@ BBIL_FLAG_ALL
consider all events
Definition: blackboard.h:92
@ BBIL_FLAG_MESSAGES
consider message received events
Definition: blackboard.h:89
virtual bool try_aliveness_restore() noexcept=0
Try to restore the aliveness of the BlackBoard instance.
virtual void register_observer(BlackBoardInterfaceObserver *observer)
Register BB interface observer.
Definition: blackboard.cpp:225
std::string demangle_fawkes_interface_name(const char *type)
Produce interface name from C++ signature.
Definition: blackboard.cpp:257
virtual void unregister_listener(BlackBoardInterfaceListener *listener)
Unregister BB interface listener.
Definition: blackboard.cpp:212
virtual Interface * open_for_writing(const char *interface_type, const char *identifier, const char *owner=NULL)=0
Open interface for writing.
BlackBoard(bool create_notifier=true)
Constructor.
Definition: blackboard.cpp:165
virtual Interface * open_for_writing_f(const char *interface_type, const char *identifier,...)
Open interface for writing with identifier format string.
Definition: blackboard.cpp:319
virtual ~BlackBoard()
Destructor.
Definition: blackboard.cpp:175
virtual std::list< Interface * > open_multiple_for_reading(const char *type_pattern, const char *id_pattern="*", const char *owner=NULL)=0
Open multiple interfaces for reading.
virtual void register_listener(BlackBoardInterfaceListener *listener, ListenerRegisterFlag flag=BBIL_FLAG_ALL)
Register BB event listener.
Definition: blackboard.cpp:185
virtual void close(Interface *interface)=0
Close interface.
Interface information list.
Base class for all Fawkes BlackBoard interfaces.
Definition: interface.h:80
Fawkes library namespace.
BlackBoard::ListenerRegisterFlag operator|(const BlackBoard::ListenerRegisterFlag &a, const BlackBoard::ListenerRegisterFlag &b)
Concatenation of register flags.
Definition: blackboard.h:251
BlackBoard::ListenerRegisterFlag operator&(const BlackBoard::ListenerRegisterFlag &a, const BlackBoard::ListenerRegisterFlag &b)
Testing of register flags.
Definition: blackboard.h:262