47.28 TRANSPORT_UNICAST QosPolicy (DDS Extension)
The TRANSPORT_UNICAST QosPolicy allows you to specify unicast network addresses to be used by DomainParticipant, DataWriters and DataReaders for receiving messages.
Connext may send data to a variety of Entities, not just DataReaders. DomainParticipants receive messages to support the discovery process discussed in Chapter 22 Discovery Overview. DataWriters may receive ACK/NACK messages to support the reliable protocol discussed in Chapter 32 Reliability Models for Sending Data.
During discovery, each Entity announces to remote applications a list of (up to 16) 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 44.8 TRANSPORT_BUILTIN QosPolicy (DDS Extension) and 47.27 TRANSPORT_SELECTION QosPolicy (DDS Extension)). Also, the associated ports are automatically determined (see 23.2 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 16 addresses will be used. Connext 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 Table 47.47 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 (whose default size is 16). |
|
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 to use a default port number based on domain and participant ids. See Chapter 23 Ports Used for Communication. |
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 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 maximum number of return addresses that Connext accepts (8 by default, changeable to 16).
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 to automatically use a default value. As explained in Chapter 23 Ports Used for Communication, 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 may create a thread to process messages received for that port on that transport. See Part 11: Connext 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 47.16 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.
47.28.1 Example
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.
47.28.2 Properties
This QosPolicy cannot be modified after the Entity is created.
It can be set differently for the DomainParticipant, the DataWriter and the DataReader.
47.28.3 Related QosPolicies
- 47.16 MULTI_CHANNEL QosPolicy (DDS Extension)
- 47.27 TRANSPORT_SELECTION QosPolicy (DDS Extension)
- 48.5 TRANSPORT_MULTICAST QosPolicy (DDS Extension)
- 44.8 TRANSPORT_BUILTIN QosPolicy (DDS Extension)
47.28.4 Applicable Entities
47.28.5 System Resource Considerations
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 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 Chapter 67 Receive Threads for more information.