Environment variable or a file that specifies the default values of rti::core::policy::Discovery::initial_peers(const dds::core::StringSeq & the_initial_peers) and rti::core::policy::Discovery::multicast_receive_addresses contained in the dds::domain::qos::DomainParticipantQos::discovery qos policy.

The default value of the dds::domain::qos::DomainParticipantQos is obtained by calling dds::domain::DomainParticipant::default_participant_qos()().

NDDS_DISCOVERY_PEERS specifies the default value of the rti::core::policy::Discovery::initial_peers(const dds::core::StringSeq & the_initial_peers) and rti::core::policy::Discovery::multicast_receive_addresses fields, when the default participant QoS policies have not been explictly set by the user (i.e., dds::domain::DomainParticipant::default_participant_qos()() has never been called or was called using PARTICIPANT_QOS_DEFAULT).

If NDDS_DISCOVERY_PEERS does not contain a multicast address, then the string sequence rti::core::policy::Discovery::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 will be stored in rti::core::policy::Discovery::multicast_receive_addresses, starting at element 0. They will be stored in the order in which they appear in NDDS_DISCOVERY_PEERS.

Note: IPv4 multicast addresses must have a prefix. Therefore, when using the UDPv6 transport: if there are any IPv4 multicast addresses in the peers list, make sure they have "udpv4://" in front of them (such as udpv4://239.255.0.1).

Note: Currently, RTI Connext will only listen for discovery traffic on the first multicast address (element 0) in rti::core::policy::Discovery::multicast_receive_addresses.

NDDS_DISCOVERY_PEERS provides a mechanism to dynamically switch the discovery configuration of an RTI Connext application without recompilation. The application programmer is free to not use the default values; instead use values supplied by other means.

NDDS_DISCOVERY_PEERS can be specified either in an environment variable as comma (',') separated "peer descriptors" (see Peer Descriptor Format) or in a file. These formats are described below.

Peer Descriptor Format

A peer descriptor string specifies a range of participants at a given locator. Peer descriptor strings are used in the rti::core::policy::Discovery::initial_peers(const dds::core::StringSeq & the_initial_peers) field and the dds::domain::DomainParticipant::add_peer(const std::string & peer_descr_string)() operation.

The anatomy of a peer descriptor is illustrated below using a UDPv4 transport and a custom "StarFabric" transport example.

String based addressing

A peer descriptor consists of:

[optional] Participant ID Limit. If a simple integer is specified, it indicates the maximum participant ID to be contacted by the RTI Connext discovery mechanism at the given locator. If that integer is enclosed in square brackets (e.g.: [2]) only that Participant ID will be used. You can also specify a range in the form of [a-b]: in this case only the Participant IDs in that specific range are contacted. If omitted, a default value of 4 is implied: participant IDs 0,1,2,3, and 4 will be contacted.

Locator. See Locator Format.

These are separated by the '@' character. The separator may be omitted if a participant ID limit is not explictly specified.

Note that the "participant ID limit" only applies to unicast locators; it is ignored for multicast locators (and therefore should be omitted for multicast peer descriptors).

Locator Format

A locator string specifies a transport and an address in string format. Locators are used to form peer descriptors. A locator is equivalent to a peer descriptor with the default maximum participant ID.

A locator consists of:

[optional] Transport name (alias or class). This identifies the set of transport plugins (Transport Aliases) that may be used to parse the address portion of the locator. Note that a transport class name is an implicit alias that is used to refer to all the transport plugin instances of that class.

[optional] Address. See Address Format.

These are separated by the "//:" string. The separator is specified if and only if a transport name is specified.

If a transport name is specified, the address may be omitted; in that case, all the unicast addresses (across all transport plugin instances) associated with the transport class are implied. Thus, a locator string may specify several addresses.

If an address is specified, the transport name and the separator string may be omitted; in that case all the available transport plugins (for the dds::core::Entity) may be used to parse the address string.

Address Format

An address string specifies a transport-independent network address that qualifies a transport-dependent address string. Addresses are used to form locators. Addresses are also used in rti::core::policy::Discovery::multicast_receive_addresses, and rti::core::TransportMulticastSettings::receive_address fields. An address is equivalent to a locator in which the transport name and separator are omitted.

An address consists of:

[optional] Network Address. An address in IPv4 or IPv6 string notation. If omitted, the network address of the transport is implied (Transport Network Address).

[optional] Transport Address. A string that is passed to the transport for processing. The transport maps this string into NDDS_Transport_Property_t::address_bit_count bits. If omitted the network address is used as the fully qualified address.

These are separated by the '#' character. If a separator is specified, it must be followed by a non-empty string which is passed to the transport plugin. If the separator is omitted, it is treated as a transport address with an implicit network address (of the transport plugin). The implicit network address is the address used when registering the transport: e.g, the UDPv4 implicit network address is 0.0.0.0.0.0.0.0.0.0.0.0.

The bits resulting from the transport address string are prepended with the network address. The least significant NDDS_Transport_Property_t::address_bit_count bits of the network address are ignored (Transport Network Address).

NDDS_DISCOVERY_PEERS Environment Variable Format

NDDS_DISCOVERY_PEERS can be specified via an environment variable of the same name, consisting of a sequence of peer descriptors separated by the comma (',') character.

Examples

Multicast (maximum participant ID is irrelevant)

239.255.0.1

Default maximum participant ID on localhost

localhost

Default maximum participant ID on host 192.168.1.1 (IPv4)

192.168.1.1

Default maximum participant ID on host FAA0::0 (IPv6)

FAA0::1

Default maximum participant ID on host himalaya accessed using the "udpv4" transport plugin(s) (IPv4)

udpv4://himalaya

Default maximum participant ID on localhost using the "udpv4" transport plugin(s) registered at network address FAA0::0

udpv4://FAA0::0#localhost

Default maximum participant ID on host 0/0/R (StarFabric)

0/0/R
#0/0/R

Default maximum participant ID on host 0/0/R (StarFabric) using the "starfabric" (StarFabric) transport plugin(s)

starfabric://0/0/R
starfabric://#0/0/R

Default maximum participant ID on host 0/0/R (StarFabric) using the "starfabric" (StarFabric) transport plugin(s) registered at network address FAA0::0

starfabric://FBB0::0#0/0/R

Default maximum participant ID on all unicast addresses accessed via the "starfabric" (StarFabric) transport plugin(s)

starfabric://

Default maximum participant ID on all unicast addresses accessed via the "shmem" (shared memory) transport plugin(s) registered at network address FCC0::0

shmem://FCC0::0

Default maximum participant ID on hosts himalaya and gangotri

himalaya,gangotri

Maximum participant ID of 1 on hosts himalaya and gangotri

1@himalaya,1@gangotri

Combinations of above

239.255.0.1,localhost,192.168.1.1,0/0/R
FAA0::1,FAA0::0#localhost,FBB0::0#0/0/R
udpv4://himalaya,udpv4://FAA0::0#localhost,#0/0/R
starfabric://0/0/R,starfabric://FBB0::0#0/0/R,shmem://
starfabric://,shmem://FCC0::0,1@himalaya,1@gangotri

NDDS_DISCOVERY_PEERS File Format

NDDS_DISCOVERY_PEERS can be specified via a file of the same name in the program's current working directory. A NDDS_DISCOVERY_PEERS file would contain a sequence of peer descriptors separated by whitespace or the comma (',') character. The file may also contain comments starting with a semicolon (';') character till the end of the line.

Example:

 ;; NDDS_DISCOVERY_PEERS - Discovery Configuration File 
 ;; 
 ;; 
 ;; NOTE: 
 ;;   1. This file must be in the current working directory, i.e. 
 ;;      in the folder from which the application is launched. 
 ;; 
 ;;   2. This file takes precedence over the environment variable NDDS_DISCOVERY_PEERS 
 ;;
  
 ;; Multicast 
 239.255.0.1                  ; The default dds discovery multicast address
  
 ;; Unicast 
 localhost,192.168.1.1        ; A comma can be used a separator 
 FAA0::1  FAA0::0#localhost   ; Whitespace can be used as a separator 
 1@himalaya                   ; Maximum participant ID of 1 on 'himalaya' 
 1@gangotri
  
 ;; UDPv4 
 udpv4://himalaya             ; 'himalaya' via 'udpv4' transport plugin(s) 
 udpv4://FAA0::0#localhost    ; 'localhost' via 'updv4' transport 
                              ;  plugin registered at network address FAA0::0
  
 ;; Shared Memory 
 shmem://                     ; All 'shmem' transport plugin(s) 
 builtin.shmem://             ; The builtin 'shmem' transport plugin 
 shmem://FCC0::0              ; Shared memory transport plugin registered 
                              ;                at network address FCC0::0
  
 ;; StarFabric 
 0/0/R                        ; StarFabric node 0/0/R 
 starfabric://0/0/R           ; 0/0/R accessed via 'starfabric' 
                              ;             transport plugin(s) 
 starfabric://FBB0::0#0/0/R   ; StarFabric transport plugin registered 
                              ;             at network address FBB0::0 
 starfabric://                ; All 'starfabric' transport plugin(s)

NDDS_DISCOVERY_PEERS Precedence

If the current working directory from which the RTI Connext application is launched contains a file called NDDS_DISCOVERY_PEERS, and an environment variable named NDDS_DISCOVERY_PEERS is also defined, the file takes precedence; the environment variable is ignored.

NDDS_DISCOVERY_PEERS Default Value

If NDDS_DISCOVERY_PEERS is not specified (either as a file in the current working directory, or as an environment variable), it implicitly defaults to the following.

 ;; Multicast (only on platforms which allow UDPv4 multicast out of the box) 
 ;; 
 ;; This allows any dds applications anywhere on the local network to 
 ;; discover each other over UDPv4. 
 builtin.udpv4://239.255.0.1  ; dds's default discovery multicast address 
                              ; This is also the default multicast receive address
  
 ;; Unicast - UDPv4 (on all platforms) 
 ;; 
 ;; This allows two dds applications using participant IDs up to the maximum 
 ;; default participant ID on the local host and domain to discover each 
 ;; other over UDP/IPv4. 
 builtin.udpv4://127.0.0.1
  
 ;; Unicast - Shared Memory (only on platforms that support shared memory) 
 ;; 
 ;; This allows two dds applications using participant IDs up to the maximum 
 ;; default participant ID on the local host and domain to discover each 
 ;; other over shared memory. 
 builtin.shmem://

Builtin Transport Class Names

The class names for the builtin transport plugins are:

shmem - ShmemTransport
udpv4 - UDPv4Transport
udpv6 - UDPv6Transport

These may be used as the transport names in the Locator Format.

NDDS_DISCOVERY_PEERS and Local Host Communication

Suppose you want to communicate with other RTI Connext applications on the same host and you are setting NDDS_DISCOVERY_PEERS explicitly (generally in order to use unicast discovery with applications on other hosts).

If the local host platform does not support the shared memory transport, then you can include the name of the local host in the NDDS_DISCOVERY_PEERS list.

If the local host platform supports the shared memory transport, then you can do one of the following:

Include "shmem://" in the NDDS_DISCOVERY_PEERS list. This will cause shared memory to be used for discovery and data traffic for applications on the same host.

or:

Include the name of the local host in the NDDS_DISCOVERY_PEERS list and disable the shared memory transport in the rti::core::policy::TransportBuiltin of the dds::domain::DomainParticipant. This will cause UDP loopback to be used for discovery and data traffic for applications on the same host.

(To check if your platform supports shared memory, see the Platform Notes.)

See also: rti::core::policy::Discovery::multicast_receive_addresses; rti::core::policy::Discovery::initial_peers(const dds::core::StringSeq & the_initial_peers); dds::domain::DomainParticipant::add_peer(const std::string & peer_descr_string)(); PARTICIPANT_QOS_DEFAULT; dds::domain::DomainParticipant::default_participant_qos()(); Transport Aliases; Transport Network Address