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

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

Base class for a Module.

User modules should derive from nrt::Module and from any of nrt::MessagePoster, nrt::MessageChecker, nrt::MessageSubscriber depending on what they post(), check() for, or subscribe to.

Be sure to issue a:

NRT_REGISTER_MODULE(ModuleClassName);

in your .C file after you have defined a new Module, to make sure that your module, once compiled as a shared object file, can be loaded at runtime (e.g., by the nrtLoader).

See test-Module.C for examples.

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

Definition at line 179 of file Module.H.

Inheritance diagram for nrt::Module:
nrt::Component nrt::ModuleBase nrt::ParameterRegistry MyModule MyModule

Public Member Functions

 Module (std::string const &instanceid="")
 Constructor.
 
virtual ~Module ()
 Virtual destructor for safe inheritance.
 
void setNamespace (std::string const &namespac)
 Set the module's namespace. More...
 
void changeNamespace (std::string const &oldnamespc, std::string const &newnamespc)
 If old namespace matches ours, then change ours to new namespace; otherwise, do nothing. More...
 
template<class Mod >
std::shared_ptr< Mod > addSubModule (std::string const &instanceName="")
 Create a message port for a Parameter of this module (or sub-Component or sub-Module) More...
 
template<class Mod >
void removeSubModule (std::shared_ptr< Mod > &module)
 Remove a sub-Module from this Module, by shared_ptr. More...
 
void removeSubModule (std::string const &instanceName)
 Remove a sub-Module from this Module, by instance name.
 
template<class Mod = nrt::Module>
std::shared_ptr< Mod > getSubModule (std::string const &instanceName) const
 Get a sub-module by instance name. More...
 
- 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.
 
- Public Member Functions inherited from nrt::ModuleBase
 ModuleBase ()
 Constructor.
 
virtual ~ModuleBase ()
 Virtual destructor for safe inheritance.
 
ModuleUID const & uid () const
 Get our unique ID which will be used to track Module objects in distributed systems.
 
std::string getNamespace () const
 Get the module's namespace. More...
 
void setLogicalPath (std::string const &lp)
 Set the logical path for this module, as categ/subcat/.../classname. More...
 
std::string getLogicalPath () const
 Get the logical path for this module, as categ/subcat/.../classname.
 

Protected Member Functions

virtual void notifyParamChanged (nrt::ParameterState const state, ParameterBase const *const param) const
 Notification when a param is changed.
 
- Protected Member Functions inherited from nrt::Component
virtual void preInit ()
 Called before all sub-Components are init()ed.
 
virtual void postInit ()
 Called after all sub-Components are init()ed.
 
virtual void preStart ()
 Called before all sub-Components are start()ed.
 
virtual void postStart ()
 Called after all sub-Components are start()ed.
 
virtual void run ()
 Called in its own thread after all Components have been start()ed. More...
 
virtual void preStop ()
 Called before all sub-Components are stop()ed.
 
virtual void postStop ()
 Called after all sub-Components are stop()ed.
 
virtual void preUninit ()
 Called before all sub-Components are uninit()ed.
 
virtual void postUninit ()
 Called after all sub-Components are uninit()ed.
 
void populateHelpMessage (std::string const &cname, std::unordered_map< std::string, std::unordered_map< std::string, std::vector< std::pair< std::string, std::string > > > > &helplist) const
 

Additional Inherited Members

- Protected Attributes inherited from nrt::Component
boost::shared_mutex itsMtx
 Mutex used to protect our internals other than subcomponents and parameters.
 
std::vector< std::shared_ptr
< Component > > 
itsSubComponents
 
boost::shared_mutex itsSubMtx
 
Component *const nrt_component_this
 
- Protected Attributes inherited from nrt::ModuleBase
boost::shared_mutex itsNamespaceMtx
 
std::string namespc
 
std::string logicalpath
 

Member Function Documentation

void nrt::Module::setNamespace ( std::string const &  namespac)

Set the module's namespace.

The module must be a top-level module, i.e., its parent is the Blackboard), otherwise throws. This call propagates to all sub-modules recursively, enforcing that all sub-modules are in the same namespace as their top-level parent module.

Examples:
tests/test-Module.C.

Referenced by main().

void nrt::Module::changeNamespace ( std::string const &  oldnamespc,
std::string const &  newnamespc 
)

If old namespace matches ours, then change ours to new namespace; otherwise, do nothing.

Note that partial matches are allowed at the start of the names, which allows renaming a namespace. You can only call changeNamespace() on a top-level module, i.e., its parent is the Blackboard), otherwise throws. This call propagates to all sub-modules recursively, enforcing that all sub-modules are in the same namespace as their top-level parent module.

template<class Mod >
std::shared_ptr< Mod > nrt::Module::addSubModule ( std::string const &  instanceName = "")
inline

Create a message port for a Parameter of this module (or sub-Component or sub-Module)

Note
You must be at least initialized() for this to work, because you need to be able to post(), check(), etc by the time you create ports for your parameter.
When creating a ModuleParamPort::Poster, this method will immediately post the current Parameter value. Delete a message port for a Parameter of this module (or sub-Component or sub-Module)

Note that we will automatically delete the ports during uninit() because they cannot be allowed to exist and post(), check(), etc if we are not initialized. Set the topic of a Parameter Poster

Will throw if the poster is not found, eg, it has not been created. Requires initialized() or more.

Note
After setting the topic, this method will immediately post the current Parameter value.
Exceptions
nrt::exception::ParameterExceptionif no Parameter matches the given descriptor or if one is found but no poster port has been created for it.
Returns
list of fully-unrolled (no '*') descriptors of the parameters that were matched and set. The list is guaranteed to have at least one element since we throw if no matching parameter is found. Set the topic filter of a Parameter Checker

Will throw if the checker is not found, eg, it has not been created. Requires initialized() or more.

Exceptions
nrt::exception::ParameterExceptionif no Parameter matches the given descriptor or if one is found but no poster port has been created for it.
Returns
list of fully-unrolled (no '*') descriptors of the parameters that were matched and set. The list is guaranteed to have at least one element since we throw if no matching parameter is found. Set the topic filter of a Parameter Subscriber

Will throw if the subscriber is not found, eg, it has not been created. Requires initialized() or more.

Exceptions
nrt::exception::ParameterExceptionif no Parameter matches the given descriptor or if one is found but no poster port has been created for it.
Returns
list of fully-unrolled (no '*') descriptors of the parameters that were matched and set. The list is guaranteed to have at least one element since we throw if no matching parameter is found. Pseudo-constructor: construct and add another Module as a submodule of this one

A child module of type Mod (which must derive from nrt::Module) will be created and added as a sub-module of this. The child logically "belongs" to this module, and will automatically be deleted when the parent module is deleted. In addition to construction, adding a submodule has the following effects:

  • subMod will be start()ed after this Module's preStart() but before this Module's postStart(), and idem for init().
  • subMod will be stop()ed after this Module's preStop() but before this Module's postStop(), idem for uninit().
  • When setting parameters, the sub-Module can be referenced as a child of this module. For instance, if we have a ModuleParent which has ModuleChild as a sub-Module, and ModuleChild has parameter named coolChildParam, then that parameter could be specified on the command line by

    --ModuleParent:ModuleChild:coolChildParam="whatever"

    This method is essentially the same as nrt::Component::addSubComponent() except that it enforces that Mod derives from nrt::Module and it registers the Module with the local Blackboard, sets its namespace, and updates the Blackboard Federation.

Definition at line 41 of file ModuleImpl.H.

References nrt::ModuleBase::getNamespace(), nrt::Singleton< T >::instance(), NRT_FATAL, and NRT_MODDEBUG.

template<class Mod >
void nrt::Module::removeSubModule ( std::shared_ptr< Mod > &  module)

Remove a sub-Module from this Module, 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 108 of file ModuleImpl.H.

References nrt::Singleton< T >::instance(), NRT_MODDEBUG, and NRT_WARNING.

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

Get a sub-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 removeSubModule()), 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 86 of file ModuleImpl.H.

References NRT_FATAL.


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