The TRANSPORT_UNICAST QosPolicy allows you to specify unicast network addresses to be used by DomainParticipant, DataWriters and DataReaders for receiving messages.
Connext DDS may send data to a variety of Entities, not just DataReaders. DomainParticipants receive messages to support the discovery process discussed in Discovery. DataWriters may receive ACK/NACK messages to support the reliable protocol discussed in Reliable Communications.
During discovery, each Entity announces to remote applications a list of (up to 4) unicast addresses to which the remote application should send data (either user-data packets or reliable protocol meta-data such as ACK/NACK and Heartbeats).
By default, the list of addresses is populated automatically with values obtained from the enabled transport plugins allowed to be used by the Entity (see the TRANSPORT_BUILTIN QosPolicy (DDS Extension) and TRANSPORT_SELECTION QosPolicy (DDS Extension)). Also, the associated ports are automatically determined (see Inbound Ports for User Traffic).
Use TRANSPORT_UNICAST QosPolicy to manually set the receive address list for an Entity. You may optionally set a port to use a non-default receive port as well. Only the first 4 addresses will be used. Connext DDS will create a receive thread for every unique port number that it encounters (on a per transport basis).
The QosPolicy structure includes the members in DDS_TransportUnicastQosPolicy. For more information and default values, please refer to the API Reference HTML documentation.
|
Type |
Field Name |
Description |
|
DDS_TransportUnicastSettingsSeq |
A sequence of up to 16 unicast settings that should be used by remote entities to address messages to be sent to this Entity. This is a hard limit that cannot be increased. However, this limit can be decreased by configuring the DomainParticipant property dds.domain_participant.max_announced_locator_list_size. |
|
Type |
Field Name |
Description |
|
DDS_StringSeq |
A sequence of transport aliases that specifies which transports should be used to receive unicast messages for this Entity. |
|
|
DDS_Long |
The port that should be used in the addressing of unicast messages destined for this Entity. A value of 0 will cause Connext DDS to use a default port number based on domain and participant ids. See Ports Used for Discovery. |
A message sent to a unicast address will be received by a single node on the network (as opposed to a multicast address where a single message may be received by multiple nodes). This policy sets the unicast addresses and ports that remote entities should use when sending messages to the Entity on which the TRANSPORT_UNICAST QosPolicy is set.
Up to 16 “return” unicast addresses may be configured for an Entity. This is a hard limit that cannot be increased. However, this limit can be decreased by configuring the DomainParticipant property dds.domain_participant.max_announced_locator_list_size. Instead of specifying addresses directly, you use the transports field of the DDS_TransportUnicastSetting_t to select the transports (using their aliases) on which remote entities should send messages destined for this Entity. The addresses of the selected transports will be the “return” addresses. See the API Reference HTML documentation about configuring transports and aliases (from the Modules page, select RTI Connext DDS API Reference, Pluggable Transports).
Note, a single transport may have more than one unicast address. For example, if a node has multiple network interface cards (NICs), then the UDPv4 transport will have an address for each NIC. When using the TRANSPORT_UNICAST QosPolicy to set the return addresses, a single value for the DDS_TransportUnicastSettingsSeq may provide more than the four return addresses that Connext DDS currently uses.
Whether or not you are able to configure the network interfaces that are allowed to be used by a transport is up to the implementation of the transport. For the built-in UDPv4 transport, you may restrict an instance of the transport to use a subset of the available network interfaces. See the API Reference HTML documentation for the built-in UDPv4 transport for more information.
For a DomainParticipant, this QoS policy sets the default list of addresses used by other applications to send user data for local DataReaders.
For a reliable DataWriter, if set, the other applications will use the specified list of addresses to send reliable protocol packets (ACKS/NACKS) on the behalf of reliable DataReaders. Otherwise, if not set, the other applications will use the addresses set by the DomainParticipant.
For a DataReader, if set, then other applications will use the specified list of addresses to send user data (and reliable protocol packets for reliable DataReaders). Otherwise, if not set, the other applications will use the addresses set by the DomainParticipant.
For a DataReader, if the port number specified by this QoS is the same as a port number specified by a TRANSPORT_MULTICAST QoS, then the transport may choose to process data received both via multicast and unicast with a single thread. Whether or not a transport must use different threads to process data received via multicast or unicast for the same port number depends on the implementation of the transport.
To use this QosPolicy, you also need to specify a port number. A port number of 0 will cause Connext DDS to automatically use a default value. As explained in Ports Used for Discovery, the default port number for unicast addresses is based on the domain and participant IDs. Should you choose to use a different port number, then for every unique port number used by Entities in your application, depending on the transport, Connext DDS may create a thread to process messages received for that port on that transport. See Connext DDS Threading Model for more about threads.
Threads are created on a per-transport basis, so if this QosPolicy specifies multiple transports for a receive_port, then a thread may be created for each transport for that unique port. Some transports may be able to share a single thread for different ports, others can not. Different Entities can share the same port number, and thus, the same thread will process all of the data for all of the Entities sharing the same port number for a transport.
Note: If a DataWriter is using the MULTI_CHANNEL QosPolicy (DDS Extension), the unicast addresses specified in the TRANSPORT_UNICAST QosPolicy are ignored by that DataWriter. The DataWriter will not publish DDS samples on those locators.
You may use this QosPolicy to restrict an Entity from receiving data through a particular transport. For example, on a multi-NIC (network interface card) system, you may install different transports for different NICs. Then you can balance the network load between network cards by using different values for the TRANSPORT_UNICAST QosPolicy for different DataReaders. Thus some DataReaders will receive their data from one NIC and other DataReaders will receive their data from another.
This QosPolicy cannot be modified after the Entity is created.
It can be set differently for the DomainParticipant, the DataWriter and the DataReader.
Because this QosPolicy changes the transports on which messages are received for different Entities, the bandwidth used on the different transports may be affected.
Depending on the implementation of a transport, Connext DDS may need to create threads to receive and process data on a unique-port-number basis. Some transports can share the same thread to process data received for different ports; others like UDPv4 must have different threads for different ports. In addition, if the same port is used for both unicast and multicast, the transport implementation will determine whether or not the same thread can be used to process both unicast and multicast data. For UDPv4, only one thread is needed per port–independent of whether the data was received via unicast or multicast data. See Receive Threads for more information.
© 2018 RTI