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
27#include <cstdlib>
28#include <cstring>
29
30namespace fawkes {
31
32/** @class BlackBoardInterfaceObserver <blackboard/interface_observer.h>
33 * BlackBoard interface observer.
34 * Derive this class if you want to be notified of specific BlackBoard
35 * events that are not tied to particular instances of interfaces like
36 * create and destroy operations.
37 *
38 * The bb_interface_* methods are called during the appropriate operation. The
39 * operation that you carry out in this event handler really has to be damn fast,
40 * or the performance of the whole system will suffer severely. For this reason use
41 * this notification facility only rarely and only register for the appropriate
42 * events.
43 *
44 * This class provides the basic infrastructure that can be used to build
45 * your own observer. During the life time of your observer you
46 * first add all the interfaces to the appropriate structures that you want
47 * to listen for and add the interface types where you want to be notified
48 * of creation events.
49 *
50 * The interface created event is raised whenever an interface of a type that
51 * you registered for is created. The destroyed event is raised if the an interface
52 * is irrecoverable deleted from the BlackBoard. This happens when the last
53 * reader or writer closes the interface. That means neither a writer nor any
54 * reader has a particular interface still opened.
55 *
56 * Here is a simple life cycle of a BlackBoard interface observer:
57 * First you add all the interface types that you want to observe with calls to
58 * bbio_add_interface_create_type() and bbio_add_interface_destroy_type(). Then
59 * you register the observer with InterfaceManager::register_observer(). From then
60 * on you are notified of the events. Afterwards you unregister your observer
61 * to no longer receive events.
62 *
63 * @author Tim Niemueller
64 * @see BlackBoardInterfaceManager::register_observer()
65 * @see BlackBoardInterfaceManager::unregister_observer()
66 */
67
68/** Empty constructor. */
70{
71}
72
73/** Destructor. */
75{
76 bbio_observed_create_.clear();
77 bbio_observed_destroy_.clear();
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 */
90void
91BlackBoardInterfaceObserver::bb_interface_created(const char *type, const char *id) noexcept
92{
93}
94
95/** BlackBoard interface destroyed notification.
96 * This is called whenever an interface is destroyed for a type that you registered
97 * for.
98 * @param type type of the interface. If you want to store this make a copy as it
99 * is not guaranteed that the supplied string exists for longer than the duration
100 * of the method call
101 * @param id ID of the newly created interface. If you want to store this make a
102 * copy as it is not guaranteed that the supplied string exists for longer than
103 * the duration of the method call
104 */
105void
106BlackBoardInterfaceObserver::bb_interface_destroyed(const char *type, const char *id) noexcept
107{
108}
109
110/** Add interface creation type to watch list.
111 * With this you add an interface type to the watch list. For any type on this list
112 * you will be notified if an interface is created.
113 * @param type_pattern pattern of interface types to watch, supports wildcards
114 * similar to filenames (*, ?, []), see "man fnmatch" for all supported.
115 * @param id_pattern pattern of interface IDs to open, supports wildcards similar
116 * to filenames (*, ?, []), see "man fnmatch" for all supported.
117 */
118void
120 const char *id_pattern) noexcept
121{
122 bbio_observed_create_.lock();
123 bbio_observed_create_[type_pattern].push_back(id_pattern);
124 bbio_observed_create_[type_pattern].sort();
125 bbio_observed_create_[type_pattern].unique();
126 bbio_observed_create_.unlock();
127}
128
129/** Add interface destruction type to watch list.
130 * With this you add an interface type to the watch list. For any type on this
131 * list you will be notified if an interface is destroyed.
132 * @param type_pattern pattern of interface types to watch, supports wildcards
133 * similar to filenames (*, ?, []), see "man fnmatch" for all supported.
134 * @param id_pattern pattern of interface IDs to open, supports wildcards similar
135 * to filenames (*, ?, []), see "man fnmatch" for all supported.
136 */
137void
139 const char *id_pattern) noexcept
140{
141 bbio_observed_destroy_.lock();
142 bbio_observed_destroy_[type_pattern].push_back(id_pattern);
143 bbio_observed_destroy_[type_pattern].sort();
144 bbio_observed_destroy_[type_pattern].unique();
145 bbio_observed_destroy_.unlock();
146}
147
148/** Get interface creation type watch list.
149 * @return interface type watch list
150 */
153{
154 return &bbio_observed_create_;
155}
156
157/** Get interface destriction type watch list.
158 * @return interface type watch list
159 */
162{
163 return &bbio_observed_destroy_;
164}
165
166} // end namespace fawkes
ObservedInterfaceLockMap * bbio_get_observed_destroy() noexcept
Get interface destriction type watch list.
void bbio_add_observed_destroy(const char *type_pattern, const char *id_pattern="*") noexcept
Add interface destruction type to watch list.
ObservedInterfaceLockMap * bbio_get_observed_create() noexcept
Get interface creation type watch list.
virtual void bb_interface_created(const char *type, const char *id) noexcept
BlackBoard interface created notification.
virtual void bb_interface_destroyed(const char *type, const char *id) noexcept
BlackBoard interface destroyed notification.
void bbio_add_observed_create(const char *type_pattern, const char *id_pattern="*") noexcept
Add interface creation type to watch list.
virtual ~BlackBoardInterfaceObserver()
Destructor.
Fawkes library namespace.