Gazebo Transport

API Reference

12.2.1
Discovery< Pub > Class Template Reference

A discovery class that implements a distributed topic discovery protocol. It uses UDP multicast for sending/receiving messages and stores updated topic information. The discovery clients can request the discovery of a topic or the advertisement of a local topic. The discovery uses heartbeats to track the state of other peers in the network. The discovery clients can register callbacks to detect when new topics are discovered or topics are no longer available. More...

#include <gz/transport/Discovery.hh>

Public Member Functions

 Discovery (const std::string &_pUuid, const std::string &_ip, const int _port, const bool _verbose=false)
 Constructor. More...
 
virtual ~Discovery ()
 Destructor. More...
 
unsigned int ActivityInterval () const
 The discovery checks the validity of the topic information every 'activity interval' milliseconds. More...
 
bool Advertise (const Pub &_publisher)
 Advertise a new message. More...
 
void ConnectionsCb (const DiscoveryCallback< Pub > &_cb)
 Register a callback to receive discovery connection events. Each time a new topic is connected, the callback will be executed. This version uses a free function as callback. More...
 
void DisconnectionsCb (const DiscoveryCallback< Pub > &_cb)
 Register a callback to receive discovery disconnection events. Each time a topic is no longer active, the callback will be executed. This version uses a free function as callback. More...
 
bool Discover (const std::string &_topic) const
 Request discovery information about a topic. When using this method, the user might want to use SetConnectionsCb() and SetDisconnectionCb(), that registers callbacks that will be executed when the topic address is discovered or when the node providing the topic is disconnected. More...
 
unsigned int HeartbeatInterval () const
 Each node broadcasts periodic heartbeats to keep its topic information alive in other nodes. A heartbeat message is sent after 'heartbeat interval' milliseconds. More...
 
std::string HostAddr () const
 Get the IP address of this host. More...
 
const TopicStorage< Pub > & Info () const
 Get the discovery information. More...
 
void PrintCurrentState () const
 Print the current discovery state. More...
 
bool Publishers (const std::string &_topic, Addresses_M< Pub > &_publishers) const
 Get all the publishers' information known for a given topic. More...
 
void Register (const MessagePublisher &_pub) const
 Register a node from this process as a remote subscriber. More...
 
void RegistrationsCb (const DiscoveryCallback< Pub > &_cb)
 Register a callback to receive an event when a new remote node subscribes to a topic within this process. More...
 
void SetActivityInterval (const unsigned int _ms)
 Set the activity interval. More...
 
void SetHeartbeatInterval (const unsigned int _ms)
 Set the heartbeat interval. More...
 
void SetSilenceInterval (const unsigned int _ms)
 Set the maximum silence interval. More...
 
unsigned int SilenceInterval () const
 Get the maximum time allowed without receiving any discovery information from a node before canceling its entries. More...
 
void Start ()
 Start the discovery service. You probably want to register the callbacks for receiving discovery notifications before starting the service. More...
 
void TopicList (std::vector< std::string > &_topics) const
 Get the list of topics currently advertised in the network. More...
 
bool Unadvertise (const std::string &_topic, const std::string &_nUuid)
 Unadvertise a new message. Broadcast a discovery message that will cancel all the discovery information for the topic advertised by a specific node. More...
 
void Unregister (const MessagePublisher &_pub) const
 Unregister a node from this process as a remote subscriber. More...
 
void UnregistrationsCb (const DiscoveryCallback< Pub > &_cb)
 Register a callback to receive an event when a remote node unsubscribes to a topic within this process. More...
 
void WaitForInit () const
 Check if ready/initialized. If not, then wait on the initializedCv condition variable. More...
 

Protected Attributes

std::map< std::string, Timestampactivity
 Activity information. Every time there is a message from a remote node, its activity information is updated. If we do not hear from a node in a while, its entries in 'info' will be invalided. The key is the process uuid. More...
 

Detailed Description

template<typename Pub>
class gz::transport::Discovery< Pub >

A discovery class that implements a distributed topic discovery protocol. It uses UDP multicast for sending/receiving messages and stores updated topic information. The discovery clients can request the discovery of a topic or the advertisement of a local topic. The discovery uses heartbeats to track the state of other peers in the network. The discovery clients can register callbacks to detect when new topics are discovered or topics are no longer available.

Constructor & Destructor Documentation

◆ Discovery()

Discovery ( const std::string _pUuid,
const std::string _ip,
const int  _port,
const bool  _verbose = false 
)
inline

Constructor.

Parameters
[in]_pUuidThis discovery instance will run inside a transport process. This parameter is the transport process' UUID.
[in]_ipIP address used for discovery traffic.
[in]_portUDP port used for discovery traffic.
[in]_verbosetrue for enabling verbose mode.

References vector< T >::at(), string::c_str(), gz::transport::determineInterfaces(), string::empty(), std::endl(), gz::transport::env(), Discovery< Pub >::PrintCurrentState(), and gz::transport::split().

◆ ~Discovery()

virtual ~Discovery ( )
inlinevirtual

Member Function Documentation

◆ ActivityInterval()

unsigned int ActivityInterval ( ) const
inline

The discovery checks the validity of the topic information every 'activity interval' milliseconds.

See also
SetActivityInterval.
Returns
The value in milliseconds.

◆ Advertise()

bool Advertise ( const Pub &  _publisher)
inline

Advertise a new message.

Parameters
[in]_publisherPublisher's information to advertise.
Returns
True if the method succeed or false otherwise (e.g. if the discovery has not been started).

References TopicStorage< T >::AddPublisher(), gz::transport::ALL, and gz::transport::PROCESS.

◆ ConnectionsCb()

void ConnectionsCb ( const DiscoveryCallback< Pub > &  _cb)
inline

Register a callback to receive discovery connection events. Each time a new topic is connected, the callback will be executed. This version uses a free function as callback.

Parameters
[in]_cbFunction callback.

◆ DisconnectionsCb()

void DisconnectionsCb ( const DiscoveryCallback< Pub > &  _cb)
inline

Register a callback to receive discovery disconnection events. Each time a topic is no longer active, the callback will be executed. This version uses a free function as callback.

Parameters
[in]_cbFunction callback.

◆ Discover()

bool Discover ( const std::string _topic) const
inline

Request discovery information about a topic. When using this method, the user might want to use SetConnectionsCb() and SetDisconnectionCb(), that registers callbacks that will be executed when the topic address is discovered or when the node providing the topic is disconnected.

See also
SetConnectionsCb.
SetDisconnectionsCb.
Parameters
[in]_topicTopic name requested.
Returns
True if the method succeeded or false otherwise (e.g. if the discovery has not been started).

References gz::transport::ALL, and TopicStorage< T >::Publishers().

◆ HeartbeatInterval()

unsigned int HeartbeatInterval ( ) const
inline

Each node broadcasts periodic heartbeats to keep its topic information alive in other nodes. A heartbeat message is sent after 'heartbeat interval' milliseconds.

See also
SetHeartbeatInterval.
Returns
The value in milliseconds.

◆ HostAddr()

std::string HostAddr ( ) const
inline

Get the IP address of this host.

Returns
A string with this host's IP address.

◆ Info()

const TopicStorage<Pub>& Info ( ) const
inline

Get the discovery information.

Returns
Reference to the discovery information object.

◆ PrintCurrentState()

void PrintCurrentState ( ) const
inline

◆ Publishers()

bool Publishers ( const std::string _topic,
Addresses_M< Pub > &  _publishers 
) const
inline

Get all the publishers' information known for a given topic.

Parameters
[in]_topicTopic name.
[out]_publishersPublishers requested.
Returns
True if the topic is found and there is at least one publisher

References TopicStorage< T >::Publishers().

◆ Register()

void Register ( const MessagePublisher _pub) const
inline

Register a node from this process as a remote subscriber.

Parameters
[in]_pubContains information about the subscriber.

References gz::transport::ALL.

◆ RegistrationsCb()

void RegistrationsCb ( const DiscoveryCallback< Pub > &  _cb)
inline

Register a callback to receive an event when a new remote node subscribes to a topic within this process.

Parameters
[in]_cbFunction callback.

◆ SetActivityInterval()

void SetActivityInterval ( const unsigned int  _ms)
inline

Set the activity interval.

See also
ActivityInterval.
Parameters
[in]_msNew value in milliseconds.

◆ SetHeartbeatInterval()

void SetHeartbeatInterval ( const unsigned int  _ms)
inline

Set the heartbeat interval.

See also
HeartbeatInterval.
Parameters
[in]_msNew value in milliseconds.

◆ SetSilenceInterval()

void SetSilenceInterval ( const unsigned int  _ms)
inline

Set the maximum silence interval.

See also
SilenceInterval.
Parameters
[in]_msNew value in milliseconds.

◆ SilenceInterval()

unsigned int SilenceInterval ( ) const
inline

Get the maximum time allowed without receiving any discovery information from a node before canceling its entries.

See also
SetSilenceInterval.
Returns
The value in milliseconds.

◆ Start()

void Start ( )
inline

Start the discovery service. You probably want to register the callbacks for receiving discovery notifications before starting the service.

References steady_clock::now().

◆ TopicList()

void TopicList ( std::vector< std::string > &  _topics) const
inline

Get the list of topics currently advertised in the network.

Parameters
[out]_topicsList of advertised topics.

References TopicStorage< T >::TopicList(), and Discovery< Pub >::WaitForInit().

◆ Unadvertise()

bool Unadvertise ( const std::string _topic,
const std::string _nUuid 
)
inline

Unadvertise a new message. Broadcast a discovery message that will cancel all the discovery information for the topic advertised by a specific node.

Parameters
[in]_topicTopic name to be unadvertised.
[in]_nUuidNode UUID.
Returns
True if the method succeeded or false otherwise (e.g. if the discovery has not been started).

References gz::transport::ALL, TopicStorage< T >::DelPublisherByNode(), gz::transport::PROCESS, and TopicStorage< T >::Publisher().

◆ Unregister()

void Unregister ( const MessagePublisher _pub) const
inline

Unregister a node from this process as a remote subscriber.

Parameters
[in]_pubContains information about the subscriber.

References gz::transport::ALL.

◆ UnregistrationsCb()

void UnregistrationsCb ( const DiscoveryCallback< Pub > &  _cb)
inline

Register a callback to receive an event when a remote node unsubscribes to a topic within this process.

Parameters
[in]_cbFunction callback.

◆ WaitForInit()

void WaitForInit ( ) const
inline

Check if ready/initialized. If not, then wait on the initializedCv condition variable.

References condition_variable::wait().

Referenced by Discovery< Pub >::TopicList().

Member Data Documentation

◆ activity

std::map<std::string, Timestamp> activity
protected

Activity information. Every time there is a message from a remote node, its activity information is updated. If we do not hear from a node in a while, its entries in 'info' will be invalided. The key is the process uuid.

Referenced by Discovery< Pub >::PrintCurrentState().


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