iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages

#include <nrt/Core/Blackboard/Blackboard.H>

The Blackboard handles communication of Message objects between Module objects.

For the most part, users should never need to directly reference a Blackboard. Each executable has a global Singleton Blackboard that can be accessed as nrt::Blackboard::instance(). All further interaction with a Blackboard is usually handled automatically via a Module's post(), onMessage(), check(), etc.

The NRT Blackboard system exposes three interfaces:

  • A strongly-typed and highly-efficient interface via Module ports. This is the preferred interface when programming NRT modules. A call to a Module's poster port post() function will, under the hood, communicate with the localBlackboard, which may further communicate with remote Blackboards in a federation. Likewise, instantiating a Module with ports will automatically register these ports with the Blackboard federation.
  • A weakly-typed, strings-based, less efficient interface available on the Blackboard directly. This interface should typically never be used from within Module objects. Instead, it allows transparent access to modules, ports, connectors, parameters, etc on local or remote Blackboards via a unified interface. This interface is useful, for example, for GUI designers or people who write applications that interact with the Blackboard federation or present a view of it to users, as opposed to standard NRT modules that just post and receive messages and process them. For example, if you created a module, then call Module::setModuleNamespace() on that module rather than Blackboard::setModuleNamespace() on the Blackboard. The nrtDesigner is an example of an application that makes extensive use of the strings-based interface to instantiate new modules on local or remote Blackboards, split/unsplit ports, set parameters, create/delete connectors, etc.
  • The BlackboardManager interface, which allows configuration of network communications, who/where the master Blackboard is, etc. See BlackboardManager for details. Blackboard derives from BlackboardManager, which itself derives from Manager, so this interface also includes the management of command-line arguments and of collections of Component objects (Module derives from Component). See Manager and Component for details. Because BlackboardManager and Manager are both folder into Blackboard, they do not need to be instantiated eplicitly in executables that will use a Blackboard. Just access the Blackboard and the managers are part of it.
Examples:
tests/test-Module.C, tests/test-ResultsSyntax.C, tests/test-split-messages.C, and tests/test-TransformManager.C.

Definition at line 189 of file Blackboard.H.

Inheritance diagram for nrt::Blackboard:
nrt::Singleton< T > nrt::BlackboardManager nrt::Manager nrt::Parameter< blackboardmanager::masterip, blackboardmanager::masterport, blackboardmanager::master, blackboardmanager::nick > nrt::Component nrt::Parameter< manager::help, manager::profilebb, manager::profilelog, manager::onlineprofile, manager::profilesaveto, manager::loglevel > nrt::ParameterRegistry

Public Member Functions

void abortAllSplitReceive () const
 Abort all ongoing split receive.
 
Blackboard basics and debugging
 Blackboard ()
 Constructor. More...
 
virtual ~Blackboard ()
 Destructor.
 
BlackboardUID const & uid () const
 Our UID.
 
std::string const & uidstr () const
 Our UID as a string.
 
std::string const & nickname () const
 Our Nickname.
 
std::string const & masteruid () const
 The UID (as a string) of the Blackboard federation master (could be ourselves)
 
void printInfo (std::ostream &os) const
 Print some debugging info about registered posters, callbacks, etc.
 
void printMessages (std::ostream &os) const
 Print current Message objects on the Blackboard.
 
void printSummary (std::ostream &os) const
 Print out the data in a BlackboardFederationSummary.
 
int getCallbackCount () const
 Get the number of currently active onMessage() subscriber callbacks.
 
Distributed Blackboard Federation updates
void waitUntilUpdated () const
 Wait until all pending Blackboard federation transactions (if any) are complete. More...
 
std::shared_ptr
< nrt::blackboard::BlackboardFederationSummary
const > 
getLatestBFS (bool waituntilupdated=false) const
 Get the latest available BlackboardFederationSummary. More...
 
std::string getAutoTopic (std::string const &namespc)
 Get an automatically-generated, federation-unique-within-a-namespace topic name.
 
Strings-based (less efficient) access to local and remote modules, ports, connectors, etc
std::string getHelpMessage (std::string const &bbuid)
 Get the help message from local or remote Blackboard. More...
 
void createNamespace (std::string const &namespc)
 Create a namespace on the master blackboard.
 
void renameNamespace (std::string const &oldnamespc, std::string const &newnamespc)
 Rename a namespace and all its contents.
 
void deleteNamespace (std::string const &namespc)
 Delete a namespace.
 
void setModuleNamespace (std::string const &module, std::string const &namespc)
 Set the namespace of a module.
 
std::string getModuleNamespace (std::string const &module)
 Get the namespace of a module. More...
 
void markNamespaceModified (std::string const &namespc)
 Mark a namespace (macro-module) as modified, so that GUI will request user to save it. More...
 
std::string createConnector (nrt::ConnectorFlavor const flavor, std::string const &msgtype, std::string const &rettype, std::string const &portname, std::string const &namespc, nrt::ConnectorType const type, std::string const &topic, std::string const &topicfilt)
 Create a connector on the master Blackboard. More...
 
std::string getConnector (std::string const &namespc, std::string const &portname)
 Lookup a Connector UID from a namespace and instance name (portname) within that namespace.
 
void deleteConnector (std::string const &connuid)
 Delete a connector on the master blackboard.
 
void setConnectorTopic (std::string const &connuid, std::string const &topic)
 Set the topic on a local or remote connector.
 
void setConnectorTopicFilter (std::string const &connuid, std::string const &topicfilter)
 Set the topic filter on a local or remote connector.
 
void setMessagePosterTopic (std::string const &module, std::string const &portname, std::string const &topic)
 Set the topic of a poster port of a module. More...
 
void splitMessagePoster (std::string const &module, std::string const &portname, bool const splitit=true)
 Split/unsplit a poster port of a module. More...
 
void setMessageCheckerTopicFilter (std::string const &module, std::string const &portname, std::string const &topicfilter)
 Set the topic filter of a checker. More...
 
void setMessageSubscriberTopicFilter (std::string const &module, std::string const &portname, std::string const &topicfilter)
 Set the topic filter of a subscriber port of a module. More...
 
void splitMessageSubscriber (std::string const &module, std::string const &portname, bool const splitit=true)
 Split/unsplit a subscriber port of a module. More...
 
void useModuleLibrary (std::string const &paths="")
 Instantiate a ModuleLibrary on the local Blackboard and parse all the manifests, load all the icons, etc. More...
 
std::vector< ModuleDescriptiongetModuleLibraryContents (std::string const &bbuid)
 Get a copy of the ModuleLibrary contents on a (local or remote) blackboard. More...
 
template<class Mod >
std::shared_ptr< Mod > addModule (std::string const &instanceName="", std::string const &namespc="")
 Create a Module and register it with the local Blackboard. More...
 
template<class Mod >
std::shared_ptr< Mod > addSubModule (std::string const &instanceName)=delete
 Use addModule() to add a top-level module to the Blackboard, as opposed to nrt::Module::addSubModule()
 
std::pair< std::string,
std::string > 
loadModule (std::string const &bbuid, std::string const &sopath, std::string const &logicalpath, std::string const &instance="", std::string const &namespc="", bool versioncheck=true)
 Load a module from a shared library file, on the local Blackboard or on a remote one. More...
 
std::pair< std::string,
std::string > 
loadModuleLogical (std::string const &bbnick, std::string const &logicalpath, std::string const &instance="", std::string const &namespc="", bool versioncheck=true)
 Load a module from a shared library file, on the local Blackboard or on a remote one. More...
 
std::string loadMacroModule (std::string const &logicalpath, std::string const &instancename, std::string const &namespc, std::map< std::string, std::string > const &bbnickremap)
 Load a macro-module on the Blackboard master, by logical path. More...
 
void saveMacroModule (std::string const &namespc, nrt::ModuleManifest const &manifest)
 Save a macro-module. More...
 
template<class Mod >
void removeModule (std::shared_ptr< Mod > &module)
 Remove a top-level Module from the local Blackboard, by shared_ptr. More...
 
template<class Mod >
void removeSubModule (std::shared_ptr< Mod > &module)=delete
 Use removeModule() to remove a top-level module from Blackboard, as opposed to nrt::Module::removeSubModule()
 
void removeModule (std::string const &instanceName)
 Remove a top-level Module from the local Blackboard, by instance name.
 
void removeSubModule (std::string const &instanceName)=delete
 Use removeModule() to remove a top-level module from Blackboard, as opposed to nrt::Module::removeSubModule()
 
template<class Mod = nrt::Module>
std::shared_ptr< Mod > getModule (std::string const &instanceName) const
 Get a top-level Module by instance name. More...
 
template<class Mod >
std::shared_ptr< Mod > getSubModule (std::string const &instanceName) const =delete
 Use getModule() on the Blackboard as opposed to nrt::Module::getSubModule() on modules.
 
void unloadModule (std::string const &module)
 Unload a module previously loaded with loadModule() or added with addModule(), local or remote. More...
 
nrt::ModuleManifest loadManifest (std::string const &bbuid, std::string const &unixroot, std::string const &logicalpath)
 Load a Module or Macro-Module manifest. More...
 
void saveManifest (std::string const &bbuid, std::string const &unixroot, std::string const &logicalpath, nrt::ModuleManifest const &manifest)
 Save a Module or Macro-Module manifest.
 
- Public Member Functions inherited from nrt::BlackboardManager
 BlackboardManager (std::string const &instanceName="Blackboard")
 Constructor.
 
virtual ~BlackboardManager ()
 Destructor.
 
void fedinit ()
 Initialization. More...
 
void fedstart ()
 Starts the component, and its subtree, recursively. More...
 
void fedlaunch ()
 Launch the run() function, and propagate to subcomponents. More...
 
void fedendrun ()
 Switch out of running state and then call waitendrun() to wait for all run() threads to complete. More...
 
void fedstop ()
 Stops the component and its subtree, recursively. More...
 
void feduninit ()
 Un-initialize. More...
 
void setRunStateFromMaster ()
 Set our runstate up/down to match the Blackboard federation master. More...
 
virtual void init ()
 Local initialization.
 
virtual void start ()
 Local start. More...
 
virtual void launch ()
 Local launch. More...
 
virtual void endrun ()
 Local endrun. More...
 
virtual void stop ()
 Local stop. More...
 
virtual void uninit ()
 Local un-init. More...
 
- Public Member Functions inherited from nrt::Manager
 Manager (std::string const &instanceID="TheManager")
 Constructor without command-line args. More...
 
 Manager (int argc, char const *argv[], std::string const &instanceID="TheManager")
 Constructor. More...
 
void setCommandLineArgs (int argc, char const *argv[])
 Set the command-line arguments, call this before start() if args were not passed at construction.
 
virtual ~Manager ()
 Destructor.
 
std::vector< std::string > const & remainingArgs () const
 Get the remaining arguments that were not parsed by the command line. More...
 
void delayParseCommandLine ()
 Do not parse command-line arguments during preInit() More...
 
template<>
std::shared_ptr< ComponentgetComponent (std::string const &instanceName) const
 
template<class Comp >
std::shared_ptr< Comp > addComponent (std::string const &instanceName="")
 Pseudo-constructor: construct a top-level Component. More...
 
template<class Comp >
std::shared_ptr< Comp > addSubComponent (std::string const &instanceName)=delete
 Use addComponent() on the Manager as opposed to nrt::Component::addSubComponent()
 
template<class Comp >
void removeComponent (std::shared_ptr< Comp > &component)
 Remove a top-level Component from the Manager, by shared_ptr. More...
 
template<class Comp >
void removeSubComponent (std::shared_ptr< Comp > &component)=delete
 Use removeComponent() on the Manager as opposed to nrt::Component::removeSubComponent()
 
void removeComponent (std::string const &instanceName)
 Remove a top-level Component from the Manager, by instance name.
 
void removeSubComponent (std::string const &instanceName)=delete
 Use removeComponent() on the Manager as opposed to nrt::Component::removeSubComponent()
 
template<class Comp = nrt::Component>
std::shared_ptr< Comp > getComponent (std::string const &instanceName) const
 Get a top-level component by instance name. More...
 
template<class Comp >
std::shared_ptr< Comp > getSubComponent (std::string const &instanceName) const =delete
 Use getComponent() on the Manager as opposed to nrt::Component::getSubComponent()
 
- Public Member Functions inherited from nrt::Component
 Component (std::string const &instanceName)
 Constructor. More...
 
void prepareForDeletion ()
 Prepare for deletion: uninit and disconnect from our parent. More...
 
virtual ~Component ()
 Virtual destructor for safe inheritance. More...
 
template<>
std::shared_ptr< ComponentgetSubComponent (std::string const &instanceName) const
 
template<class Comp >
std::shared_ptr< Comp > addSubComponent (std::string const &instanceName="")
 Pseudo-constructor: construct and add another component as a subcomponent of this one. More...
 
template<class Comp >
void removeSubComponent (std::shared_ptr< Comp > &component)
 Remove a sub-Component from this Component, by shared_ptr. More...
 
void removeSubComponent (std::string const &instanceName)
 Remove a sub-Component from this Component, by instance name.
 
template<class Comp = nrt::Component>
std::shared_ptr< Comp > getSubComponent (std::string const &instanceName) const
 Get a sub-component by instance name. More...
 
bool isTopLevel () const
 Returns true if this component is top-level, i.e., its parent is an nrt::Manager (including nrt::Blackboard)
 
bool initialized () const
 Has this component been initialized yet?
 
bool started () const
 Is this component started, i.e., it has passed the start() state and not yet entered the stop() state.
 
bool running () const
 Is this component running, i.e., has passed start() and been launch()ed and not yet entered the stop() state.
 
void wait ()
 Wait until all run() functions decide on their own that they are finished. More...
 
Component::MetaInfo const & meta () const
 Get the metainfo of this Component. More...
 
template<typename T >
std::vector< std::string > setParamVal (std::string const &paramdescriptor, T const &val)
 Set a parameter value. More...
 
template<typename T >
void setParamValUnique (std::string const &paramdescriptor, T const &val)
 Set a parameter value, simple version assuming only one parameter match. More...
 
template<typename T >
std::vector< std::pair
< std::string, T > > 
getParamVal (std::string const &paramdescriptor) const
 Get parameter(s) value(s) by descriptor. More...
 
template<typename T >
getParamValUnique (std::string const &paramdescriptor) const
 Get a parameter value, simple version assuming only one parameter match. More...
 
std::vector< std::string > setParamString (std::string const &paramdescriptor, std::string const &val)
 Set a parameter value, by string. More...
 
void setParamStringUnique (std::string const &paramdescriptor, std::string const &val)
 Set a parameter value by string, simple version assuming only one parameter match. More...
 
std::vector< std::pair
< std::string, std::string > > 
getParamString (std::string const &paramdescriptor) const
 Get a parameter value, by string. More...
 
std::string getParamStringUnique (std::string const &paramdescriptor) const
 Get a parameter value by string, simple version assuming only one parameter match. More...
 
std::string descriptor () const
 Get our full descriptor (including all parents) as [Classname-Instancename]:[...]:[...].
 
std::string parentModuleUID () const
 Get the ModuleUID (as string) of this Component's nearest parent Module, or an empty string.
 
void prettyPrintTree (std::ostream &os, int indent=0) const
 Produce a nice textual hierarchy of this Component's sub-tree.
 
std::vector< std::pair
< std::string,
nrt::ParameterSummary > > 
getParamSummary (std::string const &paramdescriptor) const
 Return a list of parameter summaries for a given descriptor. More...
 
std::vector< std::pair
< std::string,
nrt::ParameterSummary > > 
getParamSummary (bool skipsubmodules=false) const
 Return a list of parameter summaries for all parameters of this Component and its subcomponents. More...
 
void setPath (std::string const &path)
 Assign a filesystem path to this component.
 
std::string absolutePath (std::string const &path)
 If given path is relative (not starting with /), prepend the Component path to it; otherwise, no-op.
 
virtual void notifyAllParamChanged (nrt::ParameterState const state) const
 This method is called by the Blackboard to refresh a ParamChangedListener.
 
virtual void getAllParamSummaries (std::vector< nrt::ParameterSummary > &ps) const
 Recursively get all param summaries.
 
- Public Member Functions inherited from nrt::ParameterRegistry
void addParameter (ParameterBase *const param)
 The parameter class uses this method to register itself on construction with it's owning Component.
 
void removeParameter (ParameterBase *const param)
 The parameter class uses this method to un-register itself on destruction with it's owning Component.
 

Interface to listener objects that get activated when various Blackboard contents are updated

Create a port for a Module parameter

If the module is not local, request will be dispatched to the appropriate remote Blackboard Delete a port for a Module parameter

If the module is not local, request will be dispatched to the appropriate remote Blackboard deleteModuleParamPort(ModuleParamPort const ptype, std::string const & module, std::string const & descriptor);

class Singleton< Blackboard >
 Needed by nrt::Singleton.
 
class ModuleBase
 Be friends with people who can post/service Message and Request, and only with those.
 
class BlackboardManager
 Allow our BlackboardManager base to access our internals.
 
class BlackboardMaster
 Allow BlackboardMaster to dispatch remote commands.
 
class Module
 Allow Module to register itself with us.
 
class ConnectorBase
 Allow ConnectorBase to register itself with us.
 
class nrt::NetIce::BlackboardClientI
 Allow Ice network client to talk to us.
 
class MessagePosterCoreBase
 Allow ports to notify us when their topic/filter changes.
 
class MessageCheckerCoreBase
 
class MessageSubscriberCoreBase
 
template<class... Postings>
class nrt::MessagePoster
 
template<class Posting >
class nrt::MessagePosterCore
 
template<class... Checkings>
class nrt::MessageChecker
 
template<class Checking >
class nrt::MessageCheckerCore
 
template<class... Subscriptions>
class nrt::MessageSubscriber
 
template<class Subscription >
class nrt::MessageSubscriberCore
 
std::vector
< nrt::ParameterSummary
registerParamChangedListener (nrt::ParamChangedListener *lis)
 Register a listener that should be called each time a parameter of a module on bbuid changes. More...
 
void unRegisterParamChangedListener (nrt::ParamChangedListener *lis)
 Un-Register a listener that should be called each time a parameter of a module on bbuid changes.
 
void notifyParamChanged (nrt::ModuleBase const *mod, nrt::ParameterState const state, nrt::ParameterBase const *const param)
 Notify that a Parameter of a local Module/Component changed, will forward the notify to matching listeners.
 
void setParam (std::string const &bbuid, std::string const &descriptor, std::string const &value)
 Set the value of a Parameter on a (possibly remote) Blackboard. More...
 
void setModuleParam (std::string const &module, std::string const &relativedescriptor, std::string const &value)
 Set the value of a Parameter on a Module on a (possibly remote) Blackboard. More...
 
std::vector
< nrt::ParameterSummary
getAllModuleParams (std::string const &module)
 Get the current value of all of a Module's (and its sub-modules & sub-components) parameters. More...
 
void registerBlackboardFederationSummaryListener (nrt::BlackboardFederationSummaryListener *lis)
 Register a listener that should be called each time a BlackboardFederationSummary is available. More...
 
void unRegisterBlackboardFederationSummaryListener (nrt::BlackboardFederationSummaryListener *lis)
 Un-Register a listener that should be called each time a BlackboardFederationSummary is available.
 
void requestBlackboardUpdate (std::string const &bbuid)
 Request that the specified Blackboard (could be us) sends a Blackboard Federation update.
 
void registerBlackboardGUIdataListener (nrt::BlackboardGUIdataListener *lis)
 Register a listener that should be called each time some GUI data is updated. More...
 
void unRegisterBlackboardGUIdataListener (nrt::BlackboardGUIdataListener *lis)
 Un-Register a listener that should be called each time some GUI data is available.
 
nrt::blackboard::GUIdata getGUIdata (std::string const &key)
 Get GUI data for a given key of form m:ModuleUID, n:namespace, etc.
 
void setGUIdata (std::string const &key, nrt::blackboard::GUIdata const &gd)
 Create/update GUI data for a given key of form m:ModuleUID or n:namespace.
 
nrt::BlackboardUsageData getBlackboardUsageData (std::string const &bbuid)
 Get Blackboard usage data from a (local or remote) Blackboard.
 
void registerRunStateActionListener (nrt::RunStateActionListener *lis)
 Register a listener that should be called each time a RunStateAction is executed.
 
void unRegisterRunStateActionListener (nrt::RunStateActionListener *lis)
 Un-Register a listener that should be called each time a RunStateAction is executed.
 
void incrementActiveCallbackCount ()
 
void decrementActiveCallbackCount ()
 

Additional Inherited Members

- Static Public Member Functions inherited from nrt::Singleton< T >
static T & instance ()
 Get the global, unique instance of the class T. More...
 
- Protected Member Functions inherited from nrt::Singleton< T >
 Singleton ()
 Only classes that inherit from Singleton can construct it via its protected default constructor.
 
- Protected Member Functions inherited from nrt::BlackboardManager
void preInit ()
 Called before all sub-Components are init()ed.
 
void preStop ()
 Called before all sub-Components are stop()ed.
 
void onParamChange (nrt::blackboardmanager::nick const &param, std::string const &newval)
 
- Protected Attributes inherited from nrt::BlackboardManager
boost::shared_mutex itsRunStateMtx
 Protect init()/start()/etc.
 

Constructor & Destructor Documentation

nrt::Blackboard::Blackboard ( )

Constructor.

Because the Blackboard is a singleton, you should never try to contruct one by hand. Instead, just call

to get a reference to the Blackboard. The Blackboard will be constructed the first time it is accessed.

Member Function Documentation

void nrt::Blackboard::waitUntilUpdated ( ) const

Wait until all pending Blackboard federation transactions (if any) are complete.

Note that this just waits until a point in time where all in-progress transactions have completed (transactions are things like loading modules, creating ports, setting topics, etc). However, there is no guarantee that things will stay that way, i.e., as soon as the wait is over, a new transaction may start even before this function returns. Thus you should not assume that no transaction is in process when this function returns. This function is just to help ensure that some previous transaction that you may have initiated is complete before you initiate another transaction that is dependent on the first one. That is, you cannot guarantee that transactions from others (remote Blackboards, or even other threads acting on this local Blackboard) are cleared before initiating yours, but you can guarantee that your previous transactions are complete befofe initiating additional ones.

std::shared_ptr<nrt::blackboard::BlackboardFederationSummary const> nrt::Blackboard::getLatestBFS ( bool  waituntilupdated = false) const

Get the latest available BlackboardFederationSummary.

If you need to receive updates to that summary each time they become available, consider using a BlackboardFederationSummaryListener instead.

std::string nrt::Blackboard::getHelpMessage ( std::string const &  bbuid)

Get the help message from local or remote Blackboard.

This is the message that is returned by commadn-line option –help, here accessible on remote Blackboards as well. This message will list all available parameters of all modules and components on that Blackboard, along with the current parameter values and how to access these parameters (parameter descriptor)

std::string nrt::Blackboard::getModuleNamespace ( std::string const &  module)

Get the namespace of a module.

Note
Avoid using this function as it is not synchronization-safe, i.e., someone may change that namespace between the time you get it and you try to do anything with it. Mostly this is used internally to mark a macro-module as modified when it is moved in the GUI, in which case such synchronization errors may be tolerable.
void nrt::Blackboard::markNamespaceModified ( std::string const &  namespc)

Mark a namespace (macro-module) as modified, so that GUI will request user to save it.

Operations that modify the contents of a namespace call this automatically, so no need to call it in general, unless you need to explicitly mark a namespace for saving even though no module, parameter, connection, etc has been changed yet.

std::string nrt::Blackboard::createConnector ( nrt::ConnectorFlavor const  flavor,
std::string const &  msgtype,
std::string const &  rettype,
std::string const &  portname,
std::string const &  namespc,
nrt::ConnectorType const  type,
std::string const &  topic,
std::string const &  topicfilt 
)

Create a connector on the master Blackboard.

Returns
connector UID
void nrt::Blackboard::setMessagePosterTopic ( std::string const &  module,
std::string const &  portname,
std::string const &  topic 
)

Set the topic of a poster port of a module.

If the module is not local, request will be dispatched to the appropriate remote Blackboard

Examples:
tests/test-split-messages.C.

Referenced by main().

void nrt::Blackboard::splitMessagePoster ( std::string const &  module,
std::string const &  portname,
bool const  splitit = true 
)

Split/unsplit a poster port of a module.

If the module is not local, request will be dispatched to the appropriate remote Blackboard

void nrt::Blackboard::setMessageCheckerTopicFilter ( std::string const &  module,
std::string const &  portname,
std::string const &  topicfilter 
)

Set the topic filter of a checker.

If the module is not local, request will be dispatched to the appropriate remote Blackboard

void nrt::Blackboard::setMessageSubscriberTopicFilter ( std::string const &  module,
std::string const &  portname,
std::string const &  topicfilter 
)

Set the topic filter of a subscriber port of a module.

If the module is not local, request will be dispatched to the appropriate remote Blackboard

Examples:
tests/test-split-messages.C.

Referenced by main().

void nrt::Blackboard::splitMessageSubscriber ( std::string const &  module,
std::string const &  portname,
bool const  splitit = true 
)

Split/unsplit a subscriber port of a module.

If the module is not local, request will be dispatched to the appropriate remote Blackboard

void nrt::Blackboard::useModuleLibrary ( std::string const &  paths = "")

Instantiate a ModuleLibrary on the local Blackboard and parse all the manifests, load all the icons, etc.

Parameters
pathsColon-separated list of paths. If the list is empty, we will use the NRTMODULEPATH environment variable instead.
std::vector<ModuleDescription> nrt::Blackboard::getModuleLibraryContents ( std::string const &  bbuid)

Get a copy of the ModuleLibrary contents on a (local or remote) blackboard.

Simply returns an empty library if none was loaded by a call to useModuleLibrary

template<class Mod >
std::shared_ptr< Mod > nrt::Blackboard::addModule ( std::string const &  instanceName = "",
std::string const &  namespc = "" 
)
inline

Create a Module and register it with the local Blackboard.

The created module becomes a so-called top-level module, and it is owned directly by the Blackboard. One can later change the namespace of such top-level modules (whereas sub-modules inherit their namespace from their top-level parent).

Examples:
tests/test-Module.C, tests/test-ResultsSyntax.C, tests/test-split-messages.C, and tests/test-TransformManager.C.

Definition at line 454 of file BlackboardImpl.H.

References BBTHROW, and NRT_MODDEBUG.

Referenced by main().

std::pair<std::string , std::string > nrt::Blackboard::loadModule ( std::string const &  bbuid,
std::string const &  sopath,
std::string const &  logicalpath,
std::string const &  instance = "",
std::string const &  namespc = "",
bool  versioncheck = true 
)

Load a module from a shared library file, on the local Blackboard or on a remote one.

The module will be loaded, instantiated, added as a sub-component to the blackboard, placed in the desired namespace, and brought to the same initialized/started/running state as the creating Blackboard.

Parameters
bbuidthe Blackboard to load the module on
sopathfull absolute file path (including filename) of the .so file to load
logicalpaththe logical path of the module, as categ/subcat/.../classname. If this module is not categorized, provide at least classname in there. This classname is the name of the class in the .so file to instantiate to create the module
instancename to give to the instance at construction. If empty, a unique name of the form NRT_AUTO_# (with # replaced by a number) will be computed and returned.
namespcthe namespace to place the module in.
versioncheckif true, check that the module was compiled with the same NRT version as the loading Blackboard.
Returns
moduleuid (as a string) of the loaded module, and instance name.
std::pair<std::string , std::string > nrt::Blackboard::loadModuleLogical ( std::string const &  bbnick,
std::string const &  logicalpath,
std::string const &  instance = "",
std::string const &  namespc = "",
bool  versioncheck = true 
)

Load a module from a shared library file, on the local Blackboard or on a remote one.

The module will be loaded, instantiated, added as a sub-component to the blackboard, placed in the desired namespace, and brought to the same initialized/started/running state as the creating Blackboard.

Parameters
bbnickthe nick of the Blackboard that should load the module
logicalpathlogical file path of the module, format categ/subcat/.../classname
instancename to give to the instance at construction. If empty, a unique name of the form NRT_AUTO_# (with # replaced by a number) will be computed and returned.
namespcnamespace to place the module in.
versioncheckif true, check that the module was compiled with the same NRT version as the loading Blackboard.
Returns
moduleuid (as a string) of the loaded module, and instance name.
Note
This function is slightly slower than loadModule() as it requires a lookup from bbnick to bbuid, and from logicalpath to sopath.
std::string nrt::Blackboard::loadMacroModule ( std::string const &  logicalpath,
std::string const &  instancename,
std::string const &  namespc,
std::map< std::string, std::string > const &  bbnickremap 
)

Load a macro-module on the Blackboard master, by logical path.

The Blackboard master will load the macro-module (but this may involve instantiating modules on other Blackboards, which will be done automatically). A namespace is created for namespc/instancename and all the contents of the macro-module file are instantiated in that namespace.

Parameters
logicalpathlogical file path of the macro-module, format categ/subcat/.../macromodname
instancenamename to give to this macro-module. If empty, a unique name of the form NRT_AUTO_# (with # replaced by a number) will be computed and returned.
namespcnamespace to place all of the macro-module's contents into
bbnickremapremapping of bbnicks between those in the file and those that will be used for instantiation of the macro-module's actual modules
void nrt::Blackboard::saveMacroModule ( std::string const &  namespc,
nrt::ModuleManifest const &  manifest 
)

Save a macro-module.

The Blackboard master will do the saving, on its local disk.

template<class Mod >
void nrt::Blackboard::removeModule ( std::shared_ptr< Mod > &  module)

Remove a top-level Module from the local Blackboard, by shared_ptr.

Note
Beware that the passed shared_ptr is invalidated in the process. A warning is issued if the use_count is not down to zero after that (i.e., there are additional shared_ptr pointers to this Module floating around, which prevent it from actually being deleted.

Definition at line 530 of file BlackboardImpl.H.

References NRT_BBDEBUG, and NRT_WARNING.

template<class Mod >
std::shared_ptr< Mod > nrt::Blackboard::getModule ( std::string const &  instanceName) const
inline

Get a top-level Module by instance name.

This method does a dynamic_pointer_cast to Mod if it is not the default (nrt::Module). Throws if module is not found by instance name, or it is found but not of type Mod (if Mod is specified). Note that once you hold a shared_ptr to a Module, it is guaranteed that the module will not be destroyed until that shared_ptr is released. If the NRT system tries to destroy the module (e.g., someone calls removeModule()), the module will be un-initialized and its parent will be unset, so it will not be fully operational and will be actually deleted when the last shared_ptr to it runs out of scope.

Definition at line 503 of file BlackboardImpl.H.

References BBTHROW, and BBTHROWX.

void nrt::Blackboard::unloadModule ( std::string const &  module)

Unload a module previously loaded with loadModule() or added with addModule(), local or remote.

The module will be stopped, un-initialized, removed as sub-component, and destroyed. Only works for modules that have been loaded with loadModule().

nrt::ModuleManifest nrt::Blackboard::loadManifest ( std::string const &  bbuid,
std::string const &  unixroot,
std::string const &  logicalpath 
)

Load a Module or Macro-Module manifest.

If not found, a default manifest is returned, populated with default values from NRTAUTHOR and from the running NRT software and operating system.

std::vector<nrt::ParameterSummary> nrt::Blackboard::registerParamChangedListener ( nrt::ParamChangedListener lis)

Register a listener that should be called each time a parameter of a module on bbuid changes.

Note: make sure your listener is fully constructed and ready to process callbacks by the time you register it, as callbacks will start immediately.

void nrt::Blackboard::setParam ( std::string const &  bbuid,
std::string const &  descriptor,
std::string const &  value 
)

Set the value of a Parameter on a (possibly remote) Blackboard.

Throws just like Parameter::set() if the value is rejected by the parameter. This function is not const because Blackboard has parameters too, which could be modified using this function.

void nrt::Blackboard::setModuleParam ( std::string const &  module,
std::string const &  relativedescriptor,
std::string const &  value 
)

Set the value of a Parameter on a Module on a (possibly remote) Blackboard.

Throws just like Parameter::set() if the value is rejected by the parameter. This function is not const because Blackboard has parameters too, which could be modified using this function.

Parameters
moduleModule UID, the param should be in that module or one of its sub-components/sub-modules
relativedescriptorDescriptor relative to the module. If the param is in the module itself, that would just be the param name; if it is in a sub then strandard descriptor syntax applies, starting from the specified module.
valueValue to set the param to.
std::vector<nrt::ParameterSummary> nrt::Blackboard::getAllModuleParams ( std::string const &  module)

Get the current value of all of a Module's (and its sub-modules & sub-components) parameters.

Returns a snapshot of all current parameter values. Using a ParamChangedListener is usually the preferred way to keep up with changing parameters. This function is here to assist with saving the entire state of a Blackboard federation, e.g., when a GUI wants to export a whole network as a python script.

void nrt::Blackboard::registerBlackboardFederationSummaryListener ( nrt::BlackboardFederationSummaryListener lis)

Register a listener that should be called each time a BlackboardFederationSummary is available.

If available, the latest summary will be passed to the listener immediately upon registration.

void nrt::Blackboard::registerBlackboardGUIdataListener ( nrt::BlackboardGUIdataListener lis)

Register a listener that should be called each time some GUI data is updated.

If available, the latest data will be passed to the listener immediately upon registration.


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