iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
nrt::MessagePosterCore< Posting > Class Template Reference

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

template<class Posting>
class nrt::MessagePosterCore< Posting >

Module objects which derive from MessagePoster will be allowed to post Message objects.

Definition at line 57 of file Blackboard.H.

Inheritance diagram for nrt::MessagePosterCore< Posting >:
nrt::ModuleBase nrt::MessagePosterCoreBase

Public Types

typedef Posting PostingType
 Our underlying posting type (used by Connectors)
 
typedef MessagePosterResults
< Posting > 
PostResultsType
 Type for the results of a post.
 

Public Member Functions

 MessagePosterCore ()
 Constructor, will register us with the Blackboard.
 
virtual ~MessagePosterCore ()
 Destructor, will un-register us with the Blackboard.
 
virtual void createSubPosters ()
 Create our split sub-ports.
 
virtual void deleteSubPosters ()
 Delete our split sub-ports.
 
virtual bool isSplit () const
 Return true if we currently have split-sub-posters.
 
template<typename... Args>
Posting::MsgUptr make_message (Args &&...args) const
 Allocate a message and return a unique_ptr to it, to be used by post() More...
 
PostResultsType post (std::unique_ptr< typename Posting::MsgType > &m) const
 Post a Message to the blackboard. More...
 
PostResultsType post (std::unique_ptr< typename Posting::MsgType > &&m) const
 Post a Message to the blackboard, move semantics. More...
 
PostResultsType repost (std::shared_ptr< typename Posting::MsgType const > &m) const
 Re-post a received message. More...
 
void expunge () const
 Expunge from the Blackboard any previously posted message. More...
 
std::string make_connector (std::string const &name, std::string const &namespc, nrt::ConnectorType const type, std::string const &topicfilter, std::string const &topic) const
 Create a connector for this port's Posting type on the master Blackboard. More...
 
- 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.
 
- Public Member Functions inherited from nrt::MessagePosterCoreBase
virtual ~MessagePosterCoreBase ()
 Virtual destructor for safe inheritance.
 
void setTopic (std::string const &topic_)
 Set topic of a MessagePoster port. More...
 

Friends

template<class... >
class nrt::MessagePoster
 
class nrt::Module
 
class nrt::BlackboardManager
 
template<class T >
class nrt::ParameterCore
 
class nrt::MessageBase
 
template<class T >
class nrt::SplitMessagePoster
 

Additional Inherited Members

- Protected Attributes inherited from nrt::ModuleBase
boost::shared_mutex itsNamespaceMtx
 
std::string namespc
 
std::string logicalpath
 
- Protected Attributes inherited from nrt::MessagePosterCoreBase
std::string msgtype
 Type of Message we post.
 
std::string rettype
 Type of Message we expect back from subscribers.
 
std::string module
 Module which we belong to.
 
std::string portname
 String name for our Posting port class.
 
std::string description
 String human description for our Posting.
 
std::string topic
 Topic into which we post.
 
int sequence
 Poster sequence number within module used for ordering of ports in the GUI.
 
bool splittable
 Can this port be split into sub-ports?
 
std::map< std::string,
RemotePostData > 
remotePostData
 Map of remote post handlers that get triggered when we post a message, one per remote blackboard.
 
std::map< std::string,
RemotePostData > 
remotePostDataAny
 Map of remote post handlers, one per remote blackboard that has subscribers for nrt::AnyMessage version.
 
nrt::blackboard::msgkey messagekey
 Pre-computed key to our Blackboard's internal repository of messages.
 
boost::shared_mutex mtx
 

Member Function Documentation

template<class Posting >
template<typename... Args>
Posting::MsgUptr nrt::MessagePosterCore< Posting >::make_message ( Args &&...  args) const
inline

Allocate a message and return a unique_ptr to it, to be used by post()

All given args are forwarded to the message constructor.

Definition at line 341 of file ModulePortImpl.H.

template<class Posting>
nrt::MessagePosterCore< Posting >::PostResultsType nrt::MessagePosterCore< Posting >::post ( std::unique_ptr< typename Posting::MsgType > &  m) const
inline

Post a Message to the blackboard.

The post() method sends the given message to the Blackboard Federation and triggers any local and remote callbacks, run in in parallel threads, of any Modules who have subscribed to the matching message/return types, who are in the same namespace as the poster, and whose Topic Filter matches the Topic of the poster.

Because post() takes a unique_ptr to the message, it has very low overhead in transmitting the message to local subscribers (no copy of message data invoved). Users should therefore feel free to include large data structures (such as an Image) in their messages. However, post() can also transparently trigger callbacks on remote machines, which is more costly as both the posted Message and the resulting return Message must be serialized and transported over the network. Thus, users must be careful to pay attention to bandwidth limitations when constructing distributed systems. Proper use of message/return types, namespaces, and topics can help maximize throughput and minimize network congestion.

post() returns quickly, i.e., almost immediately as the only thing it does is to dispatch the message to a pre-computed list of callbacks, if any, where each callback runs in a parallel thread, and possibly it also serializes the message once for dispatch to a pre-computed list of remote callbacks, if any. Callbacks are executed in parallel threads and may each take variable amount of time to complete. The futures in MessagePosterResults allow you to check for completion of each callback, see the documentation of MessagePosterResults.

Note that an exception will be thrown if you try to post() from a MessagePoster that is not attached to a Module, or if you try to post() while the system in not in the running() state. Have a look at Component.H and Manager.H for some explanations about the running() state.

Parameters
msgA unique pointer to the message that will be posted. Note that once you post the message, the pointer will be invalidated (will point to nullptr), as inside post() the Blackboard will take ownership of the pointee and will std::move it out of the unique_ptr. That is, your message is gone as far as your access to it. This is by design, to discourage you from modifying the message after it has been posted (and while it may be serializing or transmitting over the network).
Returns
MessagePosterResults<Posting>, see the MessagePosterResults documentation for usage. Note that if you just ignore the results (i.e., just write Posting::post(msg) without grabbing the results), this is equivalent to doing a waitgetall() on those results.

Definition at line 349 of file ModulePortImpl.H.

template<class Posting>
nrt::MessagePosterCore< Posting >::PostResultsType nrt::MessagePosterCore< Posting >::post ( std::unique_ptr< typename Posting::MsgType > &&  m) const
inline

Post a Message to the blackboard, move semantics.

This version of post() behavies just like the other one except for the move semantics. This allows posting of unique_ptr to messages that are returned by functions. For example:

MyPoster::post(MyPoster::make_message(some_data));

Definition at line 362 of file ModulePortImpl.H.

template<class Posting>
nrt::MessagePosterCore< Posting >::PostResultsType nrt::MessagePosterCore< Posting >::repost ( std::shared_ptr< typename Posting::MsgType const > &  m) const
inline

Re-post a received message.

This should only used by dispatcher or queueing modules that wish to re-post on a different port messages received on some port. Functionality is identical to post() except that we here accept a shared_ptr<Msg const> instead of a unique_ptr<Msg const>. To discourage modification of the message in the same spirit as the original use of unique_ptr, repost() will invalidate your shared_ptr (will internally swap it for a shared_ptr to a null message).

When a message is re-posted, no deep copy of the message data occurs, but all the internal bookkeeping makes it look as if it was a brand new message posted in the normal way (e.g., with respect to checkers, subscribers, etc). This is elegant and efficient, but be sure to respect the constness of the "Posting::MsgType const" semantics of your shared_ptr and to not modify the message contents. Here are two simple scenarios: a module receives messages on a subscriber port, queues them up, possibly re-orders them, etc and at some point wants to post them. Using repost() is appropriate in this case. Now if the module also wants to, say, update some of the message contents, such as setting an ID or an order field based on the re-ordering that has occurred, then repost() is not appropriate, you should instead make a deep copy of the message (e.g., construct a new one from the old one using the copy constructor), then modify that copy, and then do a regular post() of the modified copy.

Definition at line 375 of file ModulePortImpl.H.

template<class Posting >
void nrt::MessagePosterCore< Posting >::expunge ( ) const
inline

Expunge from the Blackboard any previously posted message.

This clears from the Blackboard any previously posted message from that poster. Note that the message is deleted even if the poster's topic has changed. This is useful to reclaim some memory on the Blackboard if a large message is known to not be needed in the future. But it is not necessary in normal operation as only the most recent message for each poster is stored on the Blackboard, so memory usage does not grow uncontrollably. Another interesting use of expunge is to make sure that some blocking check() will perform as desired.

Definition at line 534 of file ModulePortImpl.H.

References nrt::Singleton< T >::instance().

template<class Posting >
std::string nrt::MessagePosterCore< Posting >::make_connector ( std::string const &  name,
std::string const &  namespc,
nrt::ConnectorType const  type,
std::string const &  topicfilter,
std::string const &  topic 
) const
inline

Create a connector for this port's Posting type on the master Blackboard.

Returns
The connector uid. This is the only way to "access" the connector, as it lives hidden deep inside the master Blackboard. The Blackboard class exposes functions that allow one to set connector topics, etc using the connector uid to address a particular connector.

Beware of the order of the topic and topicfilter arguments as they differ between the poster checker and subscriber version of make_connector. Think of the first one as directly connected to the physical port, and the other one as the other end of the connector.

Definition at line 545 of file ModulePortImpl.H.

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


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