NDDS_DISCOVERY_PEERS
[DISCOVERY]

Environment variable or a file that specifies the default values of DDS::DiscoveryQosPolicy::initial_peers and DDS::DiscoveryQosPolicy::multicast_receive_addresses contained in the DDS::DomainParticipantQos::discovery qos policy. More...

The default value of the DDS::DomainParticipantQos is obtained by calling DDS::DomainParticipantFactory::get_default_participant_qos().

NDDS_DISCOVERY_PEERS specifies the default value of the DDS::DiscoveryQosPolicy::initial_peers and DDS::DiscoveryQosPolicy::multicast_receive_addresses fields, when the default participant QoS policies have not been explictly set by the user (i.e., DDS::DomainParticipantFactory::set_default_participant_qos() has never been called or was called using DDS::DomainParticipantFactory::PARTICIPANT_QOS_DEFAULT).

If NDDS_DISCOVERY_PEERS does not contain a multicast address, then the string sequence DDS::DiscoveryQosPolicy::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 DDS::DiscoveryQosPolicy::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 Data Distribution Service will only listen for discovery traffic on the first multicast address (element 0) in DDS::DiscoveryQosPolicy::multicast_receive_addresses.

NDDS_DISCOVERY_PEERS provides a mechanism to dynamically switch the discovery configuration of an RTI Data Distribution Service 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 DDS::DiscoveryQosPolicy::initial_peers field and the DDS::DomainParticipant::add_peer() operation.

The anatomy of a peer descriptor is illustrated below using a special "StarFabric" transport example.

String based addressing

A peer descriptor consists of:

[optional] Maximum Participant ID. Specifies the maximum participant ID that is contacted by the RTI Data Distribution Service discovery mechanism at the given locator. If omitted, a default value of 4 is implied.

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, and 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 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::Entity) may be used to parse the address string.

Address Format

An address string specifies a transport independent network address that qualifies an transport dependent address string. Addresses are used to form locators. Addresses are also used in DDS::DiscoveryQosPolicy::multicast_receive_addresses, and DDS::TransportMulticastSettings_t::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 DDS::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.

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

If the separator is omitted and the string is not a valid IPv4 or IPv6 address, it is treated as a transport address with an implicit network address (of the transport plugin).

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 FAA0::0#localhost (could be a UDPv4 transport plugin registered at network address of FAA0::0) (IPv6)

FAA0::0#localhost

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 all unicast addresses accessed via the "udpv4" (UDPv4) transport plugin(s)

udpv4://

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)

shmem://

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 - Default 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 RTI Data Distribution Service 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 Data Distribution Service 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 RTI Data Distribution Service applications anywhere on the local network to
  ;; discover each other over UDPv4.
  
  builtin.udpv4://239.255.0.1  ; RTI Data Distribution Service's default discovery multicast address
  
  
  ;; Unicast - UDPv4 (on all platforms)
  ;;
  ;; This allows two RTI Data Distribution Service 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 RTI Data Distribution Service 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:

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 Data Distribution Service 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 DDS::TransportBuiltinQosPolicy of the DDS::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 document.)

DDS::DiscoveryQosPolicy::initial_peers

DDS::DomainParticipant::add_peer()

DDS::DomainParticipantFactory::PARTICIPANT_QOS_DEFAULT

DDS::DomainParticipantFactory::get_default_participant_qos()

Transport Aliases

Transport Network Address

NDDS_DISCOVERY_PEERS [DISCOVERY]

NDDS_DISCOVERY_PEERS
[DISCOVERY]