Public Member Functions | Protected Attributes | List of all members
ignition::transport::Discovery Class Reference

A discovery class that implements a distributed topic discovery protocol. More...

#include <ignition/transport/Discovery.hh>

Public Member Functions

 Discovery (const std::string &_pUuid, 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...
 
unsigned int AdvertiseInterval () const
 While a topic is being advertised by a node, a beacon is sent periodically every 'advertise interval' milliseconds. More...
 
bool AdvertiseMsg (const MessagePublisher &_publisher)
 Advertise a new message. More...
 
bool AdvertiseSrv (const ServicePublisher &_publisher)
 Advertise a new service. More...
 
void ConnectionsCb (const MsgDiscoveryCallback &_cb)
 Register a callback to receive discovery connection events. More...
 
template<typename C >
void ConnectionsCb (void(C::*_cb)(const MessagePublisher &_pub), C *_obj)
 Register a callback to receive discovery connection events. More...
 
void ConnectionsSrvCb (const SrvDiscoveryCallback &_cb)
 Register a callback to receive discovery connection events for services. More...
 
template<typename C >
void ConnectionsSrvCb (void(C::*_cb)(const ServicePublisher &_pub), C *_obj)
 Register a callback to receive discovery connection events for services. More...
 
void DisconnectionsCb (const transport::MsgDiscoveryCallback &_cb)
 Register a callback to receive discovery disconnection events. More...
 
template<typename C >
void DisconnectionsCb (void(C::*_cb)(const MessagePublisher &_pub), C *_obj)
 Register a callback to receive discovery disconnection events. More...
 
void DisconnectionsSrvCb (const transport::SrvDiscoveryCallback &_cb)
 Register a callback to receive discovery disconnection events for services. More...
 
template<typename C >
void DisconnectionsSrvCb (void(C::*_cb)(const ServicePublisher &_pub), C *_obj)
 Register a callback to receive discovery disconnection events. More...
 
bool DiscoverMsg (const std::string &_topic)
 Request discovery information about a topic. More...
 
bool DiscoverSrv (const std::string &_topic)
 Request discovery information about a service. More...
 
const TopicStorage< MessagePublisher > & DiscoveryMsgInfo () const
 Get the discovery information object (messages). More...
 
const TopicStorage< ServicePublisher > & DiscoverySrvInfo () const
 Get the discovery information object (services). More...
 
unsigned int HeartbeatInterval () const
 Each node broadcasts periodic heartbeats to keep its topic information alive in other nodes. More...
 
std::string HostAddr () const
 Get the IP address of this host. More...
 
bool MsgPublishers (const std::string &_topic, MsgAddresses_M &_publishers)
 Get all the publishers' information known for a given topic. More...
 
std::recursive_mutex & Mutex () const
 Get mutex used in the Discovery class. More...
 
void PrintCurrentState () const
 Print the current discovery state (info, activity, unknown). More...
 
void ServiceList (std::vector< std::string > &_services) const
 Get the list of services currently advertised in the network. More...
 
void SetActivityInterval (const unsigned int _ms)
 Set the activity interval. More...
 
void SetAdvertiseInterval (const unsigned int _ms)
 Set the advertise 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...
 
bool SrvPublishers (const std::string &_topic, SrvAddresses_M &_publishers)
 Get all the publishers' information known for a given service. More...
 
void Start ()
 Start the discovery service. More...
 
void TopicList (std::vector< std::string > &_topics) const
 Get the list of topics currently advertised in the network. More...
 
bool UnadvertiseMsg (const std::string &_topic, const std::string &_nUuid)
 Unadvertise a new message. More...
 
bool UnadvertiseSrv (const std::string &_topic, const std::string &_nUuid)
 Unadvertise a new message service. More...
 
void WaitForInit () const
 Check if ready/initialized. More...
 

Protected Attributes

std::unique_ptr< DiscoveryPrivatedataPtr
 

Detailed Description

A discovery class that implements a distributed topic discovery protocol.

It uses UDP broadcast 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()

ignition::transport::Discovery::Discovery ( const std::string &  _pUuid,
const bool  _verbose = false 
)

Constructor.

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

◆ ~Discovery()

virtual ignition::transport::Discovery::~Discovery ( )
virtual

Destructor.

Member Function Documentation

◆ ActivityInterval()

unsigned int ignition::transport::Discovery::ActivityInterval ( ) const

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

See also
SetActivityInterval.
Returns
The value in milliseconds.

◆ AdvertiseInterval()

unsigned int ignition::transport::Discovery::AdvertiseInterval ( ) const

While a topic is being advertised by a node, a beacon is sent periodically every 'advertise interval' milliseconds.

See also
SetAdvertiseInterval.
Returns
The value in milliseconds.

◆ AdvertiseMsg()

bool ignition::transport::Discovery::AdvertiseMsg ( const MessagePublisher _publisher)

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

◆ AdvertiseSrv()

bool ignition::transport::Discovery::AdvertiseSrv ( const ServicePublisher _publisher)

Advertise a new service.

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

◆ ConnectionsCb() [1/2]

void ignition::transport::Discovery::ConnectionsCb ( const MsgDiscoveryCallback _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.

Parameters
[in]_cbFunction callback.

◆ ConnectionsCb() [2/2]

template<typename C >
void ignition::transport::Discovery::ConnectionsCb ( void(C::*)(const MessagePublisher &_pub)  _cb,
C *  _obj 
)
inline

Register a callback to receive discovery connection events.

Each time a new topic is discovered, the callback will be executed. This version uses a member functions as callback.

Parameters
[in]_cbFunction callback with the following parameters. _pub Publisher's information.
[in]_objObject instance where the member function belongs.

◆ ConnectionsSrvCb() [1/2]

void ignition::transport::Discovery::ConnectionsSrvCb ( const SrvDiscoveryCallback _cb)

Register a callback to receive discovery connection events for services.

Each time a new service is available, the callback will be executed. This version uses a free function as callback.

Parameters
[in]_cbFunction callback.

◆ ConnectionsSrvCb() [2/2]

template<typename C >
void ignition::transport::Discovery::ConnectionsSrvCb ( void(C::*)(const ServicePublisher &_pub)  _cb,
C *  _obj 
)
inline

Register a callback to receive discovery connection events for services.

Each time a new service is available, the callback will be executed. This version uses a member functions as callback.

Parameters
[in]_cbFunction callback with the following parameters. _pub Publisher's information.
[in]_objObject instance where the member function belongs.

◆ DisconnectionsCb() [1/2]

void ignition::transport::Discovery::DisconnectionsCb ( const transport::MsgDiscoveryCallback _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.

Parameters
[in]_cbFunction callback.

◆ DisconnectionsCb() [2/2]

template<typename C >
void ignition::transport::Discovery::DisconnectionsCb ( void(C::*)(const MessagePublisher &_pub)  _cb,
C *  _obj 
)
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 member function as callback.

Parameters
[in]_cbFunction callback with the following parameters. _pub Publisher's information.
[in]_objObject instance where the member function belongs.

◆ DisconnectionsSrvCb() [1/2]

void ignition::transport::Discovery::DisconnectionsSrvCb ( const transport::SrvDiscoveryCallback _cb)

Register a callback to receive discovery disconnection events for services.

Each time a service is no longer available, the callback will be executed. This version uses a free function as callback.

Parameters
[in]_cbFunction callback.

◆ DisconnectionsSrvCb() [2/2]

template<typename C >
void ignition::transport::Discovery::DisconnectionsSrvCb ( void(C::*)(const ServicePublisher &_pub)  _cb,
C *  _obj 
)
inline

Register a callback to receive discovery disconnection events.

Each time a service is no longer available, the callback will be executed. This version uses a member function as callback.

Parameters
[in]_cbFunction callback with the following parameters. _pub Publisher's information.
[in]_objObject instance where the member function belongs.

References ignition::transport::AdvSrvType, ignition::transport::AdvType, ignition::transport::ByeType, ignition::transport::HeartbeatType, ignition::transport::SubscriptionMsg::MsgLength(), ignition::transport::AdvertiseMessage< T >::MsgLength(), ignition::transport::MsgTypesStr, ignition::transport::SubscriptionMsg::Pack(), ignition::transport::AdvertiseMessage< T >::Pack(), ignition::transport::SubSrvType, ignition::transport::SubType, ignition::transport::UnadvSrvType, and ignition::transport::UnadvType.

◆ DiscoverMsg()

bool ignition::transport::Discovery::DiscoverMsg ( const std::string &  _topic)

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

◆ DiscoverSrv()

bool ignition::transport::Discovery::DiscoverSrv ( const std::string &  _topic)

Request discovery information about a service.

The user might want to use SetConnectionsSrvCb() and SetDisconnectionSrvCb(), that registers callbacks that will be executed when the service address is discovered or when the node providing the service is disconnected.

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

◆ DiscoveryMsgInfo()

const TopicStorage<MessagePublisher>& ignition::transport::Discovery::DiscoveryMsgInfo ( ) const

Get the discovery information object (messages).

Returns
Reference to the discovery information object.

◆ DiscoverySrvInfo()

const TopicStorage<ServicePublisher>& ignition::transport::Discovery::DiscoverySrvInfo ( ) const

Get the discovery information object (services).

Returns
Reference to the discovery information object.

◆ HeartbeatInterval()

unsigned int ignition::transport::Discovery::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.

See also
SetHeartbeatInterval.
Returns
The value in milliseconds.

◆ HostAddr()

std::string ignition::transport::Discovery::HostAddr ( ) const

Get the IP address of this host.

Returns
A string with this host's IP address.

◆ MsgPublishers()

bool ignition::transport::Discovery::MsgPublishers ( const std::string &  _topic,
MsgAddresses_M _publishers 
)

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

◆ Mutex()

std::recursive_mutex& ignition::transport::Discovery::Mutex ( ) const

Get mutex used in the Discovery class.

Returns
The discovery mutex.

◆ PrintCurrentState()

void ignition::transport::Discovery::PrintCurrentState ( ) const

Print the current discovery state (info, activity, unknown).

◆ ServiceList()

void ignition::transport::Discovery::ServiceList ( std::vector< std::string > &  _services) const

Get the list of services currently advertised in the network.

Parameters
[out]_topicsList of advertised services.

◆ SetActivityInterval()

void ignition::transport::Discovery::SetActivityInterval ( const unsigned int  _ms)

Set the activity interval.

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

◆ SetAdvertiseInterval()

void ignition::transport::Discovery::SetAdvertiseInterval ( const unsigned int  _ms)

Set the advertise interval.

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

◆ SetHeartbeatInterval()

void ignition::transport::Discovery::SetHeartbeatInterval ( const unsigned int  _ms)

Set the heartbeat interval.

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

◆ SetSilenceInterval()

void ignition::transport::Discovery::SetSilenceInterval ( const unsigned int  _ms)

Set the maximum silence interval.

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

◆ SilenceInterval()

unsigned int ignition::transport::Discovery::SilenceInterval ( ) const

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.

◆ SrvPublishers()

bool ignition::transport::Discovery::SrvPublishers ( const std::string &  _topic,
SrvAddresses_M _publishers 
)

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

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

◆ Start()

void ignition::transport::Discovery::Start ( )

Start the discovery service.

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

◆ TopicList()

void ignition::transport::Discovery::TopicList ( std::vector< std::string > &  _topics) const

Get the list of topics currently advertised in the network.

Parameters
[out]_topicsList of advertised topics.

◆ UnadvertiseMsg()

bool ignition::transport::Discovery::UnadvertiseMsg ( 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.

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

◆ UnadvertiseSrv()

bool ignition::transport::Discovery::UnadvertiseSrv ( const std::string &  _topic,
const std::string &  _nUuid 
)

Unadvertise a new message service.

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

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

◆ WaitForInit()

void ignition::transport::Discovery::WaitForInit ( ) const

Check if ready/initialized.

If not, then wait on the initializedCv condition variable.

Member Data Documentation

◆ dataPtr

std::unique_ptr<DiscoveryPrivate> ignition::transport::Discovery::dataPtr
protected

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