|
RTI Connext Traditional C++ API
Version 5.2.0
|
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...
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.
The default value of the DDS_DomainParticipantQos is obtained by calling DDSDomainParticipantFactory::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., DDSDomainParticipantFactory::set_default_participant_qos() has never been called or was called using DDS_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 Connext 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 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.
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 DDSDomainParticipant::add_peer() operation.
The anatomy of a peer descriptor is illustrated below using a UDPv4 transport and a custom "StarFabric" transport example.
A peer descriptor consists of:
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).
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:
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. 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 DDSEntity) may be used to parse the address string.
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 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:
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 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)
Default maximum participant ID on localhost
Default maximum participant ID on host 192.168.1.1 (IPv4)
Default maximum participant ID on host FAA0::0 (IPv6)
Default maximum participant ID on host himalaya accessed using the "udpv4" transport plugin(s) (IPv4)
Default maximum participant ID on localhost using the "udpv4" transport plugin(s) registered at network address FAA0::0
Default maximum participant ID on host 0/0/R (StarFabric)
Default maximum participant ID on host 0/0/R (StarFabric) using the "starfabric" (StarFabric) transport plugin(s)
Default maximum participant ID on host 0/0/R (StarFabric) using the "starfabric" (StarFabric) transport plugin(s) registered at network address FAA0::0
Default maximum participant ID on all unicast addresses accessed via the "starfabric" (StarFabric) transport plugin(s)
Default maximum participant ID on all unicast addresses accessed via the "shmem" (shared memory) transport plugin(s) registered at network address FCC0::0
Default maximum participant ID on hosts himalaya and gangotri
Maximum participant ID of 1 on hosts himalaya and gangotri
Combinations of above
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 RTI Connext 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) 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.
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 Connext applications anywhere on the local network to
;; discover each other over UDPv4.
builtin.udpv4://239.255.0.1 ; RTI Connext's default discovery multicast address
; This is also the default multicast receive address
;; Unicast - UDPv4 (on all platforms)
;;
;; This allows two RTI Connext 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 Connext 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:// The class names for the builtin transport plugins are:
shmem - ::Shared Memory Transport udpv4 - ::UDPv4 Transport udpv6 - ::UDPv6 Transport These may be used as the transport names in the Locator Format.
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:
or:
(To check if your platform supports shared memory, see the Platform Notes.)
RTI Connext Traditional C++ API Version 5.2.0
Copyright © Sun Jun 21 2015
Real-Time Innovations, Inc