Fawkes API  Fawkes Development Version
fawkes::BlackBoard Class Referenceabstract

The BlackBoard abstract class. More...

#include <>>

Inheritance diagram for fawkes::BlackBoard:

Public Types

enum  ListenerRegisterFlag {
  BBIL_FLAG_DATA = 1, BBIL_FLAG_MESSAGES = 2, BBIL_FLAG_READER = 4, BBIL_FLAG_WRITER = 8,
  BBIL_FLAG_ALL = 15
}
 Flags to constrain listener registraion/updates. More...
 

Public Member Functions

 BlackBoard ()
 Constructor. More...
 
virtual ~BlackBoard ()
 Destructor. More...
 
virtual Interfaceopen_for_reading (const char *interface_type, const char *identifier)=0
 Open interface for reading. More...
 
virtual Interfaceopen_for_writing (const char *interface_type, const char *identifier)=0
 Open interface for writing. More...
 
virtual void close (Interface *interface)=0
 Close interface. More...
 
virtual InterfaceInfoListlist_all ()=0
 Get list of all currently existing interfaces. More...
 
virtual InterfaceInfoListlist (const char *type_pattern, const char *id_pattern)=0
 Get list of interfaces matching type and ID patterns. More...
 
virtual bool is_alive () const =0 throw ()
 Check if the BlackBoard is still alive. More...
 
virtual bool try_aliveness_restore ()=0 throw ()
 Try to restore the aliveness of the BlackBoard instance. More...
 
virtual std::list< Interface * > open_multiple_for_reading (const char *type_pattern, const char *id_pattern="*")=0
 Open multiple interfaces for reading. More...
 
template<class InterfaceType >
std::list< InterfaceType * > open_multiple_for_reading (const char *id_pattern="*")
 Open all interfaces of given type for reading. More...
 
template<class InterfaceType >
InterfaceType * open_for_reading (const char *identifier)
 Get interface of given type. More...
 
template<class InterfaceType >
InterfaceType * open_for_writing (const char *identifier)
 Get writer interface of given type. More...
 
virtual void register_listener (BlackBoardInterfaceListener *listener, ListenerRegisterFlag flag=BBIL_FLAG_ALL)
 Register BB event listener. More...
 
virtual void update_listener (BlackBoardInterfaceListener *listener, ListenerRegisterFlag flag=BBIL_FLAG_ALL)
 Update BB event listener. More...
 
virtual void unregister_listener (BlackBoardInterfaceListener *listener)
 Unregister BB interface listener. More...
 
virtual void register_observer (BlackBoardInterfaceObserver *observer)
 Register BB interface observer. More...
 
virtual void unregister_observer (BlackBoardInterfaceObserver *observer)
 Unregister BB interface observer. More...
 
std::string demangle_fawkes_interface_name (const char *type)
 Produce interface name from C++ signature. More...
 

Protected Attributes

BlackBoardNotifier__notifier
 Notifier for BB events. More...
 

Detailed Description

The BlackBoard abstract class.

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 49 of file blackboard.h.

Member Enumeration Documentation

Flags to constrain listener registraion/updates.

Enumerator
BBIL_FLAG_DATA 

consider data events

BBIL_FLAG_MESSAGES 

consider message received events

BBIL_FLAG_READER 

consider reader events

BBIL_FLAG_WRITER 

consider writer events

BBIL_FLAG_ALL 

consider all events

Definition at line 82 of file blackboard.h.

Constructor & Destructor Documentation

fawkes::BlackBoard::BlackBoard ( )

Constructor.

Definition at line 157 of file blackboard.cpp.

fawkes::BlackBoard::~BlackBoard ( )
virtual

Destructor.

Definition at line 163 of file blackboard.cpp.

Member Function Documentation

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

Close interface.

Parameters
interfaceinterface to close

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

Referenced by LaserPointCloudThread::bb_interface_created(), RosLaserScanThread::bb_interface_created(), RosTfThread::bb_interface_created(), fawkes::BlackBoardNetworkHandler::client_disconnected(), fawkes::EclExternalBlackBoard::disconnect(), ExampleBlackBoardThread::finalize(), JoystickSensorThread::finalize(), AgentControlThread::finalize(), BallPosLogThread::finalize(), RoombaJoystickThread::finalize(), ROSOdometryThread::finalize(), OpenRaveMessageHandlerThread::finalize(), FestivalSynthThread::finalize(), FliteSynthThread::finalize(), PanTiltDirectedPerceptionThread::finalize(), PanTiltSonyEviD100PThread::finalize(), RobotinoRosJointsThread::finalize(), RobotinoJoystickThread::finalize(), ROSCmdVelThread::finalize(), LaserSensorThread::finalize(), RobotinoIrPclThread::finalize(), LaserHtSensorProcThread::finalize(), MapLaserGenThread::finalize(), OpenNiHandTrackerThread::finalize(), RefBoxCommThread::finalize(), RosNavigatorThread::finalize(), LaserPointCloudThread::finalize(), WorldModelThread::finalize(), NaoQiSpeechSynthThread::finalize(), WorldModelNetworkThread::finalize(), NaoQiLedThread::finalize(), NaoQiMotionThread::finalize(), LaserFilterThread::finalize(), RosLaserScanThread::finalize(), RosTfThread::finalize(), PanTiltRX28Thread::finalize(), BBLogReplayThread::finalize(), NaoQiButtonThread::finalize(), XabslEngineThread::finalize(), OpenNiUserTrackerThread::finalize(), BBLoggerThread::finalize(), NaoQiDCMThread::finalize(), TabletopObjectsThread::finalize(), LuaAgentPeriodicExecutionThread::finalize(), RobotinoActThread::finalize(), LuaAgentContinuousExecutionThread::finalize(), RobotinoSensorThread::finalize(), SkillerExecutionThread::finalize(), KatanaActThread::finalize(), AmclThread::finalize(), OpenNiHandTrackerThread::hand_destroy(), BallPosLogThread::init(), RoombaJoystickThread::init(), LaserHtSensorProcThread::init(), NaoQiLedThread::init(), LaserFilterThread::init(), RosTfThread::init(), TabletopObjectsThread::init(), BBLoggerThread::init(), fawkes::BlackBoardNetworkHandler::loop(), WorldModelNetworkThread::loop(), OpenNiUserTrackerThread::new_user(), WorldModelNetworkThread::opponent_disapp_rcvd(), fawkes::openni::SkelIfObserver::process_queue(), BatteryMonitorTreeView::rem_host(), WorldModelMultiCopyFuser::WorldModelMultiCopyFuser(), WorldModelObjPosAverageFuser::WorldModelObjPosAverageFuser(), WorldModelObjPosMajorityFuser::WorldModelObjPosMajorityFuser(), fawkes::BlackBoardNetworkHandler::~BlackBoardNetworkHandler(), fawkes::EclExternalBlackBoard::~EclExternalBlackBoard(), JoystickRemoteBlackBoardPoster::~JoystickRemoteBlackBoardPoster(), RemoteBlackBoardRefBoxProcessor::~RemoteBlackBoardRefBoxProcessor(), fawkes::tf::TransformListener::~TransformListener(), fawkes::tf::TransformPublisher::~TransformPublisher(), and WorldModelObjPosMajorityFuser::~WorldModelObjPosMajorityFuser().

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
typetype name to strip
Returns
stripped class type, use delete to free it after you are done

Definition at line 239 of file blackboard.cpp.

bool fawkes::BlackBoard::is_alive ( ) const
throw (
)
pure virtual
InterfaceInfoList * fawkes::BlackBoard::list ( const char *  type_pattern,
const char *  id_pattern 
)
pure virtual

Get list of interfaces matching type and ID patterns.

See the fnmatch() documentation for possible patterns.

Parameters
type_patternpattern with shell like globs (* for any number of characters, ? for exactly one character) to match the interface type.
id_patternpattern with shell like globs (* for any number of characters, ? for exactly one character) to match the interface ID.
Returns
list of interfaces

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

Referenced by fawkes::InterfaceChooserDialog::init(), and fawkes::BlackBoardNetworkHandler::loop().

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

Get list of all currently existing interfaces.

Returns
list of interfaces

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

Referenced by fawkes::BlackBoardNetworkHandler::loop().

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
typetype of the interface
identifieridentifier of the interface
Returns
new fully initialized interface instance of requested type
Exceptions
OutOfMemoryExceptionthrown if there is not enough free space for the requested interface.

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

Referenced by BatteryMonitorTreeView::add_host(), LaserPointCloudThread::bb_interface_created(), RosLaserScanThread::bb_interface_created(), RosTfThread::bb_interface_created(), ExampleBlackBoardThread::init(), BallPosLogThread::init(), EclipseAgentThread::init(), RobotinoJoystickThread::init(), RoombaJoystickThread::init(), ROSCmdVelThread::init(), ROSOdometryThread::init(), RobotinoRosJointsThread::init(), RobotinoIrPclThread::init(), LaserHtSensorProcThread::init(), RefBoxCommThread::init(), WorldModelThread::init(), NaoQiLedThread::init(), NaoQiMotionThread::init(), NaoQiButtonThread::init(), XabslEngineThread::init(), BBLoggerThread::init(), LuaAgentPeriodicExecutionThread::init(), LuaAgentContinuousExecutionThread::init(), AmclThread::init(), fawkes::BlackBoardNetworkHandler::loop(), fawkes::openni::SkelIfObserver::process_queue(), fawkes::openni::HandIfObserver::process_queue(), fawkes::InterfaceChooserDialog::run_and_open_for_reading(), fawkes::openni::SkelIfObserver::SkelIfObserver(), WorldModelObjPosMajorityFuser::WorldModelObjPosMajorityFuser(), and WorldModelSingleCopyFuser::WorldModelSingleCopyFuser().

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
identifieridentifier of the interface
Returns
new fully initialized interface instance of requested type
Exceptions
OutOfMemoryExceptionthrown if there is not enough free space for the requested interface.
TypeMismatchExceptionthrown if type in interface_type and the actual class type do not fit.

Definition at line 121 of file blackboard.h.

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
typetype of the interface
identifieridentifier of the interface
Returns
new fully initialized interface instance of requested type
Exceptions
OutOfMemoryExceptionthrown if there is not enough free space for the requested interface.
BlackBoardWriterActiveExceptionthrown if there is already a writing instance with the same type/id

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

Referenced by WorldModelNetworkThread::ball_pos_rcvd(), WorldModelNetworkThread::global_ball_pos_rcvd(), OpenNiHandTrackerThread::hand_create(), ExampleBlackBoardThread::init(), AgentControlThread::init(), JoystickSensorThread::init(), EclipseAgentThread::init(), OpenRaveMessageHandlerThread::init(), PanTiltSonyEviD100PThread::init(), FliteSynthThread::init(), FestivalSynthThread::init(), PanTiltDirectedPerceptionThread::init(), LaserSensorThread::init(), LaserHtSensorProcThread::init(), MapLaserGenThread::init(), RefBoxCommThread::init(), Roomba500Thread::init(), RosNavigatorThread::init(), NaoQiSpeechSynthThread::init(), NaoQiMotionThread::init(), WorldModelNetworkThread::init(), NaoQiLedThread::init(), PanTiltRX28Thread::init(), NaoQiButtonThread::init(), BBLogReplayThread::init(), TabletopObjectsThread::init(), BBLoggerThread::init(), NaoQiDCMThread::init(), LuaAgentPeriodicExecutionThread::init(), RobotinoActThread::init(), RobotinoSensorThread::init(), SkillerExecutionThread::init(), KatanaActThread::init(), AmclThread::init(), JoystickRemoteBlackBoardPoster::JoystickRemoteBlackBoardPoster(), fawkes::BlackBoardNetworkHandler::loop(), RosLaserScanThread::loop(), OpenNiUserTrackerThread::new_user(), WorldModelNetworkThread::opponent_pose_rcvd(), WorldModelNetworkThread::pose_rcvd(), fawkes::tf::TransformPublisher::TransformPublisher(), WorldModelMultiCopyFuser::WorldModelMultiCopyFuser(), WorldModelObjPosAverageFuser::WorldModelObjPosAverageFuser(), 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
identifieridentifier of the interface
Returns
new fully initialized interface instance of requested type
Exceptions
OutOfMemoryExceptionthrown if there is not enough free space for the requested interface.
BlackBoardWriterActiveExceptionthrown if there is already a writing instance with the same type/id
TypeMismatchExceptionthrown if type in interface_type and the actual class type do not fit.

Definition at line 173 of file blackboard.h.

std::list< Interface * > fawkes::BlackBoard::open_multiple_for_reading ( const char *  type_pattern,
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_patternpattern of interface types to open, supports wildcards similar to filenames (*, ?, []), see "man fnmatch" for all supported.
id_patternpattern 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::RemoteBlackBoard, and fawkes::LocalBlackBoard.

Referenced by fawkes::openni::HandIfObserver::HandIfObserver(), LaserPointCloudThread::init(), RosLaserScanThread::init(), RosTfThread::init(), fawkes::openni::SkelIfObserver::SkelIfObserver(), fawkes::tf::TransformListener::TransformListener(), WorldModelMultiCopyFuser::WorldModelMultiCopyFuser(), WorldModelObjPosAverageFuser::WorldModelObjPosAverageFuser(), and WorldModelObjPosMajorityFuser::WorldModelObjPosMajorityFuser().

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_patternpattern 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 141 of file blackboard.h.

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::RemoteBlackBoard, and fawkes::LocalBlackBoard.

Referenced by JoystickRemoteBlackBoardPoster::joystick_changed().

void fawkes::BlackBoard::unregister_observer ( BlackBoardInterfaceObserver observer)
virtual

Unregister BB interface observer.

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

Parameters
observerBlackBoard event listener to remove

Definition at line 224 of file blackboard.cpp.

Referenced by LaserPointCloudThread::finalize(), RosLaserScanThread::finalize(), RosTfThread::finalize(), fawkes::openni::HandIfObserver::~HandIfObserver(), fawkes::openni::SkelIfObserver::~SkelIfObserver(), fawkes::tf::TransformListener::~TransformListener(), and WorldModelObjPosMajorityFuser::~WorldModelObjPosMajorityFuser().

void fawkes::BlackBoard::update_listener ( BlackBoardInterfaceListener listener,
ListenerRegisterFlag  flag = BBIL_FLAG_ALL 
)
virtual

Update BB event listener.

Parameters
listenerBlackBoard event listener to update
flagflags what to update for

Definition at line 186 of file blackboard.cpp.

Referenced by LaserPointCloudThread::bb_interface_created(), RosLaserScanThread::bb_interface_created(), and RosTfThread::bb_interface_created().

Member Data Documentation

BlackBoardNotifier* fawkes::BlackBoard::__notifier
protected

Notifier for BB events.

Definition at line 102 of file blackboard.h.

Referenced by fawkes::LocalBlackBoard::LocalBlackBoard().


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