44.2 DISCOVERY QosPolicy (DDS Extension)

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 22. Discovery Overview.

This QosPolicy includes the members in Table 44.2 DDS_DiscoveryQosPolicy. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 44.2 DDS_DiscoveryQosPolicy

Type

Field Name

Description

DDS_StringSeq

enabled_transports

Transports available for use by the discovery process. See 44.2.1 Transports Used for Discovery.

DDS_StringSeq

initial_peers

Unicast locators (address/indices) of potential participants with which this DomainParticipant will attempt to establish communications. See 44.2.2 Setting the ‘Initial Peers’ List.

DDS_StringSeq

multicast_receive_addresses

List of multicast addresses on which Discovery-related messages can be received by the DomainParticipant. See 44.2.4 Configuring Multicast Receive Addresses.

DDS_Long

metatraffic_transport_priority

Transport priority to be used for sending Discovery messages. See 44.2.5 Meta-Traffic Transport Priority.

DDS_Boolean

accept_unknown_peers

Whether to accept a participant discovered via unicast that is not in the initial_peers list. See 44.2.6 Controlling Acceptance of Unknown Peers.

DDS_Boolean

enable_endpoint_discovery

Whether endpoint discovery will automatically occur with discovered DomainParticipants. See 27.5 Supervising Endpoint Discovery.

44.2.1 Transports Used for 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 API Reference, Pluggable Transports) for more information.

44.2.2 Setting the ‘Initial Peers’ List

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 22. Discovery Overview. 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 24.1 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 discovery process will try to contact all potential peer participants in the list periodically using unicast transports (as configured by the 44.3 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 24. Configuring the Peers List Used in Discovery.

Some transports accept the use of hostnames to specify the initial peers. By default, Connext only resolves those hostnames when the DomainParticipant is created, but the DNS tracker can be used to keep the IP addresses of these hostnames updated. See 26.3 Using DNS Tracker to Keep Peer List Updated.

44.2.3 Adding and Removing Peers List Entries

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 24.1 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 (44.2.6 Controlling Acceptance of Unknown Peers) set to FALSE and still use add_peer().)

This behavior may change depending on the DNS tracker configuration; see 26.3 Using DNS Tracker to Keep Peer List Updated. Adding a peer with a hostname that cannot be resolved into an IP address will produce an error if the DNS Tracker has not been enabled for that DomainParticipant.

You can remove an entry from the list with remove_peer(). Note that remove_peer() is only supported if Simple Participant Discovery (see 22.1 Simple Participant Discovery) is enabled for the Participant.

You can ignore data from a participant by using the ignore_participant() operation described in 27. Restricting Communication—Ignoring Entities.

44.2.4 Configuring Multicast Receive Addresses

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

44.2.5 Meta-Traffic Transport Priority

The metatraffic_transport_priority field is used to specify the transport priority to be used for sending all discovery meta-traffic. See the 47.26 TRANSPORT_PRIORITY QosPolicy for details on how transport priorities may be used.

44.2.6 Controlling Acceptance of Unknown Peers

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 44.2.3 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:

  • If accept_unknown_peers is DDS_BOOLEAN_TRUE, then Participant A will reply to Participant B, and communications will be established.
  • If accept_unknown_peers is DDS_BOOLEAN_FALSE, then Participant A will ignore Participant B, and A and B will never talk.

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.

44.2.7 Example

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.

44.2.8 Properties

This QosPolicy cannot be modified after the DomainParticipant is created.

It can be set differently on the publishing and subscribing sides.

44.2.9 Related QosPolicies

44.2.10 Applicable Entities

44.2.11 System Resource Considerations

For every entry in the initial_peers list, Connext 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.