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 
35 class BlackBoardInterfaceManager;
36 class BlackBoardMemoryManager;
37 class BlackBoardMessageManager;
38 class BlackBoardNetworkHandler;
39 class BlackBoardNotifier;
40 class InterfaceInfoList;
41 class BlackBoardInterfaceListener;
42 class BlackBoardInterfaceObserver;
43 class FawkesNetworkHub;
44 
46 {
47 public:
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 
61  virtual InterfaceInfoList *list_all() = 0;
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 
95  virtual void register_listener(BlackBoardInterfaceListener *listener,
97  virtual void update_listener(BlackBoardInterfaceListener *listener,
99  virtual void unregister_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 
107 protected:
108  BlackBoard(bool create_notifier = true);
109 
110 protected:
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  */
129 template <class InterfaceType>
130 InterfaceType *
131 BlackBoard::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  */
151 template <class InterfaceType>
152 InterfaceType *
153 BlackBoard::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  */
175 template <class InterfaceType>
176 std::list<InterfaceType *>
177 BlackBoard::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  */
206 template <class InterfaceType>
207 InterfaceType *
208 BlackBoard::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  */
231 template <class InterfaceType>
232 InterfaceType *
233 BlackBoard::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