You are here: Part 3: Advanced Concepts > Transport Plugins > Setting Builtin Transport Properties with the PropertyQosPolicy

Setting Builtin Transport Properties with the PropertyQosPolicy

The PROPERTY QosPolicy (DDS Extension) allows you to set name/value pairs of data and attach them to an entity, such as a DomainParticipant.

To assign properties, use the add_property() operation:

DDS_ReturnCode_t DDSPropertyQosPolicyHelper::add_property  
(DDS_PropertyQosPolicy policy,
const char * name,
const char * value,
DDS_Boolean propagate)

For more information on add_property() and the other operations in the DDSPropertyQosPolicyHelper class, please see PropertyQoSPolicyHelper Operations, as well as the API Reference HTML documentation.

The ‘name’ part of the name/value pairs is a predefined string. The property names for the builtin transports are described in these tables:

See also:

Note:

Changing properties with the PROPERTY QosPolicy (DDS Extension) will overwrite any properties set by calling set_builtin_transport_property().

Properties for the Builtin UDPv4 Transport

Property Name

(prefix with ‘dds.transport.UDPv4.builtin.’)

Property Value Description

parent.address_bit_count

Number of bits in a 16-byte address that are used by the transport. Should be between 0 and 128.

For example, for an address range of 0-255, the address_bit_count should be set to 8. For the range of addresses used by IPv4 (4 bytes), it should be set to 32.

parent.properties_bitmap

A bitmap that defines various properties of the transport to the Connext DDS core.

Currently, the only property supported is whether or not the transport plugin will always loan a buffer when Connext DDS tries to receive a message using the plugin. This is in support of a zero-copy interface.

parent.
gather_send_buffer_count_max

Specifies the maximum number of buffers that Connext DDS can pass to the send() method of a transport plugin.

The transport plugin send() API supports a gather-send concept, where the send() call can take several discontiguous buffers, assemble and send them in a single message. This enables Connext DDS to send a message from parts obtained from different sources without first having to copy the parts into a single contiguous buffer.

However, most transports that support a gather-send concept have an upper limit on the number of buffers that can be gathered and sent. Setting this value will prevent Connext DDS from trying to gather too many buffers into a send call for the transport plugin.

Connext DDS requires all transport-plugin implementations to support a gather-send of least a minimum number of buffers. This minimum number is NDDS_TRANSPORT_PROPERTY_GATHER_SEND_BUFFER_COUNT_MIN.

See Setting the Maximum Gather-Send Buffer Count for UDPv4 and UDPv6.

parent.message_size_max

The maximum size of a message in bytes that can be sent or received by the transport plugin.

This value must be set before the transport plugin is registered, so that Connext DDS can properly use the plugin.

parent.allow_interfaces_list

A list of strings, each identifying a range of interface addresses or an interface name. Interfaces must be specified as comma-separated strings, with each comma delimiting an interface.

For example, the following are acceptable strings:

192.168.1.1

192.168.1.*

192.168.*

192.*

ether0

If the list is non-empty, this "white" list is applied before the parent.deny_interfaces_list list. The DomainParticipant will use the resulting list of interfaces to inform its remote participant(s) about which unicast addresses may be used to contact the DomainParticipant.

The resulting list restricts reception to a particular set of interfaces for unicast UDP. Multicast output will still be sent and may be received over the interfaces in the list (if multicast is supported on the platform).

You must manage the memory of the list. The memory may be freed after the DomainParticipant is deleted.

parent.deny_interfaces_list

A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty, deny the use of these interfaces.

Interfaces must be specified as comma-separated strings, with each comma delimiting an interface.

For example, the following are acceptable strings:

192.168.1.1

192.168.1.*

192.168.*

192.*

ether0

This "black" list is applied after the parent.allow_interfaces_list list and filters out the interfaces that should not be used for receiving data.

The resulting list restricts reception to a particular set of interfaces for unicast UDP. Multicast output will still be sent and may be received over the interfaces in the list (if multicast is supported on the platform).

You must manage the memory of the list. The memory may be freed after the DomainParticipant is deleted.

parent.
allow_multicast_interfaces_list

A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty, allow the use of multicast only on these interfaces. If the list is empty, allow the use of all the allowed interfaces.

Interfaces must be specified as comma-separated strings, with each comma delimiting an interface.

This list sub-selects from the allowed interfaces that are obtained after applying the parent.allow_interfaces_list "white" list and the parent.deny_interfaces_list "black" list. From that resulting list, parent.deny_multicast_interfaces_list is applied. Multicast output will be sent and may be received over the interfaces in the resulting list (if multicast is supported on the platform).

If this list is empty, all the allowed interfaces may potentially be used for multicast.

You must manage the memory of the list. The memory may be freed after the DomainParticipant is deleted.

parent.
deny_multicast_interfaces_list

A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty, deny the use of those interfaces for multicast.

Interfaces should be specified as comma-separated strings, with each comma delimiting an interface.

This "black" list is applied after the parent.allow_multicast_interfaces_list list and filters out the interfaces that should not be used for multicast. The final resulting list will be those interfaces that—if multicast is available—will be used for multicast sends.

You must manage the memory of the list. The memory may be freed after the DomainParticipant is deleted.

send_socket_buffer_size

Size in bytes of the send buffer of a socket used for sending. On most operating systems, setsockopt() will be called to set the SENDBUF to the value of this parameter.

This value must be greater than or equal to the property,
parent.message_size_max .

The maximum value is operating system-dependent.

If NDDS_TRANSPORT_UDPV4_SOCKET_BUFFER_SIZE_OS_DEFAULT, then setsockopt() (or equivalent) will not be called to size the send buffer of the socket.

recv_socket_buffer_size

Size in bytes of the receive buffer of a socket used for receiving.

On most operating systems, setsockopt() will be called to set the RECVBUF to the value of this parameter.

This value must be greater than or equal to the property, parent.message_size_max . The maximum value is operating system-dependent.

Default: NDDS_TRANSPORT_UDPV4_MESSAGE_SIZE_MAX_DEFAULT.

If NDDS_TRANSPORT_UDPV4_SOCKET_BUFFER_SIZE_OS_DEFAULT, then setsockopt() (or equivalent) will not be called to size the receive buffer of the socket.

unicast_enabled

Allows the transport plugin to use unicast UDP for sending and receiving. By default, it will be turned on. Also by default, it will use all the allowed network interfaces that it finds up and running when the plugin is instanced.

Can be 1 (enabled) or 0 (disabled).

multicast_enabled

Allows the transport plugin to use multicast for sending and receiving. You can turn multicast on or off for this plugin. The default is that multicast is on and the plugin will use the all network interfaces allowed for multicast that it finds up and running when the plugin is instanced.

Can be 1 (enabled) or 0 (disabled).

multicast_ttl

Value for the time-to-live parameter for all multicast sends using this plugin. This is used to set the TTL of multicast packets sent by this transport plugin.

multicast_loopback_disabled

Prevents the transport plugin from putting multicast packets onto the loopback interface.

If disabled, then when sending multicast packets, do not put a copy on the loopback interface. This will prevent other applications on the same node (including itself) from receiving those packets.

This is set to 0 by default. So multicast loopback is enabled. Turning off multicast loopback (set to 1) may result in minor performance gains when using multicast.

Note: Windows CE does not support multicast loopback. This field is ignored for Windows CE targets.

ignore_loopback_interface

Prevents the transport plugin from using the IP loopback interface. Three values are allowed:

  • 0: Forces local traffic to be sent over loopback, even if a more efficient transport (such as shared memory) is installed (in which case traffic will be sent over both transports).

  • 1: Disables local traffic via this plugin. The IP loopback interface will not be used, even if no NICs are discovered. This is useful when you want applications running on the same node to use a more efficient transport (such as shared memory) instead of the IP loopback.

  • -1: Automatic. Enables local traffic via this plugin. To avoid redundant traffic, Connext DDS will selectively ignore the loopback destinations that are also reachable through shared memory.

ignore_nonup_interfaces

This property is only supported on Windows platforms with statically configured IP addresses.

It allows/disallows the use of interfaces that are not reported as UP (by the operating system) in the UDPv4 transport. Two values are allowed:

  • 0: Allow interfaces that are reported as DOWN.
  • Setting this value to 0 supports communication scenarios in which interfaces are enabled after the participant is created. Once the interfaces are enabled, discovery will not occur until the participant sends the next periodic announcement (controlled by the parameter participant_qos.discovery_config.participant_liveliness_
    assert_period
    ).

    To reduce discovery time, you may want to decrease the value of participant_liveliness_assert_period.

    For the above scenario, there is one caveat: non-UP interfaces must have a static IP assigned.

  • 1 (default): Do not allow interfaces that are reported as DOWN.

interface_poll_period

If ignore_nonup_interfaces is 0, the UDPv4 transport creates a new thread to query the status of the interfaces. The interface_poll_period specifies the polling period in milliseconds for performing this query.

This property’s value is ignored if ignore_nonup_interfaces is 1.

ignore_nonrunning_interfaces

Prevents the transport plugin from using a network interface that is not reported as RUNNING by the operating system.

The transport checks the flags reported by the operating system for each network interface upon initialization. An interface which is not reported as UP will not be used. This property allows the same check to be extended to the IFF_RUNNING flag implemented by some operating systems. The RUNNING flag is defined to mean that "all resources are allocated", and may be off if there is no link detected, e.g., the network cable is unplugged. Two values are allowed:

  • 0: Do not check the RUNNING flag when enumerating interfaces, just make sure the interface is UP.

  • 1: Check the flag when enumerating interfaces, and ignore those that are not reported as RUNNING. This can be used on some operating systems to cause the transport to ignore interfaces that are enabled but not connected to the network.

no_zero_copy

Prevents the transport plugin from doing a zero copy.

By default, this plugin will use the zero copy on OSs that offer it. While this is good for performance, it may sometime tax the OS resources in a manner that cannot be overcome by the application.

The best example is if the hardware/device driver lends the buffer to the application itself. If the application does not return the loaned buffers soon enough, the node may error or malfunction. In case you cannot reconfigure the hardware, device driver, or the OS to allow the zero-copy feature to work for your application, you may have no choice but to turn off zero-copy.

By default this is set to 0, so Connext DDS will use the zero-copy API if offered by the OS.

send_blocking

Controls the blocking behavior of send sockets. CHANGING THIS FROM THE DEFAULT CAN CAUSE SIGNIFICANT PERFORMANCE PROBLEMS. Currently two values are defined:

NDDS_TRANSPORT_UDPV4_BLOCKING_ALWAYS: Sockets are blocking (default socket options for operating system).

NDDS_TRANSPORT_UDPV4_BLOCKING_NEVER: Sockets are modified to make them non-blocking. This is not a supported configuration and may cause significant performance problems.

transport_priority_mask

Mask for the transport priority field. This is used in conjunction with transport_priority_mapping_low and transport_priority_mapping_high to define the mapping from the TRANSPORT_PRIORITY QosPolicy to the IPv4 TOS field. Defines a contiguous region of bits in the 32-bit transport priority value that is used to generate values for the IPv4 TOS field on an outgoing socket.

For example, the value 0x0000ff00 causes bits 9-16 (8 bits) to be used in the mapping. The value will be scaled from the mask range (0x0000 - 0xff00 in this case) to the range specified by low and high.

If the mask is set to zero, then the transport will not set IPv4 TOS for send sockets.

transport_priority_mapping_low

Sets the low and high values of the output range to IPv4 TOS.

These values are used in conjunction with transport_priority_mask to define the mapping from the TRANSPORT_PRIORITY QosPolicy to the IPv4 TOS field. Defines the low and high values of the output range for scaling.

Note that IPv4 TOS is generally an 8-bit value.

transport_priority_mapping_high

reuse_multicast_receive_resource

Controls whether or not to reuse receive resources. Setting this to 0 (FALSE) prevents multicast crosstalk by uniquely configuring a port and creating a receive thread for each multicast group address.

Affects Linux systems only; ignored for non-Linux systems.

protocol_overhead_max

Maximum size in bytes of protocol overhead, including headers.

This value is the maximum size, in bytes, of protocol-related overhead. Normally, the overhead accounts for UDP and IP headers. The default value is set to accommodate the most common UDP/IP header size.

Note that when parent.message_size_max plus this overhead is larger than the UDPv4 maximum message size (65535 bytes), the middleware will automatically reduce the effective message_size_max to 65535 minus this overhead.

public_address

Public IP address associated with the transport instantiation.

Setting the public IP address is only necessary to support communication over WAN that involves Network Address Translation (NAT).

Typically, the address is the public address of the IP NAT router that provides access to the WAN.

By default, the DomainParticipant creating the transport will announce the IP addresses obtained from the NICs to other DomainParticipants in the system.

When this property is set, the DomainParticipant will announce the IP address corresponding to the property value instead of the LAN IP addresses associated with the NICs.

Notes:

Setting this property is necessary, but is not a sufficient condition for sending and receiving data over the WAN. You must also configure the IP NAT router to allow UDP traffic and to map the public IP address specified by this property to the DomainParticipant's private LAN IP address. This is typically done with one of these mechanisms:

Port Forwarding: You must map the private ports used to receive discovery and user data traffic to the corresponding public ports (see DDS_RtpsWellKnownPorts_t). Public and private ports must be the same since the transport does not allow you to change the mapping.

1:1 NAT: You must add a 1:1 NAT entry that maps the public IP address specified in this property to the private LAN IP address of the DomainParticipant.

By setting this property, the DomainParticipant only announces its public IP address to other DomainParticipants. Therefore, communication with DomainParticipants within the LAN that are running on different nodes will not work unless the NAT router is configured to enable NAT reflection (hairpin NAT).

There is another way to achieve simultaneous communication with DomainParticipants running in the LAN and WAN, that does not require hairpin NAT. This way uses a gateway application such as RTI Routing Service to provide access to the WAN.

 

Properties for Builtin UDPv6 Transport

Property Name (prefix with ‘dds.transport.UDPv6.builtin.’)

Description

parent.address_bit_count

Number of bits in a 16-byte address that are used by the transport. Should be between 0 and 128.

For example, for an address range of 0-255, this address_bit_count should be set to 8. For the range of addresses used by IPv4 (4 bytes), it should be set to 32.

parent.properties_bitmap

A bitmap that defines various properties of the transport to the Connext DDS core.

Currently, the only property supported is whether or not the transport plugin will always loan a buffer when Connext DDS tries to receive a message using the plugin. This is in support of a zero-copy interface.

parent.gather_send_buffer_
count_max

Specifies the maximum number of buffers that Connext DDS can pass to the send() method of a transport plugin.

The transport plugin send() API supports a gather-send concept, where the send() call can take several discontiguous buffers, assemble and send them in a single message. This enables Connext DDS to send a message from parts obtained from different sources without first having to copy the parts into a single contiguous buffer.

However, most transports that support a gather-send concept have an upper limit on the number of buffers that can be gathered and sent. Setting this value will prevent Connext DDS from trying to gather too many buffers into a send call for the transport plugin.

Connext DDS requires all transport-plugin implementations to support a gather-send of least a minimum number of buffers. This minimum number is NDDS_TRANSPORT_PROPERTY_GATHER_SEND_BUFFER_COUNT_MIN.

parent.message_size_max

The maximum size of a message in bytes that can be sent or received by the transport plugin.

This value must be set before the transport plugin is registered, so that Connext DDS can properly use the plugin.

parent.allow_interfaces_list

A list of strings, each identifying a range of interface addresses or an interface name.

Interfaces must be specified as comma-separated strings, with each comma delimiting an interface. See Formatting Rules for IPv6 ‘Allow’ and ‘Deny’ Address Lists .

If the list is non-empty, this "white" list is applied before the parent.deny_interfaces_list list. The DomainParticipant will use the resulting list of interfaces to inform its remote participant(s) about which unicast addresses may be used to contact the DomainParticipant.

The resulting list restricts reception to a particular set of interfaces for unicast UDP. Multicast output will still be sent and may be received over the interfaces in the list (if multicast is supported on the platform).

You must manage the memory of the list. The memory may be freed after the DomainParticipant is deleted.

parent.deny_interfaces_list

A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty, deny the use of these interfaces.

Interfaces must be specified as comma-separated strings, with each comma delimiting an interface. See Formatting Rules for IPv6 ‘Allow’ and ‘Deny’ Address Lists .

This "black" list is applied after the parent.allow_interfaces_list list and filters out the interfaces that should not be used.

The resulting list restricts reception to a particular set of interfaces for unicast UDP. Multicast output will still be sent and may be received over the interfaces in the list (if multicast is supported on the platform).

You must manage the memory of the list. The memory may be freed after the DomainParticipant is deleted.

parent.
allow_multicast_interfaces_list

A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty, allow the use of multicast only these interfaces; otherwise allow the use of all the allowed interfaces.

Interfaces must be specified as comma-separated strings, with each comma delimiting an interface. See Formatting Rules for IPv6 ‘Allow’ and ‘Deny’ Address Lists .

This list sub-selects from the allowed interfaces that are obtained after applying the parent.allow_interfaces_list "white" list and the parent.deny_interfaces_list "black" list. Finally, the parent.deny_multicast_interfaces_list is applied. Multicast output will be sent and may be received over the interfaces in the resulting list (if multicast is supported on the platform).

If this list is empty, all the allowed interfaces may potentially be used for multicast.

You must manage the memory of the list. The memory may be freed after the DomainParticipant is deleted.

parent.
deny_multicast_interfaces_list

A list of strings, each identifying a range of interface addresses or an interface name. If the list is non-empty, deny the use of those interfaces for multicast.

Interfaces must be specified as comma-separated strings, with each comma delimiting an interface. See Formatting Rules for IPv6 ‘Allow’ and ‘Deny’ Address Lists .

This "black" list is applied after the parent.allow_multicast_interfaces_list list and filters out the interfaces that should not be used for multicast. Multicast output will be sent and may be received over the interfaces in the resulting list (if multicast is supported on the platform).

You must manage the memory of the list. The memory may be freed after the DomainParticipant is deleted.

send_socket_buffer_size

Size in bytes of the send buffer of a socket used for sending.

On most operating systems, setsockopt() will be called to set the SENDBUF to the value of this parameter.

This value must be greater than or equal to parent.message_size_max. The maximum value is operating system-dependent.

If NDDS_TRANSPORT_UDPV6_SOCKET_BUFFER_SIZE_OS_DEFAULT, then setsockopt() (or equivalent) will not be called to size the send buffer of the socket.

recv_socket_buffer_size

Size in bytes of the receive buffer of a socket used for receiving.

On most operating systems, setsockopt() will be called to set the RECVBUF to the value of this parameter.

This value must be greater than or equal to parent.message_size_max. The maximum value is operating system-dependent.

If NDDS_TRANSPORT_UDPV6_SOCKET_BUFFER_SIZE_OS_DEFAULT, then setsockopt() (or equivalent) will not be called to size the receive buffer of the socket.

unicast_enabled

Allows the transport plugin to use unicast UDP for sending and receiving. By default, it will be turned on (1). Also by default, it will use all the allowed network interfaces that it finds up and running when the plugin is instanced.

Can be 1 (enabled) or 0 (disabled).

multicast_enabled

Allows the transport plugin to use multicast for sending and receiving.

You can turn multicast UDP on or off for this plugin. By default, it will be turned on (1). Also by default, it will use the all network interfaces allowed for multicast that it finds up and running when the plugin is instanced.

Can be 1 (enabled) or 0 (disabled).

multicast_ttl

Value for the time-to-live parameter for all multicast sends using this plugin.

This is used to set the TTL of multicast packets sent by this transport plugin

multicast_loopback_disabled

Prevents the transport plugin from putting multicast packets onto the loopback interface.

If disabled, then when sending multicast packets, Connext DDS will not put a copy on the loopback interface. This will prevent applications on the same node (including itself) from receiving those packets.

This is set to 0 by default, meaning multicast loopback is enabled. Disabling multicast loopback off (setting this value to 1) may result in minor performance gains when using multicast.

ignore_loopback_interface

Prevents the transport plugin from using the IP loopback interface. Three values are allowed:

  • 0: Enable local traffic via this plugin. This plugin will only use and report the IP loopback interface if there are no other network interfaces (NICs) up on the system.

  • 1: Disable local traffic via this plugin. Do not use the IP loopback interface even if no NICs are discovered. This is useful when you want applications running on the same node to use a more efficient plugin like Shared Memory instead of the IP loopback.

  • -1: Automatic. Enables local traffic via this plugin. To avoid redundant traffic, Connext DDS will selectively ignore the loopback destinations that are also reachable through shared memory.

ignore_nonrunning_interfaces

Prevents the transport plugin from using a network interface that is not reported as RUNNING by the operating system.

The transport checks the flags reported by the operating system for each network interface upon initialization. An interface which is not reported as UP will not be used. This property allows the same check to be extended to the IFF_RUNNING flag implemented by some operating systems. The RUNNING flag is defined to mean that "all resources are allocated", and may be off if there is no link detected, e.g., the network cable is unplugged. Two values are allowed:

  • 0: Do not check the RUNNING flag when enumerating interfaces, just make sure the interface is UP.

  • 1: Check the flag when enumerating interfaces, and ignore those that are not reported as RUNNING. This can be used on some operating systems to cause the transport to ignore interfaces that are enabled but not connected to the network.

no_zero_copy

Prevents the transport plugin from doing a zero copy.

By default, this plugin will use the zero copy on OSs that offer it. While this is good for performance, it may sometime tax the OS resources in a manner that cannot be overcome by the application.

The best example is if the hardware/device driver lends the buffer to the application itself. If the application does not return the loaned buffers soon enough, the node may error or malfunction. In case you cannot reconfigure the H/W, device driver, or the OS to allow the zero-copy feature to work for your application, you may have no choice but to turn off zero-copy.

By default this is set to 0, so Connext DDS will use the zero-copy API if offered by the OS.

send_blocking

Controls the blocking behavior of send sockets. CHANGING THIS FROM THE DEFAULT CAN CAUSE SIGNIFICANT PERFORMANCE PROBLEMS. Currently two values are defined:

  • NDDS_TRANSPORT_UDPV4_BLOCKING_ALWAYS: Sockets are blocking (default socket options for Operating System).

  • NDDS_TRANSPORT_UDPV4_BLOCKING_NEVER: Sockets are modified to make them non-blocking. This is not a supported configuration and may cause significant performance problems.

enable_v4mapped

Specifies whether the UDPv6 transport will process IPv4 addresses.

Set this to 1 to turn on processing of IPv4 addresses. Note that this may make it incompatible with use of the UDPv4 transport within the same DomainParticipant.

transport_priority_mask

Sets a mask for use of transport priority field.

If transport priority mapping is supported on the platform1See the Platform Notes to find out if the transport priority is supported on a specific platform., this mask is used in conjunction with transport_priority_mapping_low and transport_priority_mapping_high to define the mapping from the DDS transport priority TRANSPORT_PRIORITY QosPolicy to the IPv6 TCLASS field.

Defines a contiguous region of bits in the 32-bit transport priority value that is used to generate values for the IPv6 TCLASS field on an outgoing socket.

For example, the value 0x0000ff00 causes bits 9-16 (8 bits) to be used in the mapping. The value will be scaled from the mask range (0x0000 - 0xff00 in this case) to the range specified by low and high.

If the mask is set to zero, then the transport will not set IPv6 TCLASS for send sockets.

transport_priority_mapping_low

Sets the low and high values of the output range to IPv6 TCLASS.

These values are used in conjunction with transport_priority_mask to define the mapping from DDS transport priority to the IPv6 TCLASS field. Defines the low and high values of the output range for scaling.

Note that IPv6 TCLASS is generally an 8-bit value.

transport_priority_mapping_high

 

Properties for Builtin Shared-Memory Transport

Property Name
(prefix with ‘dds.transport.shmem.builtin.’)

Property Value Description

parent.address_bit_count

Number of bits in a 16-byte address that are used by the transport. Should be between 0 and 128.

For example, for an address range of 0-255, this address_bit_count should be set to 8. For the range of addresses used by IPv4 (4 bytes), it should be set to 32.

parent.properties_bitmap

A bitmap that defines various properties of the transport to the Connext DDS core.

Currently, the only property supported is whether or not the transport plugin will always loan a buffer when Connext DDS tries to receive a message using the plugin. This is in support of a zero-copy interface.

parent.gather_send_buffer_
count_max

Specifies the maximum number of buffers that Connext DDS can pass to the send() method of a transport plugin.

The transport plugin send() API supports a gather-send concept, where the send() call can take several discontiguous buffers, assemble and send them in a single message. This enables Connext DDS to send a message from parts obtained from different sources without first having to copy the parts into a single contiguous buffer.

However, most transports that support a gather-send concept have an upper limit on the number of buffers that can be gathered and sent. Setting this value will prevent Connext DDS from trying to gather too many buffers into a send call for the transport plugin.

Connext DDS requires all transport-plugin implementations to support a gather-send of least a minimum number of buffers. This minimum is NDDS_TRANSPORT_PROPERTY_GATHER_SEND_BUFFER_COUNT_MIN.

parent.message_size_max

The maximum size of a message in bytes that can be sent or received by the transport plugin.

This value must be set before the transport plugin is registered, so that Connext DDS can properly use the plugin.

parent.allow_interfaces_list

Not applicable to the Shared-Memory Transport

parent.deny_interfaces_list

parent.
allow_multicast_interfaces_list

parent.
deny_multicast_interfaces_list

received_message_count_max

Number of messages that can be buffered in the receive queue. This is the maximum number of messages that can be buffered in a RecvResource of the Transport Plugin. This does not guarantee that the Transport-Plugin will actually be able to buffer received_message_count_max messages of the maximum size set in parent.message_size_max.

The total number of bytes that can be buffered for a RecvResource is actually controlled by receive_buffer_size.

receive_buffer_size

The total number of bytes that can be buffered in the receive queue.

This number controls how much memory is allocated by the plugin for the receive queue (on a per RecvResource basis). The actual number of bytes allocated is:

size = receive_buffer_size + message_size_max +
received_message_count_max * fixedOverhead

where fixedOverhead is some small number of bytes used by the queue data structure.

If receive_buffer_size <
(message_size_max * received_message_count_max), the transport plugin will not be able to store received_message_count_max messages of size message_size_max.

If receive_buffer_size >
(message_size_max * received_message_count_max), then there will be memory allocated that cannot be used by the plugin and thus wasted.

To optimize memory usage, specify a receive queue size less than that required to hold the maximum number of messages which are all of the maximum size.

In most situations, the average message size may be far less than the maximum message size. So for example, if the maximum message size is 64K bytes, and you configure the plugin to buffer at least 10 messages, then 640K bytes of memory would be needed if all messages were 64K bytes. Should this be desired, then receive_buffer_size should be set to 640K bytes.

However, if the average message size is only 10K bytes, then you could set the receive_buffer_size to 100K bytes. This allows you to optimize the memory usage of the plugin for the average case and yet allow the plugin to handle the extreme case.

The queue will always be able to hold 1 message of message_size_max bytes, regardless of the value of receive_buffer_size.

© 2016 RTI