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 
33 namespace fawkes {
34 #if 0 /* just to make Emacs auto-indent happy */
35 }
36 #endif
37 
38 class BlackBoardInterfaceManager;
39 class BlackBoardMemoryManager;
40 class BlackBoardMessageManager;
41 class BlackBoardNetworkHandler;
42 class BlackBoardNotifier;
43 class InterfaceInfoList;
44 class BlackBoardInterfaceListener;
45 class BlackBoardInterfaceObserver;
46 class FawkesNetworkHub;
47 
49 {
50  public:
51  virtual ~BlackBoard();
52 
53  virtual Interface * open_for_reading(const char *interface_type,
54  const char *identifier,
55  const char *owner = NULL) = 0;
56  virtual Interface * open_for_writing(const char *interface_type,
57  const char *identifier,
58  const char *owner = NULL) = 0;
59  virtual void close(Interface *interface) = 0;
60 
61  virtual Interface * open_for_reading_f(const char *interface_type,
62  const char *identifier, ...);
63  virtual Interface * open_for_writing_f(const char *interface_type,
64  const char *identifier, ...);
65 
66 
67  virtual InterfaceInfoList * list_all() = 0;
68  virtual InterfaceInfoList * list(const char *type_pattern,
69  const char *id_pattern) = 0;
70  virtual bool is_alive() const throw() = 0;
71  virtual bool try_aliveness_restore() throw() = 0;
72 
73  virtual std::list<Interface *>
74  open_multiple_for_reading(const char *type_pattern,
75  const char *id_pattern = "*",
76  const char *owner = NULL) = 0;
77 
78  template <class InterfaceType>
79  std::list<InterfaceType *>
80  open_multiple_for_reading(const char *id_pattern = "*",
81  const char *owner = NULL);
82 
83  template <class InterfaceType>
84  InterfaceType * open_for_reading(const char *identifier,
85  const char *owner = NULL);
86 
87  template <class InterfaceType>
88  InterfaceType * open_for_writing(const char *identifier,
89  const char *owner = NULL);
90 
91  template <class InterfaceType>
92  InterfaceType * open_for_reading_f(const char *identifier, ...);
93 
94  template <class InterfaceType>
95  InterfaceType * open_for_writing_f(const char *identifier, ...);
96 
97  /** Flags to constrain listener registration/updates. */
98  typedef enum {
99  BBIL_FLAG_DATA = 1, ///< consider data events
100  BBIL_FLAG_MESSAGES = 2, ///< consider message received events
101  BBIL_FLAG_READER = 4, ///< consider reader events
102  BBIL_FLAG_WRITER = 8, ///< consider writer events
103  BBIL_FLAG_ALL = 15, ///< consider all events
105 
106  virtual void register_listener(BlackBoardInterfaceListener *listener,
108  virtual void update_listener(BlackBoardInterfaceListener *listener,
110  virtual void unregister_listener(BlackBoardInterfaceListener *listener);
111 
112  virtual void register_observer(BlackBoardInterfaceObserver *observer);
113  virtual void unregister_observer(BlackBoardInterfaceObserver *observer);
114 
115  std::string demangle_fawkes_interface_name(const char *type);
116  std::string format_identifier(const char *identifier_format, va_list arg);
117 
118  protected:
119  BlackBoard(bool create_notifier = true);
120 
121  protected:
122  BlackBoardNotifier *__notifier; ///< Notifier for BB events.
123 };
124 
125 
126 /** Get interface of given type.
127  * This will open a new interface for reading just like the
128  * non-template version of open_for_reading(). But with the template
129  * method you will get a correctly typed object that you can use. An
130  * TypeMismatchException is thrown if the string representation of the
131  * type and the actual class type of the interface do not match.
132  * @param identifier identifier of the interface
133  * @param owner name of entity which opened this interface. If using the BlackBoardAspect
134  * to access the blackboard leave this untouched unless you have a good reason.
135  * @return new fully initialized interface instance of requested type
136  * @exception OutOfMemoryException thrown if there is not enough free space for
137  * the requested interface.
138  * @exception TypeMismatchException thrown if type in interface_type
139  * and the actual class type do not fit.
140  */
141 template <class InterfaceType>
142 InterfaceType *
143 BlackBoard::open_for_reading(const char *identifier, const char *owner)
144 {
145  std::string type_name =
146  demangle_fawkes_interface_name(typeid(InterfaceType).name());
147  Interface *interface = open_for_reading(type_name.c_str(), identifier, owner);
148  return static_cast<InterfaceType *>(interface);
149 }
150 
151 
152 /** Get interface of given type with identifier format string.
153  * This will open a new interface for reading just like the
154  * non-template version of open_for_reading(). But with the template
155  * method you will get a correctly typed object that you can use. An
156  * TypeMismatchException is thrown if the string representation of the
157  * type and the actual class type of the interface do not match.
158  * @param identifier identifier of the interface
159  * @return new fully initialized interface instance of requested type
160  * @exception OutOfMemoryException thrown if there is not enough free space for
161  * the requested interface.
162  * @exception TypeMismatchException thrown if type in interface_type
163  * and the actual class type do not fit.
164  */
165 template <class InterfaceType>
166 InterfaceType *
167 BlackBoard::open_for_reading_f(const char *identifier, ...)
168 {
169  va_list arg;
170  va_start(arg, identifier);
171  std::string type_name =
172  demangle_fawkes_interface_name(typeid(InterfaceType).name());
173  std::string identifier_s = format_identifier(identifier, arg);
174  va_end(arg);
175  Interface *interface = open_for_reading(type_name.c_str(), identifier_s.c_str());
176  return static_cast<InterfaceType *>(interface);
177 }
178 
179 
180 /** Open all interfaces of given type for reading.
181  * This will create interface instances for all currently registered interfaces of
182  * the given type. The result can be casted to the appropriate type.
183  * @param id_pattern pattern of interface IDs to open, supports wildcards similar
184  * to filenames (*, ?, []), see "man fnmatch" for all supported.
185  * @param owner name of entity which opened this interface. If using the BlackBoardAspect
186  * to access the blackboard leave this untouched unless you have a good reason.
187  * @return list of new fully initialized interface instances of requested type. The
188  * is allocated using new and you have to free it using delete after you are done
189  * with it!
190  */
191 template <class InterfaceType>
192 std::list<InterfaceType *>
193 BlackBoard::open_multiple_for_reading(const char *id_pattern, const char *owner)
194 {
195  std::string type_name =
196  demangle_fawkes_interface_name(typeid(InterfaceType).name());
197  std::list<Interface *> il =
198  open_multiple_for_reading(type_name.c_str(), id_pattern, owner);
199  std::list<InterfaceType *> rv;
200  for (std::list<Interface *>::iterator i = il.begin(); i != il.end(); ++i) {
201  rv.push_back(static_cast<InterfaceType *>(*i));
202  }
203 
204  return rv;
205 }
206 
207 
208 /** Get writer interface of given type.
209  * This will open a new interface for writing just like the
210  * non-template version of open_for_writing(). But with the template
211  * method you will get a correctly typed object that you can use. An
212  * TypeMismatchException is thrown if the string representation of the
213  * type and the actual class type of the interface do not match.
214  * @param identifier identifier of the interface
215  * @param owner name of entity which opened this interface. If using the BlackBoardAspect
216  * to access the blackboard leave this untouched unless you have a good reason.
217  * @return new fully initialized interface instance of requested type
218  * @exception OutOfMemoryException thrown if there is not enough free space for
219  * the requested interface.
220  * @exception BlackBoardWriterActiveException thrown if there is already a writing
221  * instance with the same type/id
222  * @exception TypeMismatchException thrown if type in interface_type
223  * and the actual class type do not fit.
224  */
225 template <class InterfaceType>
226 InterfaceType *
227 BlackBoard::open_for_writing(const char *identifier, const char *owner)
228 {
229  std::string type_name =
230  demangle_fawkes_interface_name(typeid(InterfaceType).name());
231  Interface *interface = open_for_writing(type_name.c_str(), identifier, owner);
232  return static_cast<InterfaceType *>(interface);;
233 }
234 
235 
236 /** Get writer interface of given type with identifier format string.
237  * This will open a new interface for writing just like the
238  * non-template version of open_for_writing(). But with the template
239  * method you will get a correctly typed object that you can use. An
240  * TypeMismatchException is thrown if the string representation of the
241  * type and the actual class type of the interface do not match.
242  * @param identifier identifier of the interface
243  * @return new fully initialized interface instance of requested type
244  * @exception OutOfMemoryException thrown if there is not enough free space for
245  * the requested interface.
246  * @exception BlackBoardWriterActiveException thrown if there is already a writing
247  * instance with the same type/id
248  * @exception TypeMismatchException thrown if type in interface_type
249  * and the actual class type do not fit.
250  */
251 template <class InterfaceType>
252 InterfaceType *
253 BlackBoard::open_for_writing_f(const char *identifier, ...)
254 {
255  va_list arg;
256  va_start(arg, identifier);
257  std::string type_name =
258  demangle_fawkes_interface_name(typeid(InterfaceType).name());
259  std::string identifier_s = format_identifier(identifier, arg);
260  va_end(arg);
261  Interface *interface = open_for_writing(type_name.c_str(), identifier_s.c_str());
262  return static_cast<InterfaceType *>(interface);;
263 }
264 
265 
266 /** Concatenation of register flags.
267  * @param a flags to concatenate
268  * @param b other flags to concatenate
269  * @return concatenated flags
270  */
274 {
275  return (BlackBoard::ListenerRegisterFlag)((int)a | (int)b);
276 }
277 
278 
279 /** Testing of register flags.
280  * @param a flags to test
281  * @param b flags to test for
282  * @return resulting flags
283  */
287 {
288  return (BlackBoard::ListenerRegisterFlag)((int)a & (int)b);
289 }
290 
291 
292 } // end namespace fawkes
293 
294 #endif
virtual void register_observer(BlackBoardInterfaceObserver *observer)
Register BB interface observer.
Definition: blackboard.cpp:230
ListenerRegisterFlag
Flags to constrain listener registration/updates.
Definition: blackboard.h:98
consider data events
Definition: blackboard.h:99
std::string format_identifier(const char *identifier_format, va_list arg)
Get formatted identifier string.
Definition: blackboard.cpp:276
consider reader events
Definition: blackboard.h:101
BlackBoard::ListenerRegisterFlag operator|(const BlackBoard::ListenerRegisterFlag &a, const BlackBoard::ListenerRegisterFlag &b)
Concatenation of register flags.
Definition: blackboard.h:272
Fawkes library namespace.
virtual Interface * open_for_reading_f(const char *interface_type, const char *identifier,...)
Open interface for reading with identifier format string.
Definition: blackboard.cpp:299
virtual bool try_aliveness_restore()=0
Try to restore the aliveness of the BlackBoard instance.
BlackBoard notifier.
Definition: notifier.h:43
virtual void unregister_listener(BlackBoardInterfaceListener *listener)
Unregister BB interface listener.
Definition: blackboard.cpp:218
virtual void update_listener(BlackBoardInterfaceListener *listener, ListenerRegisterFlag flag=BBIL_FLAG_ALL)
Update BB event listener.
Definition: blackboard.cpp:203
Base class for all Fawkes BlackBoard interfaces.
Definition: interface.h:79
virtual InterfaceInfoList * list(const char *type_pattern, const char *id_pattern)=0
Get list of interfaces matching type and ID patterns.
consider message received events
Definition: blackboard.h:100
virtual void register_listener(BlackBoardInterfaceListener *listener, ListenerRegisterFlag flag=BBIL_FLAG_ALL)
Register BB event listener.
Definition: blackboard.cpp:190
Interface information list.
virtual bool is_alive() const =0
Check if the BlackBoard is still alive.
virtual void unregister_observer(BlackBoardInterfaceObserver *observer)
Unregister BB interface observer.
Definition: blackboard.cpp:244
virtual Interface * open_for_writing_f(const char *interface_type, const char *identifier,...)
Open interface for writing with identifier format string.
Definition: blackboard.cpp:326
BlackBoardNotifier * __notifier
Notifier for BB events.
Definition: blackboard.h:122
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.
BlackBoard interface observer.
BlackBoard(bool create_notifier=true)
Constructor.
Definition: blackboard.cpp:169
virtual ~BlackBoard()
Destructor.
Definition: blackboard.cpp:179
consider writer events
Definition: blackboard.h:102
virtual InterfaceInfoList * list_all()=0
Get list of all currently existing interfaces.
virtual Interface * open_for_reading(const char *interface_type, const char *identifier, const char *owner=NULL)=0
Open interface for reading.
The BlackBoard abstract class.
Definition: blackboard.h:48
BlackBoard::ListenerRegisterFlag operator &(const BlackBoard::ListenerRegisterFlag &a, const BlackBoard::ListenerRegisterFlag &b)
Testing of register flags.
Definition: blackboard.h:285
virtual Interface * open_for_writing(const char *interface_type, const char *identifier, const char *owner=NULL)=0
Open interface for writing.
BlackBoard interface listener.
std::string demangle_fawkes_interface_name(const char *type)
Produce interface name from C++ signature.
Definition: blackboard.cpp:260
virtual void close(Interface *interface)=0
Close interface.