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 
30 namespace 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  */
90 void
91 BlackBoardInterfaceObserver::bb_interface_created(const char *type, const char *id) throw()
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  */
105 void
106 BlackBoardInterfaceObserver::bb_interface_destroyed(const char *type, const char *id) throw()
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  */
118 void
120  const char *id_pattern) throw()
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  */
137 void
139  const char *id_pattern) throw()
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
fawkes::BlackBoardInterfaceObserver::bbio_add_observed_destroy
void bbio_add_observed_destroy(const char *type_pattern, const char *id_pattern="*")
Add interface destruction type to watch list.
Definition: interface_observer.cpp:138
fawkes::BlackBoardInterfaceObserver::bb_interface_destroyed
virtual void bb_interface_destroyed(const char *type, const char *id)
BlackBoard interface destroyed notification.
Definition: interface_observer.cpp:106
fawkes::LockMap< std::string, std::list< std::string > >
fawkes::BlackBoardInterfaceObserver::BlackBoardInterfaceObserver
BlackBoardInterfaceObserver()
Empty constructor.
Definition: interface_observer.cpp:69
fawkes::BlackBoardInterfaceObserver::bbio_get_observed_destroy
ObservedInterfaceLockMap * bbio_get_observed_destroy()
Get interface destriction type watch list.
Definition: interface_observer.cpp:161
fawkes::BlackBoardInterfaceObserver::bbio_add_observed_create
void bbio_add_observed_create(const char *type_pattern, const char *id_pattern="*")
Add interface creation type to watch list.
Definition: interface_observer.cpp:119
fawkes
Fawkes library namespace.
fawkes::BlackBoardInterfaceObserver::~BlackBoardInterfaceObserver
virtual ~BlackBoardInterfaceObserver()
Destructor.
Definition: interface_observer.cpp:74
fawkes::BlackBoardInterfaceObserver::bbio_get_observed_create
ObservedInterfaceLockMap * bbio_get_observed_create()
Get interface creation type watch list.
Definition: interface_observer.cpp:152
fawkes::BlackBoardInterfaceObserver::bb_interface_created
virtual void bb_interface_created(const char *type, const char *id)
BlackBoard interface created notification.
Definition: interface_observer.cpp:91