fawkes::BlackBoard Class Reference

The BlackBoard. More...

#include <blackboard/blackboard.h>

Inheritance diagram for fawkes::BlackBoard:

[legend]
List of all members.

Public Member Functions

virtual ~BlackBoard ()
 Virtual empty destructor.
virtual Interfaceopen_for_reading (const char *interface_type, const char *identifier)=0
 Open interface for reading.
virtual Interfaceopen_for_writing (const char *interface_type, const char *identifier)=0
 Open interface for writing.
virtual void close (Interface *interface)=0
 Close interface.
virtual InterfaceInfoListlist_all ()=0
 Get list of interfaces.
virtual bool is_alive () const =0 throw ()
 Check if the BlackBoard is still alive.
virtual bool try_aliveness_restore ()=0 throw ()
 Try to restore the aliveness of the BlackBoard instance.
virtual std::list< Interface * > open_multiple_for_reading (const char *interface_type, const char *id_pattern="*")=0
 Open multiple interfaces for reading.
template<class InterfaceType>
std::list< InterfaceType * > open_multiple_for_reading (const char *id_pattern="*")
 Open all interfaces of given type for reading.
template<class InterfaceType>
InterfaceType * open_for_reading (const char *identifier)
 Get interface of given type.
template<class InterfaceType>
InterfaceType * open_for_writing (const char *identifier)
 Get writer interface of given type.
virtual void register_listener (BlackBoardInterfaceListener *listener, unsigned int flags)=0
 Register BB event listener.
virtual void unregister_listener (BlackBoardInterfaceListener *listener)=0
 Unregister BB interface listener.
virtual void register_observer (BlackBoardInterfaceObserver *observer, unsigned int flags)=0
 Register BB interface observer.
virtual void unregister_observer (BlackBoardInterfaceObserver *observer)=0
 Unregister BB interface observer.
std::string demangle_fawkes_interface_name (const char *type)
 Produce interface name from C++ signature.

Static Public Attributes

static const unsigned int BBIL_FLAG_DATA = 1
 Data changed notification flag.
static const unsigned int BBIL_FLAG_MESSAGES = 2
 Message received notification flag.
static const unsigned int BBIL_FLAG_READER = 4
 Reader added/removed notification flag.
static const unsigned int BBIL_FLAG_WRITER = 8
 Writer added/removed notification flag.
static const unsigned int BBIL_FLAG_ALL
 All interface listener notifications.
static const unsigned int BBIO_FLAG_CREATED = 1
 Interface creation notification flag.
static const unsigned int BBIO_FLAG_DESTROYED = 2
 Interface destruction notification flag.
static const unsigned int BBIO_FLAG_ALL
 All interface observer notifications.

Detailed Description

The BlackBoard.

This class is the single one entry point for programs that use the BlackBoard. It is used to open and close interfaces, register and unregister listeners and observers and to maintain the BlackBoard shared memory segment. Not other classes shall be used directly.

The BlackBoard holds a number of so-called interfaces. The interfaces store data and provide means to pass messages. The BlackBoard also allows for registering listeners and observers. The listeners can be used to get events for specific interfaces while the observer gets global interface creation and destruction events for a specified set of types of interfaces.

An interface consists of a few parts. First there is the storage block. This is a chunk of memory in the shared memory segment where the actual data is stored. Then there is the accessor object, an instance of a derivate of the Interface class which is used to access the data in the shared memory segment. Last but not least there is an internal message queue that can be used to pass messages from readers to the writer (not the other way around!).

The interface manager keeps track of all the allocated interfaces. Events can be triggered if a specific interface changes (like logging the data to a file, sending it over the network or notifying another interface of such a change).

Interfaces can only be instantiated through the BlackBoard. The BlackBoard instantiates an interface on request and guarantees that the instance is fully initialized and usable. This cannot be guaranteed if instantiating an interface through any other means!

Interfaces can be opened for reading or writing, not both! There can be only one writer at a time for any given interface. Interfaces are identified via a type (which denotes the data and its semantics) and an identifier. There may be several interfaces for a given type, but the identifier has to be unique. The identifier is in most cases a well-known string that is used to share data among plugins.

Interfaces provide a way to propagate data to the writer via messages. Available messages types depend on the interface type. Only matching messages are accepted and can be queued.

The BlackBoard can operate in two modes, master and slave. Only the master creates and destroys the shared memory segment. Currently, the slave mode is not fully implemented and thus may not be used.

See also:
Interface

Message

Author:
Tim Niemueller

Definition at line 46 of file blackboard.h.


Constructor & Destructor Documentation

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

Virtual empty destructor.

Definition at line 197 of file blackboard.cpp.


Member Function Documentation

void fawkes::BlackBoard::close ( Interface interface  )  [pure virtual]

Close interface.

Parameters:
interface interface to close

Implemented in fawkes::LocalBlackBoard, and fawkes::RemoteBlackBoard.

Referenced by fawkes::BlackBoardNetworkHandler::client_disconnected(), fawkes::LuaInterfaceImporter::close_reading_interfaces(), fawkes::LuaInterfaceImporter::close_writing_interfaces(), SkillShellThread::connection_died(), XabslEngineThread::finalize(), WorldModelThread::finalize(), RefBoxCommThread::finalize(), AgentControlThread::finalize(), PanTiltSonyEviD100PThread::finalize(), PanTiltRX28Thread::finalize(), PanTiltDirectedPerceptionThread::finalize(), SkillerExecutionThread::finalize(), LuaAgentExecutionThread::finalize(), LaserHtSensorProcThread::finalize(), KatanaActThread::finalize(), LaserSensorThread::finalize(), JoystickSensorThread::finalize(), FliteSynthThread::finalize(), FestivalSynthThread::finalize(), WorldModelNetworkThread::finalize(), ExampleBlackBoardThread::finalize(), BBLogReplayThread::finalize(), BBLoggerThread::finalize(), BallPosLogThread::finalize(), LaserHtSensorProcThread::init(), LaserSensorThread::init(), BBLoggerThread::init(), BallPosLogThread::init(), WorldModelNetworkThread::loop(), fawkes::BlackBoardNetworkHandler::loop(), FawkesBeepDaemon::loop(), LaserGuiHildonWindow::on_connect(), LaserGuiHildonWindow::on_disconnect(), LaserGuiGtkWindow::on_disconnect(), LaserGuiGtkWindow::on_legtracker_toggled(), LaserGuiGtkWindow::on_resolution_toggled(), WorldModelNetworkThread::opponent_disapp_rcvd(), WorldModelMultiCopyFuser::WorldModelMultiCopyFuser(), WorldModelObjPosAverageFuser::WorldModelObjPosAverageFuser(), WorldModelObjPosMajorityFuser::WorldModelObjPosMajorityFuser(), fawkes::BlackBoardNetworkHandler::~BlackBoardNetworkHandler(), JoystickBlackBoardLogger::~JoystickBlackBoardLogger(), JoystickBlackBoardPoster::~JoystickBlackBoardPoster(), LaserGuiHildonWindow::~LaserGuiHildonWindow(), RemoteBlackBoardRefBoxProcessor::~RemoteBlackBoardRefBoxProcessor(), SkillShellThread::~SkillShellThread(), WebviewBlackBoardRequestProcessor::~WebviewBlackBoardRequestProcessor(), WorldModelMultiCopyFuser::~WorldModelMultiCopyFuser(), WorldModelObjPosAverageFuser::~WorldModelObjPosAverageFuser(), WorldModelObjPosMajorityFuser::~WorldModelObjPosMajorityFuser(), and WorldModelSingleCopyFuser::~WorldModelSingleCopyFuser().

std::string fawkes::BlackBoard::demangle_fawkes_interface_name ( const char *  type  ) 

Produce interface name from C++ signature.

This extracts the interface name for a mangled signature. It has has been coded with GCC (4) in mind and assumes interfaces to be in the fawkes namespace. It cannot deal with anythin else.

Parameters:
type type name to strip
Returns:
stripped class type, use delete to free it after you are done

Definition at line 210 of file blackboard.cpp.

Referenced by open_for_reading(), open_for_writing(), and open_multiple_for_reading().

bool fawkes::BlackBoard::is_alive (  )  const throw () [pure virtual]

Check if the BlackBoard is still alive.

Returns:
true, if the BlackBoard is still alive and may be used, false otherwise.

Implemented in fawkes::LocalBlackBoard, and fawkes::RemoteBlackBoard.

Referenced by JoystickBlackBoardLogger::bb_interface_data_changed(), RemoteBlackBoardRefBoxProcessor::check_connection(), JoystickBlackBoardPoster::joystick_changed(), FawkesBeepDaemon::loop(), and RemoteBlackBoardRefBoxProcessor::refbox_process().

InterfaceInfoList * fawkes::BlackBoard::list_all (  )  [pure virtual]

Get list of interfaces.

Returns:
list of interfaces

Implemented in fawkes::LocalBlackBoard, and fawkes::RemoteBlackBoard.

Referenced by fawkes::BlackBoardNetworkHandler::loop(), and WebviewBlackBoardRequestProcessor::process_request().

template<class InterfaceType>
InterfaceType * fawkes::BlackBoard::open_for_reading ( const char *  identifier  ) 

Get interface of given type.

This will open a new interface for reading just like the non-template version of open_for_reading(). But with the template method you will get a correctly typed object that you can use. An TypeMismatchException is thrown if the string representation of the type and the actual class type of the interface do not match.

Parameters:
identifier identifier of the interface
Returns:
new fully initialized interface instance of requested type
Exceptions:
OutOfMemoryException thrown if there is not enough free space for the requested interface.
TypeMismatchException thrown if type in interface_type and the actual class type do not fit.

Definition at line 107 of file blackboard.h.

References demangle_fawkes_interface_name(), and open_for_reading().

Interface * fawkes::BlackBoard::open_for_reading ( const char *  type,
const char *  identifier 
) [pure virtual]

Open interface for reading.

This will create a new interface instance of the given type. The result can be casted to the appropriate type.

Parameters:
type type of the interface
identifier identifier of the interface
Returns:
new fully initialized interface instance of requested type
Exceptions:
OutOfMemoryException thrown if there is not enough free space for the requested interface.

Implemented in fawkes::LocalBlackBoard, and fawkes::RemoteBlackBoard.

Referenced by BatteryMonitorTreeView::add_host(), XabslEngineThread::init(), WorldModelThread::init(), RefBoxCommThread::init(), EclipseAgentThread::init(), LuaAgentExecutionThread::init(), LaserHtSensorProcThread::init(), ExampleBlackBoardThread::init(), BBLoggerThread::init(), BallPosLogThread::init(), JoystickBlackBoardLogger::JoystickBlackBoardLogger(), SkillShellThread::loop(), fawkes::BlackBoardNetworkHandler::loop(), LaserGuiHildonWindow::on_connect(), LaserGuiGtkWindow::on_connect(), LaserGuiGtkWindow::on_legtracker_toggled(), LaserGuiGtkWindow::on_resolution_toggled(), open_for_reading(), WebviewBlackBoardRequestProcessor::process_request(), WorldModelObjPosMajorityFuser::WorldModelObjPosMajorityFuser(), and WorldModelSingleCopyFuser::WorldModelSingleCopyFuser().

template<class InterfaceType>
InterfaceType * fawkes::BlackBoard::open_for_writing ( const char *  identifier  ) 

Get writer interface of given type.

This will open a new interface for writing just like the non-template version of open_for_writing(). But with the template method you will get a correctly typed object that you can use. An TypeMismatchException is thrown if the string representation of the type and the actual class type of the interface do not match.

Parameters:
identifier identifier of the interface
Returns:
new fully initialized interface instance of requested type
Exceptions:
OutOfMemoryException thrown if there is not enough free space for the requested interface.
BlackBoardWriterActiveException thrown if there is already a writing instance with the same type/id
TypeMismatchException thrown if type in interface_type and the actual class type do not fit.

Definition at line 155 of file blackboard.h.

References demangle_fawkes_interface_name(), and open_for_writing().

Interface * fawkes::BlackBoard::open_for_writing ( const char *  type,
const char *  identifier 
) [pure virtual]

Open interface for writing.

This will create a new interface instance of the given type. The result can be casted to the appropriate type. This will only succeed if there is not already a writer for the given interface type/id!

Parameters:
type type of the interface
identifier identifier of the interface
Returns:
new fully initialized interface instance of requested type
Exceptions:
OutOfMemoryException thrown if there is not enough free space for the requested interface.
BlackBoardWriterActiveException thrown if there is already a writing instance with the same type/id

Implemented in fawkes::LocalBlackBoard, and fawkes::RemoteBlackBoard.

Referenced by WorldModelNetworkThread::ball_pos_rcvd(), WorldModelNetworkThread::global_ball_pos_rcvd(), RefBoxCommThread::init(), EclipseAgentThread::init(), AgentControlThread::init(), PanTiltSonyEviD100PThread::init(), PanTiltRX28Thread::init(), PanTiltDirectedPerceptionThread::init(), SkillerExecutionThread::init(), LuaAgentExecutionThread::init(), LaserHtSensorProcThread::init(), KatanaActThread::init(), LaserSensorThread::init(), JoystickSensorThread::init(), FliteSynthThread::init(), FestivalSynthThread::init(), WorldModelNetworkThread::init(), ExampleBlackBoardThread::init(), BBLogReplayThread::init(), BBLoggerThread::init(), JoystickBlackBoardPoster::JoystickBlackBoardPoster(), fawkes::BlackBoardNetworkHandler::loop(), FawkesBeepDaemon::loop(), LaserGuiGtkWindow::on_connect(), open_for_writing(), WorldModelNetworkThread::opponent_pose_rcvd(), WorldModelNetworkThread::pose_rcvd(), WorldModelMultiCopyFuser::WorldModelMultiCopyFuser(), WorldModelObjPosAverageFuser::WorldModelObjPosAverageFuser(), WorldModelObjPosMajorityFuser::WorldModelObjPosMajorityFuser(), and WorldModelSingleCopyFuser::WorldModelSingleCopyFuser().

template<class InterfaceType>
std::list< InterfaceType * > fawkes::BlackBoard::open_multiple_for_reading ( const char *  id_pattern = "*"  ) 

Open all interfaces of given type for reading.

This will create interface instances for all currently registered interfaces of the given type. The result can be casted to the appropriate type.

Parameters:
id_pattern pattern of interface IDs to open, supports wildcards similar to filenames (*, ?, []), see "man fnmatch" for all supported.
Returns:
list of new fully initialized interface instances of requested type. The is allocated using new and you have to free it using delete after you are done with it!

Definition at line 126 of file blackboard.h.

References demangle_fawkes_interface_name(), and open_multiple_for_reading().

std::list< Interface * > fawkes::BlackBoard::open_multiple_for_reading ( const char *  type,
const char *  id_pattern = "*" 
) [pure virtual]

Open multiple interfaces for reading.

This will create interface instances for currently registered interfaces of the given type that match the given ID pattern. The result can be casted to the appropriate type.

Parameters:
type type of the interface
id_pattern pattern of interface IDs to open, supports wildcards similar to filenames (*, ?, []), see "man fnmatch" for all supported.
Returns:
list of new fully initialized interface instances of requested type. You have to close all interfaces on your own when done with the list!

Implemented in fawkes::LocalBlackBoard, and fawkes::RemoteBlackBoard.

Referenced by open_multiple_for_reading(), WorldModelMultiCopyFuser::WorldModelMultiCopyFuser(), WorldModelObjPosAverageFuser::WorldModelObjPosAverageFuser(), and WorldModelObjPosMajorityFuser::WorldModelObjPosMajorityFuser().

void fawkes::BlackBoard::register_listener ( BlackBoardInterfaceListener listener,
unsigned int  flags 
) [pure virtual]

Register BB event listener.

Parameters:
listener BlackBoard event listener to register
flags an or'ed combination of BBIL_FLAG_DATA, BBIL_FLAG_READER, BBIL_FLAG_WRITER and BBIL_FLAG_INTERFACE. Only for the given types the event listener is registered. BBIL_FLAG_ALL can be supplied to register for all events.

Implemented in fawkes::LocalBlackBoard, and fawkes::RemoteBlackBoard.

Referenced by BatteryMonitorTreeView::add_host(), fawkes::BlackBoardNetHandlerInterfaceListener::BlackBoardNetHandlerInterfaceListener(), PanTiltSonyEviD100PThread::init(), PanTiltRX28Thread::init(), PanTiltDirectedPerceptionThread::init(), SkillerExecutionThread::init(), KatanaActThread::init(), FliteSynthThread::init(), FestivalSynthThread::init(), BBLoggerThread::init(), JoystickBlackBoardLogger::JoystickBlackBoardLogger(), LaserDeadSpotCalibrator::LaserDeadSpotCalibrator(), LaserGuiHildonWindow::on_connect(), LaserGuiGtkWindow::on_connect(), LaserGuiGtkWindow::on_resolution_toggled(), and SyncInterfaceListener::SyncInterfaceListener().

void fawkes::BlackBoard::register_observer ( BlackBoardInterfaceObserver observer,
unsigned int  flags 
) [pure virtual]

Register BB interface observer.

Parameters:
observer BlackBoard interface observer to register
flags an or'ed combination of BBIO_FLAG_CREATED, BBIO_FLAG_DESTROYED

Implemented in fawkes::LocalBlackBoard, and fawkes::RemoteBlackBoard.

Referenced by WorldModelMultiCopyFuser::WorldModelMultiCopyFuser(), WorldModelObjPosAverageFuser::WorldModelObjPosAverageFuser(), and WorldModelObjPosMajorityFuser::WorldModelObjPosMajorityFuser().

bool fawkes::BlackBoard::try_aliveness_restore (  )  throw () [pure virtual]

Try to restore the aliveness of the BlackBoard instance.

Note that even though the aliveness of the BlackBoard is restored single interfaces may still be invalid. That can for instance happen if a remote connection is re-established and a writer has been created during the downtime and an own writer instance of that very interface cannot be restored.

Returns:
true if the aliveness could be restored and the BlackBoard is operational again, false otherwise.

Implemented in fawkes::LocalBlackBoard, and fawkes::RemoteBlackBoard.

Referenced by JoystickBlackBoardLogger::bb_interface_data_changed(), and JoystickBlackBoardPoster::joystick_changed().

void fawkes::BlackBoard::unregister_listener ( BlackBoardInterfaceListener listener  )  [pure virtual]

Unregister BB interface listener.

This will remove the given BlackBoard interface listener from any event that it was previously registered for.

Parameters:
listener BlackBoard event listener to remove

Implemented in fawkes::LocalBlackBoard, and fawkes::RemoteBlackBoard.

Referenced by PanTiltSonyEviD100PThread::finalize(), PanTiltRX28Thread::finalize(), PanTiltDirectedPerceptionThread::finalize(), SkillerExecutionThread::finalize(), KatanaActThread::finalize(), FliteSynthThread::finalize(), FestivalSynthThread::finalize(), BBLoggerThread::finalize(), LaserGuiGtkWindow::on_resolution_toggled(), fawkes::BlackBoardNetHandlerInterfaceListener::~BlackBoardNetHandlerInterfaceListener(), and SyncInterfaceListener::~SyncInterfaceListener().

void fawkes::BlackBoard::unregister_observer ( BlackBoardInterfaceObserver observer  )  [pure virtual]

Unregister BB interface observer.

This will remove the given BlackBoard event listener from any event that it was previously registered for.

Parameters:
observer BlackBoard event listener to remove

Implemented in fawkes::LocalBlackBoard, and fawkes::RemoteBlackBoard.

Referenced by fawkes::LuaInterfaceImporter::close_reading_interfaces(), WorldModelMultiCopyFuser::~WorldModelMultiCopyFuser(), WorldModelObjPosAverageFuser::~WorldModelObjPosAverageFuser(), and WorldModelObjPosMajorityFuser::~WorldModelObjPosMajorityFuser().


Member Data Documentation

const unsigned int fawkes::BlackBoard::BBIL_FLAG_ALL [static]

Initial value:

All interface listener notifications.

Definition at line 75 of file blackboard.h.

Referenced by fawkes::BlackBoardNetHandlerInterfaceListener::BlackBoardNetHandlerInterfaceListener().

const unsigned int fawkes::BlackBoard::BBIL_FLAG_DATA = 1 [static]

Data changed notification flag.

Definition at line 71 of file blackboard.h.

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

const unsigned int fawkes::BlackBoard::BBIL_FLAG_MESSAGES = 2 [static]

Message received notification flag.

Definition at line 72 of file blackboard.h.

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

const unsigned int fawkes::BlackBoard::BBIL_FLAG_READER = 4 [static]

Reader added/removed notification flag.

Definition at line 73 of file blackboard.h.

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

const unsigned int fawkes::BlackBoard::BBIL_FLAG_WRITER = 8 [static]

Writer added/removed notification flag.

Definition at line 74 of file blackboard.h.

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

const unsigned int fawkes::BlackBoard::BBIO_FLAG_ALL [static]

Initial value:

All interface observer notifications.

Definition at line 79 of file blackboard.h.

const unsigned int fawkes::BlackBoard::BBIO_FLAG_CREATED = 1 [static]

Interface creation notification flag.

Definition at line 77 of file blackboard.h.

Referenced by fawkes::BlackBoardNotifier::register_observer(), and WorldModelObjPosMajorityFuser::WorldModelObjPosMajorityFuser().

const unsigned int fawkes::BlackBoard::BBIO_FLAG_DESTROYED = 2 [static]

Interface destruction notification flag.

Definition at line 78 of file blackboard.h.

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


The documentation for this class was generated from the following files:
Generated on Tue Feb 22 13:31:37 2011 for Fawkes API by  doxygen 1.4.7