Fawkes API  Fawkes Development Version
fawkes::BlackBoardInterfaceListener Class Reference

BlackBoard interface listener. More...

#include <>>

Inheritance diagram for fawkes::BlackBoardInterfaceListener:

Classes

struct  InterfaceMaps
 Structure to hold maps for active subscriptions. More...
 
struct  QueueEntry
 Queue entry type. More...
 

Public Types

enum  QueueEntryType { DATA = 0, MESSAGES = 1, READER = 2, WRITER = 3 }
 Queue entry type. More...
 
typedef std::list< QueueEntryInterfaceQueue
 Queue of additions/removal of interfaces. More...
 
typedef std::map< std::string, Interface * > InterfaceMap
 Map of currently active event subscriptions. More...
 

Public Member Functions

 BlackBoardInterfaceListener (const char *name_format,...)
 Constructor. More...
 
virtual ~BlackBoardInterfaceListener ()
 Destructor. More...
 
const char * bbil_name () const
 Get BBIL name. More...
 
virtual void bb_interface_data_changed (Interface *interface) throw ()
 BlackBoard data changed notification. More...
 
virtual bool bb_interface_message_received (Interface *interface, Message *message) throw ()
 BlackBoard message received notification. More...
 
virtual void bb_interface_writer_added (Interface *interface, unsigned int instance_serial) throw ()
 A writing instance has been opened for a watched interface. More...
 
virtual void bb_interface_writer_removed (Interface *interface, unsigned int instance_serial) throw ()
 A writing instance has been closed for a watched interface. More...
 
virtual void bb_interface_reader_added (Interface *interface, unsigned int instance_serial) throw ()
 A reading instance has been opened for a watched interface. More...
 
virtual void bb_interface_reader_removed (Interface *interface, unsigned int instance_serial) throw ()
 A reading instance has been closed for a watched interface. More...
 

Protected Member Functions

void bbil_add_data_interface (Interface *interface)
 Add an interface to the data modification watch list. More...
 
void bbil_add_message_interface (Interface *interface)
 Add an interface to the message received watch list. More...
 
void bbil_add_reader_interface (Interface *interface)
 Add an interface to the reader addition/removal watch list. More...
 
void bbil_add_writer_interface (Interface *interface)
 Add an interface to the writer addition/removal watch list. More...
 
void bbil_remove_data_interface (Interface *interface)
 Remove an interface to the data modification watch list. More...
 
void bbil_remove_message_interface (Interface *interface)
 Remove an interface to the message received watch list. More...
 
void bbil_remove_reader_interface (Interface *interface)
 Remove an interface to the reader addition/removal watch list. More...
 
void bbil_remove_writer_interface (Interface *interface)
 Remove an interface to the writer addition/removal watch list. More...
 
Interfacebbil_data_interface (const char *iuid) throw ()
 Get interface instance for given UID. More...
 
Interfacebbil_message_interface (const char *iuid) throw ()
 Get interface instance for given UID. More...
 
Interfacebbil_reader_interface (const char *iuid) throw ()
 Get interface instance for given UID. More...
 
Interfacebbil_writer_interface (const char *iuid) throw ()
 Get interface instance for given UID. More...
 

Friends

class BlackBoardNotifier
 

Detailed Description

BlackBoard interface listener.

Derive this class if you want to be notified of specific BlackBoard events regarding instances of interfaces.

The bb_interface_* methods are called during the appropriate operation. The operation that you carry out in this event handler really has to damn fast, or the performance of the whole system will suffer severely. For this reason use this notification facility only rarely and only register for the appropriate events.

This class provides the basic infrastructure that can be used to build your own event handler. During the life time of your event handler your first add all the interfaces to the appropriate structures that you want to listen for and add the interface types where you want to be notified of creation events.

The reader/writer added/removed and data changed notifications act upon a specific interface. Any modification done with any instance of the interface is reported to you. The interface creation notification deals only with types of interfaces. There is no interface deletion notification because the general idea is that you opened the interface by yourself for reading and thus the deletion will not happen before you close the interface.

You will not be notified if you change data of the interface that you registered for or remove your own reading/writing instance of an interface.

Here is a simple life cycle of a BlackBoard interface listener: First you create your interface that you want to listen for. The protected methods bbil_add_data_interface(), bbil_add_reader_interface(), bbil_add_writer_interface() and bbil_add_interface_create_type() have to be called with the appropriate interfaces before the event handler is actually registered with the interface manager! From now on will be called for the all registered events. In the end you unregister the event listener and then close any interface that you had registered before.

It is important that you first unregister as an event handler before closing the interface. Otherwise it could happen that you close the interface and the instance is deleted and afterwards an event for that very interface happens. A warning is reported via the LibLogger whenever you forget this.

Author
Tim Niemueller
See also
BlackBoardInterfaceManager::register_listener()
BlackBoardInterfaceManager::unregister_listener()

Definition at line 39 of file interface_listener.h.

Member Typedef Documentation

◆ InterfaceMap

Map of currently active event subscriptions.

Definition at line 63 of file interface_listener.h.

◆ InterfaceQueue

Queue of additions/removal of interfaces.

Definition at line 60 of file interface_listener.h.

Member Enumeration Documentation

◆ QueueEntryType

Queue entry type.

Enumerator
DATA 

Data changed event entry.

MESSAGES 

Message received event entry.

READER 

Reader event entry.

WRITER 

Writer event entry.

Definition at line 45 of file interface_listener.h.

Constructor & Destructor Documentation

◆ BlackBoardInterfaceListener()

fawkes::BlackBoardInterfaceListener::BlackBoardInterfaceListener ( const char *  name_format,
  ... 
)

Constructor.

Parameters
name_formatformat of name to identify the listener, see sprintf for supported tokens

Definition at line 88 of file interface_listener.cpp.

Referenced by NavGraphGeneratorThread::NavGraphGeneratorThread().

◆ ~BlackBoardInterfaceListener()

fawkes::BlackBoardInterfaceListener::~BlackBoardInterfaceListener ( )
virtual

Destructor.

Definition at line 103 of file interface_listener.cpp.

Member Function Documentation

◆ bb_interface_data_changed()

void fawkes::BlackBoardInterfaceListener::bb_interface_data_changed ( Interface interface)
throw (
)
virtual

BlackBoard data changed notification.

This is called whenever the data in an interface that you registered for is modified. This happens if a writer calls the Interface::write() method.

Parameters
interfaceinterface instance that you supplied to bbil_add_data_interface()

Reimplemented in JoystickBlackBoardLogger, RobotStatePublisherThread, fawkes::tf::TransformListener, RosTfThread, BBLoggerThread, RosLaserScanThread, RosPosition3DThread, RosJointThread, fawkes::InterfaceDispatcher, fawkes::BlackBoardOnUpdateWaker, SyncInterfaceListener, and fawkes::BlackBoardNetHandlerInterfaceListener.

Definition at line 128 of file interface_listener.cpp.

Referenced by fawkes::BlackBoardNotifier::notify_of_data_change().

◆ bb_interface_message_received()

bool fawkes::BlackBoardInterfaceListener::bb_interface_message_received ( Interface interface,
Message message 
)
throw (
)
virtual

BlackBoard message received notification.

This is called whenever a message is received for this interface. This method is only called for writing instances of an interface, never on reading instances. If you have processed the message already, you can order that the message is not enqueued by returning false. Returning true will enqueue the message as usual. You should only do very (very!) quick tasks directly in this method, as it is out of the regular thread context and can harm performance of other plugins and the system as a whole. Note that if you decide to return false the message is not referenced. If you want to keep it longer you have to ref() it by yourself. An example where this would really make sense is a "STOP" message for the motor, which needs to be processed ASAP and maybe even waiting a couple of miliseconds for the next cycle is not acceptable.

Parameters
interfaceinterface instance that you supplied to bbil_add_message_interface()
messagethe message that was sent
Returns
true to get the message enqueued afterwards as usual, false to prevent queuing of the message.

Reimplemented in JoystickBlackBoardActListener, KatanaActThread, BBLoggerThread, DynamixelDriverThread, PanTiltRX28Thread, NaoQiLedThread, FliteSynthThread, PanTiltSonyEviD100PThread, FestivalSynthThread, PanTiltDirectedPerceptionThread, fawkes::InterfaceDispatcher, fawkes::BlackBoardOnMessageWaker, fawkes::BlackBoardNetHandlerInterfaceListener, and SyncInterfaceListener.

Definition at line 151 of file interface_listener.cpp.

Referenced by fawkes::BlackBoardNotifier::notify_of_message_received().

◆ bb_interface_reader_added()

void fawkes::BlackBoardInterfaceListener::bb_interface_reader_added ( Interface interface,
unsigned int  instance_serial 
)
throw (
)
virtual

A reading instance has been opened for a watched interface.

This is called whenever a reading instance of the interface you are watching is opened.

Parameters
interfaceinterface instance that you supplied to bbil_add_reader_interface()
instance_serialthe instance serial of the reading instance that has just been added.

Reimplemented in fawkes::InterfaceDispatcher, and fawkes::BlackBoardNetHandlerInterfaceListener.

Definition at line 166 of file interface_listener.cpp.

Referenced by fawkes::BlackBoardNotifier::notify_of_reader_added().

◆ bb_interface_reader_removed()

void fawkes::BlackBoardInterfaceListener::bb_interface_reader_removed ( Interface interface,
unsigned int  instance_serial 
)
throw (
)
virtual

A reading instance has been closed for a watched interface.

This is called whenever a reading instance of an interface you are watching is closed.

Parameters
interfaceinterface instance that you supplied to bbil_add_reader_interface()
instance_serialthe instance serial of the reading instance that has just been removed.

Reimplemented in RobotStatePublisherThread, fawkes::tf::TransformListener, SkillerExecutionThread, RosTfThread, RosLaserScanThread, LaserPointCloudThread, fawkes::InterfaceDispatcher, RosPosition3DThread, RosJointThread, and fawkes::BlackBoardNetHandlerInterfaceListener.

Definition at line 180 of file interface_listener.cpp.

Referenced by fawkes::BlackBoardNotifier::notify_of_reader_removed().

◆ bb_interface_writer_added()

void fawkes::BlackBoardInterfaceListener::bb_interface_writer_added ( Interface interface,
unsigned int  instance_serial 
)
throw (
)
virtual

A writing instance has been opened for a watched interface.

This is called whenever a writing instance of the interface you are watching is opened.

Parameters
interfaceinterface instance that you supplied to bbil_add_writer_interface()
instance_serialthe instance serial of the writing instance that has just been added.

Reimplemented in BBLoggerThread, fawkes::InterfaceDispatcher, SyncWriterInterfaceListener, and fawkes::BlackBoardNetHandlerInterfaceListener.

Definition at line 194 of file interface_listener.cpp.

Referenced by fawkes::BlackBoardNotifier::notify_of_writer_added().

◆ bb_interface_writer_removed()

void fawkes::BlackBoardInterfaceListener::bb_interface_writer_removed ( Interface interface,
unsigned int  instance_serial 
)
throw (
)
virtual

A writing instance has been closed for a watched interface.

This is called whenever a writing instance of an interface you are watching is closed.

Parameters
interfaceinterface instance that you supplied to bbil_add_writer_interface()
instance_serialthe instance serial of the writing instance that has just been removed.

Reimplemented in RobotStatePublisherThread, fawkes::tf::TransformListener, RosTfThread, BBLoggerThread, RosLaserScanThread, LaserPointCloudThread, fawkes::InterfaceDispatcher, RosPosition3DThread, RosJointThread, SyncWriterInterfaceListener, and fawkes::BlackBoardNetHandlerInterfaceListener.

Definition at line 208 of file interface_listener.cpp.

References fawkes::Interface::uid().

Referenced by fawkes::BlackBoardNotifier::notify_of_writer_removed().

◆ bbil_add_data_interface()

◆ bbil_add_message_interface()

◆ bbil_add_reader_interface()

void fawkes::BlackBoardInterfaceListener::bbil_add_reader_interface ( Interface interface)
protected

◆ bbil_add_writer_interface()

void fawkes::BlackBoardInterfaceListener::bbil_add_writer_interface ( Interface interface)
protected

◆ bbil_data_interface()

Interface * fawkes::BlackBoardInterfaceListener::bbil_data_interface ( const char *  iuid)
throw (
)
protected

Get interface instance for given UID.

A data modification notification is about to be triggered. For this the interface instance that has been added to the event listener is determined.

Parameters
iuidinterface unique ID
Returns
interface instance, NULL if not in list (non-fatal error)

Definition at line 488 of file interface_listener.cpp.

References fawkes::BlackBoardInterfaceListener::InterfaceMaps::data.

Referenced by fawkes::BlackBoardNotifier::notify_of_data_change().

◆ bbil_message_interface()

Interface * fawkes::BlackBoardInterfaceListener::bbil_message_interface ( const char *  iuid)
throw (
)
protected

Get interface instance for given UID.

A message received notification is about to be triggered. For this the interface instance that has been added to the event listener is determined.

Parameters
iuidinterface unique ID
Returns
interface instance, NULL if not in list (non-fatal error)

Definition at line 501 of file interface_listener.cpp.

References fawkes::BlackBoardInterfaceListener::InterfaceMaps::messages.

Referenced by fawkes::BlackBoardNotifier::notify_of_message_received().

◆ bbil_name()

◆ bbil_reader_interface()

Interface * fawkes::BlackBoardInterfaceListener::bbil_reader_interface ( const char *  iuid)
throw (
)
protected

Get interface instance for given UID.

A reader notification is about to be triggered. For this the interface instance that has been added to the event listener is determined.

Parameters
iuidinterface unique ID
Returns
interface instance, NULL if not in list (non-fatal error)

Definition at line 514 of file interface_listener.cpp.

References fawkes::BlackBoardInterfaceListener::InterfaceMaps::reader.

Referenced by fawkes::BlackBoardNotifier::notify_of_reader_added(), and fawkes::BlackBoardNotifier::notify_of_reader_removed().

◆ bbil_remove_data_interface()

void fawkes::BlackBoardInterfaceListener::bbil_remove_data_interface ( Interface interface)
protected

◆ bbil_remove_message_interface()

void fawkes::BlackBoardInterfaceListener::bbil_remove_message_interface ( Interface interface)
protected

Remove an interface to the message received watch list.

Only remove interfaces from the list when not currently registered to the BlackBoard or chaos and confusion will come upon you.

Parameters
interfaceinterface to watch for messages

Definition at line 307 of file interface_listener.cpp.

References MESSAGES, and fawkes::BlackBoardInterfaceListener::InterfaceMaps::messages.

Referenced by NavGraphGeneratorThread::finalize().

◆ bbil_remove_reader_interface()

void fawkes::BlackBoardInterfaceListener::bbil_remove_reader_interface ( Interface interface)
protected

Remove an interface to the reader addition/removal watch list.

Only remove interfaces from the list when not currently registered to the BlackBoard or chaos and confusion will come upon you.

Parameters
interfaceinterface to watch for addition/removal of readers

Definition at line 319 of file interface_listener.cpp.

References READER, and fawkes::BlackBoardInterfaceListener::InterfaceMaps::reader.

Referenced by RobotStatePublisherThread::bb_interface_created(), RosLaserScanThread::bb_interface_reader_removed(), RosTfThread::bb_interface_reader_removed(), RobotStatePublisherThread::bb_interface_reader_removed(), NavGraphClustersThread::loop(), and fawkes::BlackBoardInterfaceListMaintainer::~BlackBoardInterfaceListMaintainer().

◆ bbil_remove_writer_interface()

◆ bbil_writer_interface()

Interface * fawkes::BlackBoardInterfaceListener::bbil_writer_interface ( const char *  iuid)
throw (
)
protected

Get interface instance for given UID.

A writer notification is about to be triggered. For this the interface instance that has been added to the event listener is determined.

Parameters
iuidinterface unique ID
Returns
interface instance, NULL if not in list (non-fatal error)

Definition at line 527 of file interface_listener.cpp.

References fawkes::BlackBoardInterfaceListener::InterfaceMaps::writer.

Referenced by fawkes::BlackBoardNotifier::notify_of_writer_added(), and fawkes::BlackBoardNotifier::notify_of_writer_removed().


The documentation for this class was generated from the following files: