The DISCOVERY QoS configures how DomainParticipants discover each other on the network. It identifies where on the network this application can potentially discover other applications with which to communicate. The middleware will periodically send network packets to these locations, announcing itself to any remote applications that may be present, and will listen for announcements from those applications. The discovery process is described in detail in Discovery.
This QosPolicy includes the members in DDS_DiscoveryQosPolicy. For defaults and valid ranges, please refer to the API Reference HTML documentation.
Type |
Field Name |
Description |
DDS_StringSeq |
Transports available for use by the discovery process. See Transports Used for Discovery. |
|
DDS_StringSeq |
Unicast locators (address/indices) of potential participants with which this DomainParticipant will attempt to establish communications. See Setting the ‘Initial Peers’ List. |
|
DDS_StringSeq |
List of multicast addresses on which Discovery-related messages can be received by the DomainParticipant. See Configuring Multicast Receive Addresses. |
|
DDS_Long |
Transport priority to be used for sending Discovery messages. See Meta-Traffic Transport Priority. |
|
DDS_Boolean |
Whether to accept a participant discovered via unicast that is not in the initial_peers list. See Controlling Acceptance of Unknown Peers. |
|
DDS_Boolean |
Whether endpoint discovery will automatically occur with discovered DomainParticipants. See Supervising Endpoint Discovery. |
The enabled_transports field allows you to specify the set of installed and enabled transports that can be used to discover other DomainParticipants. This field is a sequence of strings where each string specifies an alias of a registered (and thus installed and enabled) transport. Please see the API Reference HTML documentation (select Modules, RTI Connext DDS API Reference, Pluggable Transports) for more information.
When a DomainParticipant is created, it needs to find other participants in the same DDS domain—this is known as the ‘discovery process’ which is discussed in Discovery. One way to do so is to use this QosPolicy to specify a list of potential participants. This is the role of the parameter initial_peers. The strings containing peer descriptors are stored in the initial_peers string sequence. The format of a string discussed in Peer Descriptor Format.
The peers stored in initial_peers are merely potential peers—there is no requirement that the peer DomainParticipants are actually up and running or even will eventually exist. The Connext DDS discovery process will try to contact all potential peer participants in the list periodically using unicast transports (as configured by the DISCOVERY_CONFIG QosPolicy (DDS Extension)).
The initial_peers parameter can be modified in source code or it can be initialized from an environment variable, NDDS_DISCOVERY_PEERS or from a text file, see Configuring the Peers List Used in Discovery.
The DomainParticipant’s add_peer() operation adds a peer description to the internal peer list that was initialized by the initial_peer field of the DISCOVERY QosPolicy.
DDS_ReturnCode_t DDSDomainParticipant::add_peer ( const char* peer_desc)
The peer_desc string must be formatted as specified in Peer Descriptor Format.
You can call this operation any time after the DomainParticipant has been enabled. An attempt will be made to contact the new peer immediately.
Adding peers with this operation has no effect on the initial_peers list. After a DomainParticipant has been created, the contents of the initial_peers field merely shows what the internal peer list was initialized to be. Therefore, initial_peers may not reflect the actual potential peer list used by a DomainParticipant. Furthermore, if you call get_qos(), the returned list of peers will not include the added peer—get_qos() will only show you what is set in the initial_peers list.
A peer added with add_peer() is not considered to be “unknown.” (That is, you may have accept_unknown_peers (Controlling Acceptance of Unknown Peers) set to FALSE and still use add_peer().)
You can remove an entry from the list with remove_peer(). Note that remove_peer() is only supported if Simple Participant Discovery (see Simple Participant Discovery) is enabled for the Participant.
You can ignore data from a participant by using the ignore_participant() operation described in Restricting Communication—Ignoring Entities.
The multicast_receive_addresses field in the DISCOVERY QosPolicy is a sequence of strings that specifies a set of multicast group addresses on which the DomainParticipant will listen for discovery meta-traffic. Each string must have a valid multicast address in either IPv4 dot notation or IPv6 presentation format. Please look at publicly available documentation of the IPv4 and IPv6 standards for the definition and valid address ranges for multicast.
The multicast_receive_addresses field can be initialized from multicast addresses that appear in the NDDS_DISCOVERY_PEERS environment variable or text file, see Configuring the Peers List Used in Discovery. A multicast address found in the environment variable or text file will be added both to the initial_peers and multicast_receive_addresses fields. Note that the addresses in initial_peers are ones in which the DomainParticipant will send discovery meta-traffic, and the ones in multicast_receive_addresses are used for receiving discovery meta-traffic.
If NDDS_DISCOVERY_PEERS does not contain a multicast address, then multicast_receive_addresses is cleared and the RTI discovery process will not listen for discovery messages via multicast.
If NDDS_DISCOVERY_PEERS contains one or more multicast addresses, the addresses are stored in multicast_receive_addresses, starting at element 0. They will be stored in the order in which they appear in NDDS_DISCOVERY_PEERS.
Note: Currently, Connext DDS will only listen for discovery traffic on the first multicast address (element 0) in multicast_receive_addresses.
If you want to send discovery meta-traffic on a different set of multicast addresses than you want to receive discovery meta-traffic, set initial_peers and multicast_receive_addresses via the QosPolicy API.
The metatraffic_transport_priority field is used to specify the transport priority to be used for sending all discovery meta-traffic. See the TRANSPORT_PRIORITY QosPolicy for details on how transport priorities may be used.
The accept_unknown_peers field controls whether or not a DomainParticipant is allowed to communicate with other DomainParticipants found via unicast transport that are not in its peers list (which is the combination of the initial_peers list and any peers added with the add_peer() operation described in Adding and Removing Peers List Entries).
Suppose Participant A is included in Participant B’s initial peers list, but Participant B is not in Participant A’s list. When Participant B contacts Participant A by sending it a unicast discovery packet, then Participant A has a choice:
Note that Participants do not exchange peer lists. So if Participant A knows about Participant B, and Participant B knows about Participant C, Participant A will not discover Participant C.
Note: If accept_unknown_peers is false and shared memory is disabled, applications on the same node will not communicate if only ‘localhost’ is specified in the peer list. If shared memory is disabled or ‘shmem://’ is not specified in the peer list, if you want to communicate with other applications on the same node through the loopback interface, you must put the actual node address or hostname in NDDS_DISCOVERY_PEERS.
You will always use this policy to set the participant_id when you want to run more than one DomainParticipant in the same DDS domain on the same host.
The easiest way to set the initial peers list is to use the NDDS_DISCOVERY_PEERS environment variable. However, should you want asymmetric multicast addresses for sending or receiving meta-traffic, you will need to use this QosPolicy directly.
A reason to use asymmetric multicast addresses is to take advantage of the efficiency provided by using multicast, while at the same time preventing all participants from discovering each other. For example, suppose you have a system in which you have a single server node and a hundred client nodes. The client nodes do not publish or subscribe to each other’s data and thus never need to know about each others existence.
If we did not use multicast, we would have to populate the server application’s peer list with 100 peer descriptors for each of the client nodes. Each client application would only need to have the server application in its peer list. The maintenance of the list is unwieldy, especially if nodes are constantly reconfigured and addresses changed. In addition, the server will send out discovery packets on a per client basis since the peer list essentially holds 100 unicast addresses.
Instead, if we used a single multicast address in the NDDS_DISCOVERY_PEERS environment variable, the server and all of the clients would discover each other. Certainly, the list is easier to maintain, but the total amount of traffic has actually increased since the clients are now exchanging packets with each other uselessly.
To keep the list maintainable, as well as to minimize discovery traffic, we can have the server send out packets on a multicast address by modifying its initial_peer field. The clients would have their multicast_receive_addresses field set to the same address used by the server. The initial_peers of the clients would only need the single unicast peer descriptor of the server as before.
Now, the server can send a single packet that will be received by all of the clients, but the clients will not discover each other because they never send out a multicast packet themselves.
This QosPolicy cannot be modified after the DomainParticipant is created.
It can be set differently on the publishing and subscribing sides.
For every entry in the initial_peers list, Connext DDS will periodically send a discovery packet to see if that participant exists. If the list has many potential participants that are never started, then CPU and network bandwidth may be wasted in sending out packets that will never be received.
© 2017 RTI