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.

virtual	~Discovery ()
	Destructor.

unsigned int	ActivityInterval () const
	The discovery checks the validity of the topic information every 'activity interval' milliseconds.

void	AddRelayAddress (const std::string &_ip)
	Register a new relay address.

bool	Advertise (const Pub &_publisher)
	Advertise a new message.

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.

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.

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.

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.

std::string	HostAddr () const
	Get the IP address of this host.

const TopicStorage< Pub > &	Info () const
	Get the discovery information.

void	PrintCurrentState () const
	Print the current discovery state.

bool	Publishers (const std::string &_topic, Addresses_M< Pub > &_publishers) const
	Get all the publishers' information known for a given topic.

void	Register (const MessagePublisher &_pub) const
	Register a node from this process as a remote subscriber.

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.

std::vector< std::string >	RelayAddresses () const

bool	RemoteSubscribers (const std::string &_topic, Addresses_M< Pub > &_subscribers) const
	Get all the subscribers' information known for a given topic.

void	SendSubscribersRep (const MessagePublisher &_pub) const
	Send the response to a SUBSCRIBERS_REQ message.

void	SetActivityInterval (const unsigned int _ms)
	Set the activity interval.

void	SetHeartbeatInterval (const unsigned int _ms)
	Set the heartbeat interval.

void	SetSilenceInterval (const unsigned int _ms)
	Set the maximum silence interval.

unsigned int	SilenceInterval () const
	Get the maximum time allowed without receiving any discovery information from a node before canceling its entries.

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

void	SubscribersCb (const std::function< void()> &_cb)
	Register a callback to receive an event when a node requests the list of remote subscribers.

void	TopicList (std::vector< std::string > &_topics)
	Get the list of topics currently advertised and subscribed in the network.

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.

void	Unregister (const MessagePublisher &_pub) const
	Unregister a node from this process as a remote subscriber.

void	UnregistrationsCb (const DiscoveryCallback< Pub > &_cb)
	Register a callback to receive an event when a remote node unsubscribes to a topic within this process.

void	WaitForInit () const
	Check if ready/initialized. If not, then wait on the initializedCv condition variable.

Protected Attributes
std::map< std::string, Timestamp >	activity
	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.

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()

template<typename Pub >

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

inline

Constructor.

Parameters

[in]	_pUuid	This discovery instance will run inside a transport process. This parameter is the transport process' UUID.
[in]	_ip	IP address used for discovery traffic.
[in]	_port	UDP port used for discovery traffic.
[in]	_verbose	true for enabling verbose mode.

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

◆ ~Discovery()

template<typename Pub >

virtual ~Discovery ( )

inlinevirtual

Destructor.

References gz::transport::ALL, thread::join(), thread::joinable(), mutex::lock(), and mutex::unlock().

Member Function Documentation

◆ ActivityInterval()

template<typename Pub >

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.

◆ AddRelayAddress()

template<typename Pub >

void AddRelayAddress ( const std::string & _ip )

inline

Register a new relay address.

Parameters

[in] _ip New IP address.

References string::c_str(), and vector< T >::push_back().

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

◆ Advertise()

template<typename Pub >

bool Advertise ( const Pub & _publisher )

inline

Advertise a new message.

Parameters

[in] _publisher Publisher'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()

template<typename Pub >

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] _cb Function callback.

◆ DisconnectionsCb()

template<typename Pub >

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] _cb Function callback.

◆ Discover()

template<typename Pub >

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] _topic Topic 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()

template<typename Pub >

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()

template<typename Pub >

std::string HostAddr ( ) const

inline

Get the IP address of this host.

Returns: A string with this host's IP address.

◆ Info()

template<typename Pub >

const TopicStorage< Pub > & Info ( ) const

inline

Get the discovery information.

Returns: Reference to the discovery information object.

◆ PrintCurrentState()

template<typename Pub >

void PrintCurrentState ( ) const

inline

Print the current discovery state.

References Discovery< Pub >::activity, std::boolalpha(), std::chrono::duration_cast(), map< K, T >::empty(), std::endl(), steady_clock::now(), and TopicStorage< T >::Print().

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

◆ Publishers()

template<typename Pub >

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

inline

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

Parameters

[in]	_topic	Topic name.
[out]	_publishers	Publishers requested.

Returns: True if the topic is found and there is at least one publisher

References TopicStorage< T >::Publishers().

◆ Register()

template<typename Pub >

void Register ( const MessagePublisher & _pub ) const

inline

Register a node from this process as a remote subscriber.

Parameters

[in] _pub Contains information about the subscriber.

References gz::transport::ALL.

◆ RegistrationsCb()

template<typename Pub >

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] _cb Function callback.

◆ RelayAddresses()

template<typename Pub >

std::vector< std::string > RelayAddresses ( ) const

inline

References vector< T >::push_back().

◆ RemoteSubscribers()

template<typename Pub >

bool RemoteSubscribers	(	const std::string &	_topic,
		Addresses_M< Pub > &	_subscribers
	)		const

inline

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

Parameters

[in]	_topic	Topic name.
[out]	_subscribers	All remote subscribers for this topic.

Returns: True if the topic is found and there is at least one publisher

References TopicStorage< T >::Publishers().

◆ SendSubscribersRep()

template<typename Pub >

void SendSubscribersRep ( const MessagePublisher & _pub ) const

inline

Send the response to a SUBSCRIBERS_REQ message.

Parameters

[in] _pub Information to send.

References gz::transport::ALL.

◆ SetActivityInterval()

template<typename Pub >

void SetActivityInterval ( const unsigned int _ms )

inline

Set the activity interval.

See also: ActivityInterval.

Parameters

[in] _ms New value in milliseconds.

◆ SetHeartbeatInterval()

template<typename Pub >

void SetHeartbeatInterval ( const unsigned int _ms )

inline

Set the heartbeat interval.

See also: HeartbeatInterval.

Parameters

[in] _ms New value in milliseconds.

◆ SetSilenceInterval()

template<typename Pub >

void SetSilenceInterval ( const unsigned int _ms )

inline

Set the maximum silence interval.

See also: SilenceInterval.

Parameters

[in] _ms New value in milliseconds.

◆ SilenceInterval()

template<typename Pub >

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()

template<typename Pub >

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().

◆ SubscribersCb()

template<typename Pub >

void SubscribersCb ( const std::function< void()> & _cb )

inline

Register a callback to receive an event when a node requests the list of remote subscribers.

Parameters

[in] _cb Function callback.

◆ TopicList()

template<typename Pub >

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

inline

Get the list of topics currently advertised and subscribed in the network.

Parameters

[out] _topics List of advertised topics.

References gz::transport::ALL, vector< T >::begin(), TopicStorage< T >::Clear(), vector< T >::end(), std::find(), vector< T >::push_back(), TopicStorage< T >::TopicList(), and Discovery< Pub >::WaitForInit().

◆ Unadvertise()

template<typename Pub >

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]	_topic	Topic name to be unadvertised.
[in]	_nUuid	Node 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()

template<typename Pub >

void Unregister ( const MessagePublisher & _pub ) const

inline

Unregister a node from this process as a remote subscriber.

Parameters

[in] _pub Contains information about the subscriber.

References gz::transport::ALL.

◆ UnregistrationsCb()

template<typename Pub >

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] _cb Function callback.

◆ WaitForInit()

template<typename Pub >

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

template<typename Pub >

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:

Discovery.hh

Gazebo Transport

API Reference

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Discovery()

◆ ~Discovery()

Member Function Documentation

◆ ActivityInterval()

◆ AddRelayAddress()

◆ Advertise()

◆ ConnectionsCb()

◆ DisconnectionsCb()

◆ Discover()

◆ HeartbeatInterval()

◆ HostAddr()

◆ Info()

◆ PrintCurrentState()

◆ Publishers()

◆ Register()

◆ RegistrationsCb()

◆ RelayAddresses()

◆ RemoteSubscribers()

◆ SendSubscribersRep()

◆ SetActivityInterval()

◆ SetHeartbeatInterval()

◆ SetSilenceInterval()

◆ SilenceInterval()

◆ Start()

◆ SubscribersCb()

◆ TopicList()

◆ Unadvertise()

◆ Unregister()

◆ UnregistrationsCb()

◆ WaitForInit()

Member Data Documentation

◆ activity