Public Types | Public Member Functions | Protected Member Functions | Friends

fawkes::BlackBoardInterfaceListener Class Reference

BlackBoard interface listener. More...

#include <>>

Inheritance diagram for fawkes::BlackBoardInterfaceListener:
Inheritance graph
[legend]

List of all members.

Public Types

typedef LockMap< std::string,
Interface * > 
InterfaceLockMap
 Type for lockable interface maps.
typedef InterfaceLockMap::iterator InterfaceLockMapIterator
 Iterator for InterfaceLockMap.

Public Member Functions

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

Protected Member Functions

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

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 36 of file interface_listener.h.


Member Typedef Documentation

Type for lockable interface maps.

Definition at line 42 of file interface_listener.h.

Iterator for InterfaceLockMap.

Definition at line 44 of file interface_listener.h.


Constructor & Destructor Documentation

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

Constructor.

Parameters:
name_format format of name to identify the listener, see sprintf for supported tokens

Definition at line 85 of file interface_listener.cpp.

fawkes::BlackBoardInterfaceListener::~BlackBoardInterfaceListener (  )  [virtual]

Destructor.

Definition at line 97 of file interface_listener.cpp.


Member Function Documentation

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:
interface interface instance that you supplied to bbil_add_data_interface()

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

Definition at line 134 of file interface_listener.cpp.

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

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:
interface interface instance that you supplied to bbil_add_message_interface()
message the message that was sent
Returns:
true to get the message enqueued afterwards as usual, false to prevent queuing of the message.

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

Definition at line 157 of file interface_listener.cpp.

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

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:
interface interface instance that you supplied to bbil_add_reader_interface()
instance_serial the instance serial of the reading instance that has just been added.

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

Definition at line 172 of file interface_listener.cpp.

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

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:
interface interface instance that you supplied to bbil_add_reader_interface()
instance_serial the instance serial of the reading instance that has just been removed.

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

Definition at line 186 of file interface_listener.cpp.

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

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:
interface interface instance that you supplied to bbil_add_writer_interface()
instance_serial the instance serial of the writing instance that has just been added.

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

Definition at line 200 of file interface_listener.cpp.

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

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:
interface interface instance that you supplied to bbil_add_writer_interface()
instance_serial the instance serial of the writing instance that has just been removed.

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

Definition at line 214 of file interface_listener.cpp.

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

void fawkes::BlackBoardInterfaceListener::bbil_add_data_interface ( Interface interface  )  [protected]

Add an interface to the data modification watch list.

Parameters:
interface interface to watch for data modifications.

Definition at line 224 of file interface_listener.cpp.

References fawkes::LockMap< KeyType, ValueType, LessKey >::mutex(), and fawkes::Interface::uid().

Referenced by fawkes::BlackBoardNetHandlerInterfaceListener::BlackBoardNetHandlerInterfaceListener(), fawkes::InterfaceDispatcher::InterfaceDispatcher(), and SyncInterfaceListener::SyncInterfaceListener().

void fawkes::BlackBoardInterfaceListener::bbil_add_message_interface ( Interface interface  )  [protected]
void fawkes::BlackBoardInterfaceListener::bbil_add_reader_interface ( Interface interface  )  [protected]

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

This method does not mean that you add interfaces that you opened for reading but that you add an interface that you want to be informed for when reader addition/removal happens.

Parameters:
interface interface to watch for addition/removal of readers

Definition at line 257 of file interface_listener.cpp.

References fawkes::LockMap< KeyType, ValueType, LessKey >::mutex(), and fawkes::Interface::uid().

Referenced by fawkes::BlackBoardNetHandlerInterfaceListener::BlackBoardNetHandlerInterfaceListener(), and fawkes::InterfaceDispatcher::InterfaceDispatcher().

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

Add an interface to the writer addition/removal watch list.

This method does not mean that you add interfaces that you opened for writing but that you add an interface that you want to be informed for when writer addition/removal happens.

Parameters:
interface interface to watch for addition/removal of writers

Definition at line 274 of file interface_listener.cpp.

References fawkes::LockMap< KeyType, ValueType, LessKey >::mutex(), and fawkes::Interface::uid().

Referenced by SyncWriterInterfaceListener::add_interface(), fawkes::BlackBoardNetHandlerInterfaceListener::BlackBoardNetHandlerInterfaceListener(), and fawkes::InterfaceDispatcher::InterfaceDispatcher().

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:
iuid interface unique ID
Returns:
interface instance, NULL if not in list (non-fatal error)

Definition at line 391 of file interface_listener.cpp.

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

BlackBoardInterfaceListener::InterfaceLockMap * fawkes::BlackBoardInterfaceListener::bbil_data_interfaces (  )  throw () [protected]

Get data modification watch list.

Returns:
data modification watch list

Definition at line 351 of file interface_listener.cpp.

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

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:
iuid interface unique ID
Returns:
interface instance, NULL if not in list (non-fatal error)

Definition at line 409 of file interface_listener.cpp.

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

BlackBoardInterfaceListener::InterfaceLockMap * fawkes::BlackBoardInterfaceListener::bbil_message_interfaces (  )  throw () [protected]

Get message received watch list.

Returns:
message received watch list

Definition at line 360 of file interface_listener.cpp.

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

const char * fawkes::BlackBoardInterfaceListener::bbil_name (  )  const
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:
iuid interface unique ID
Returns:
interface instance, NULL if not in list (non-fatal error)

Definition at line 427 of file interface_listener.cpp.

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

BlackBoardInterfaceListener::InterfaceLockMap * fawkes::BlackBoardInterfaceListener::bbil_reader_interfaces (  )  throw () [protected]

Get reader watch list.

Returns:
reader watch list

Definition at line 369 of file interface_listener.cpp.

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

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

Remove an interface to the data modification watch list.

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

Parameters:
interface interface to watch for data modifications.

Definition at line 291 of file interface_listener.cpp.

References fawkes::LockMap< KeyType, ValueType, LessKey >::mutex(), and fawkes::Interface::uid().

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:
interface interface to watch for messages

Definition at line 305 of file interface_listener.cpp.

References fawkes::Interface::is_writer(), fawkes::LockMap< KeyType, ValueType, LessKey >::mutex(), and fawkes::Interface::uid().

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:
interface interface to watch for addition/removal of readers

Definition at line 323 of file interface_listener.cpp.

References fawkes::LockMap< KeyType, ValueType, LessKey >::mutex(), and fawkes::Interface::uid().

void fawkes::BlackBoardInterfaceListener::bbil_remove_writer_interface ( Interface interface  )  [protected]

Remove an interface to the writer 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:
interface interface to watch for addition/removal of writers

Definition at line 338 of file interface_listener.cpp.

References fawkes::LockMap< KeyType, ValueType, LessKey >::mutex(), and fawkes::Interface::uid().

Referenced by SyncWriterInterfaceListener::remove_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:
iuid interface unique ID
Returns:
interface instance, NULL if not in list (non-fatal error)

Definition at line 445 of file interface_listener.cpp.

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

BlackBoardInterfaceListener::InterfaceLockMap * fawkes::BlackBoardInterfaceListener::bbil_writer_interfaces (  )  throw () [protected]

Get writer watch list.

Returns:
writer watch list

Definition at line 378 of file interface_listener.cpp.

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


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