3.1.2.2. eProsima Extensions

The eProsima QoS Policies extensions are those that allow changing the values of the RTPS layer configurable settings.

3.1.2.2.1. DataSharingQosPolicy

This additional QoS allows configuring the data-sharing delivery communication between a writer and a reader. Please, see Data-sharing delivery for a description of the data-sharing delivery functionality.

List of QoS Policy data members:

Data Member	Type	Accessor	Default Value
Data-sharing kind	DataSharingKind	kind()	AUTO
Shared memory directory	string	shm_directory()	Empty string
Maximum domain number	uint32_t	max_domains()	0 (unlimited)
Data-sharing domain IDs	vector<uint64_t>	domain_ids()	Empty
Data-sharing listener thread settings	ThreadSettings	data_sharing_listener_thread()

• Data-sharing kind: Specifies the behavior of data-sharing delivery. See DataSharingKind for a description of possible values and their effect.

• Shared memory directory: The directory that will be used for the memory-mapped files. If none is configured, then the system default directory will be used.

• Maximum domain number: Establishes the maximum number of data-sharing domain IDs in the local or remote endpoints. Domain IDs are exchanged between data-sharing delivery compatible endpoints. If this value is lower that the size of the list for any remote endpoint, the matching may fail. A value of zero represents unlimited number of IDs.

• Data sharing domain IDs: The list of data-sharing domain IDs configured for the current DataWriter or DataReader. If no ID is provided, the system will create a unique one for the current machine.

• Data-sharing listener thread settings: The ThreadSettings for the data-sharing thread dedicated to listening for incoming traffic.

Note

This QoS Policy concerns to DataWriter and DataReader entities.
It cannot be changed on enabled entities.

DataSharingKind

There are three possible values (see DataSharingKind):

• OFF: The data-sharing delivery is disabled. No communication will be performed using data-sharing delivery functionality.

• ON: The data-sharing delivery is manually enabled. An error will occur if the current topic is not compatible with data-sharing delivery. Communication with remote entities that share at least one data-sharing domain ID will be done using data-sharing delivery functionality.

• AUTO: data-sharing delivery will be activated if the current topic is compatible with data-sharing, and deactivated if not.

Data-sharing configuration helper functions

In order to set the data-sharing delivery configuration, one of the following helper member functions must be used. There is one for each DataSharingKind flavor:

Function	Resulting DataSharingKind	Shared memory directory	Data sharing domain IDs
automatic()	AUTO	Optional	Optional
on()	ON	Mandatory	Optional
off()	OFF	N/A	N/A

Instead of defining the data-sharing domain IDs on these helper functions, you can add them later with the add_domain_id() function. Beware that adding a new domain ID counts as modifying the QosPolicy, so it must be done before the entity is enabled.

Example

C++XML

DataSharingQosPolicy datasharing;

// Configure the DataSharing as AUTO with two user-defined IDs
std::vector<uint16_t> ids;
ids.push_back(0x1234);
ids.push_back(0xABCD);
datasharing.automatic(ids);

// Alternatively, configure with no IDs and add them afterwards
datasharing.automatic();
datasharing.add_domain_id(uint16_t(0x1234));
datasharing.add_domain_id(uint16_t(0xABCD));

// Or you can leave the IDs empty and the system will create one for you
// unique for the current machine
datasharing.automatic();

// [OPTIONAL] ThreadSettings for listening thread
datasharing.data_sharing_listener_thread(eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1});

3.1.2.2.2. DisablePositiveACKsQosPolicy

This additional QoS allows reducing network traffic when strict reliable communication is not required and bandwidth is limited. It consists in changing the default behavior by which positive acks are sent from readers to writers. Instead, only negative acks will be sent when a reader is missing a sample, but writers will keep data for an adjustable time before considering it as acknowledged. See DisablePositiveACKsQosPolicy.

List of QoS Policy data members:

Data Member Name	Type	Default Value
enabled	bool	false
duration	Duration_t	c_TimeInfinite

• enabled: Specifies if the QoS is enabled or not. If it is true means that the positive acks are disabled and the DataReader only sends negative acks. Otherwise, both positive and negative acks are sent.

• duration: State the duration that the DataWriters keep the data before considering it as acknowledged. This value does not apply to DataReaders.

Note

This QoS Policy concerns to DataWriter and DataReader entities.
The enabled Data Member cannot be modified on enabled entities. Thus, this feature must be set up during initialization. Only the duration Data Member can be modified at runtime.

Warning

For DataWriters and DataReaders to match, they must follow the compatibility rule. See Compatibility Rule for further details.

Compatibility Rule

To maintain the compatibility between DisablePositiveACKsQosPolicy in DataReaders and DataWriters, the DataReader cannot have this QoS enabled if the DataWriter have it disabled.

Table with the possible combinations:

DataWriter enabled value	DataReader enabled value	Compatibility
true	true	Yes
true	false	Yes
false	true	No
false	false	Yes

Example

C++

DisablePositiveACKsQosPolicy disable_acks;
//The DisablePositiveACKsQosPolicy is default constructed with enabled = false
//Change enabled to true
disable_acks.enabled = true;
//The DisablePositiveACKsQosPolicy is default constructed with infinite duration
//Change the duration to 1 second
disable_acks.duration = {1, 0};

XML

<data_writer profile_name="writer_xml_conf_disable_positive_acks_profile">
    <qos>
        <disablePositiveAcks>
            <enabled>true</enabled>
            <duration>
                <sec>1</sec>
            </duration>
        </disablePositiveAcks>
    </qos>
</data_writer>

<data_reader profile_name="reader_xml_conf_disable_positive_acks_profile">
    <qos>
        <disablePositiveAcks>
            <enabled>true</enabled>
        </disablePositiveAcks>
    </qos>
</data_reader>

3.1.2.2.3. FlowControllersQos

This QoS configures the list of flow controllers of a participant, so they can later be used on its DataWriters. It is a vector of shared pointers to FlowControllerDescriptor, which has the following fields:

Data Member Name	Type	Default Value
name	const char *
scheduler	FlowControllerSchedulerPolicy	FIFO_SCHED_POLICY-api|
max_bytes_per_period	int32_t	0 (i.e. infinite)
period_ms	uint64_t	100
sender_thread	ThreadSettings

Please refer to Flow Controllers section for more information.

Note

This QoS Policy concerns to DomainParticipant entities.
It cannot be changed on enabled entities.

3.1.2.2.4. ParticipantResourceLimitsQos

This QoS configures allocation limits and the use of physical memory for internal resources. See ParticipantResourceLimitsQos.

List of QoS Policy data members:

Data Member Name	Type
locators	RemoteLocatorsAllocationAttributes
participants	ResourceLimitedContainerConfig
readers	ResourceLimitedContainerConfig
writers	ResourceLimitedContainerConfig
send_buffers	SendBuffersAllocationAttributes
data_limits	VariableLengthDataLimits
content_filter	ContentFilterProperty::AllocationConfiguration

• locators: Defines the limits for collections of remote locators.

• participants: Specifies the allocation behavior and limits for collections dependent on the total number of participants.

• readers: Specifies the allocation behavior and limits for collections dependent on the total number of readers per participant.

• writers: Specifies the allocation behavior and limits for collections dependent on the total number of writers per participant.

• send_buffers: Defines the allocation behavior and limits for the send buffer manager.

• data_limits: States the limits for variable-length data.

• content_filter: States the limits for content-filter discovery information.

Note

This QoS Policy concerns to DomainParticipant entities.
It cannot be changed on enabled entities.

RemoteLocatorsAllocationAttributes

This structure holds the limits for the remote locators’ collections. See RemoteLocatorsAllocationAttributes.

List of structure members:

Member Name	Type	Default Value
max_unicast_locators	size_t	4
max_multicast_locators	size_t	1

• max_unicast_locators: This member controls the maximum number of unicast locators to keep for each discovered remote entity. It is recommended to use the highest number of local addresses found on all the systems belonging to the same domain.

• max_multicast_locators: This member controls the maximum number of multicast locators to keep for each discovered remote entity. The default value is usually enough, as it does not make sense to add more than one multicast locator per entity.

ResourceLimitedContainerConfig

This structure holds the limits of a resource limited collection, as well as the allocation configuration, which can be fixed size or dynamic size.

List of structure members:

Member Name	Type	Default Value
initial	size_t	0
maximum	size_t	std::numeric_limits<size_t>::max()
increment	size_t	1 (dynamic size), 0 (fixed size)

• initial: Indicates the number of elements to preallocate in the collection.

• maximum: Specifies the maximum number of elements allowed in the collection.

• increment: States the number of items to add when the reserved capacity limit is reached. This member has a different default value depending on the allocation configuration chosen.

SendBuffersAllocationAttributes

This structure holds the limits for the allocations of the send buffers. See SendBuffersAllocationAttributes.

List of structure members:

Member Name	Type	Default Value
preallocated_number	size_t	0
dynamic	bool	false

• preallocated_number: This member controls the initial number of send buffers to be allocated. The default value will perform an initial guess of the number of buffers required, based on the number of threads from which a send operation could be started.

• dynamic: This member controls how the buffer manager behaves when a send buffer is not available. When true, a new buffer will be created. Otherwise, it will wait for a buffer to be returned.

VariableLengthDataLimits

This structure holds the limits for variable-length data. See VariableLengthDataLimits.

List of structure members:

Member Name	Type	Default Value
max_properties	size_t	0
max_user_data	size_t	0
max_partitions	size_t	0

• max_properties: Defines the maximum size, in octets, of the properties data in the local or remote participant.

• max_user_data: Establishes the maximum size, in octets, of the user data in the local or remote participant.

• max_partitions: States the maximum size, in octets, of the partitions data in the local or remote participant.

ContentFilterProperty::AllocationConfiguration

This structure holds the limits for content-filter related discovery information. See ContentFilterProperty::AllocationConfiguration.

List of structure members:

Member Name	Type	Default Value
expression_initial_size	size_t	0
expression_parameters	ResourceLimitedContainerConfig	{0, 100, 1}

• expression_initial_size: Preallocated size of the filter expression.

• expression_parameters: Allocation configuration for the list of expression parameters.

Example

C++

ParticipantResourceLimitsQos participant_limits;
//Set the maximum size of participant resource limits collection to 3 and it allocation configuration to fixed size
participant_limits.participants = eprosima::fastrtps::ResourceLimitedContainerConfig::fixed_size_configuration(
    3u);
//Set the maximum size of reader's resource limits collection to 2 and its allocation configuration to fixed size
participant_limits.readers = eprosima::fastrtps::ResourceLimitedContainerConfig::fixed_size_configuration(2u);
//Set the maximum size of writer's resource limits collection to 1 and its allocation configuration to fixed size
participant_limits.writers = eprosima::fastrtps::ResourceLimitedContainerConfig::fixed_size_configuration(1u);
//Set the maximum size of the partition data to 256
participant_limits.data_limits.max_partitions = 256u;
//Set the maximum size of the user data to 256
participant_limits.data_limits.max_user_data = 256u;
//Set the maximum size of the properties data to 512
participant_limits.data_limits.max_properties = 512u;
//Set the preallocated filter expression size to 512
participant_limits.content_filter.expression_initial_size = 512u;
//Set the maximum number of expression parameters to 4 and its allocation configuration to fixed size
participant_limits.content_filter.expression_parameters =
        eprosima::fastrtps::ResourceLimitedContainerConfig::fixed_size_configuration(4u);

XML

<!--
<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
-->
    <participant profile_name="participant_alloc_qos_example">
        <rtps>
            <allocation>
                <!-- We know we have 3 participants on the domain -->
                <total_participants>
                    <initial>3</initial>
                    <maximum>3</maximum>
                    <increment>0</increment>
                </total_participants>
                <!-- We know we have at most 2 readers on each participant -->
                <total_readers>
                    <initial>2</initial>
                    <maximum>2</maximum>
                    <increment>0</increment>
                </total_readers>
                <!-- We know we have at most 1 writer on each participant -->
                <total_writers>
                    <initial>1</initial>
                    <maximum>1</maximum>
                    <increment>0</increment>
                </total_writers>
                <max_partitions>256</max_partitions>
                <max_user_data>256</max_user_data>
                <max_properties>512</max_properties>

                <!-- content_filter cannot be configured using XML (yet) -->
            </allocation>
        </rtps>
    </participant>

3.1.2.2.5. PropertyPolicyQos

This additional QoS Policy (PropertyPolicyQos) stores name/value pairs that can be used to configure certain DDS settings that cannot be configured directly using an standard QoS Policy. For the complete list of settings that can be configured with this QoS Policy, please refer to PropertyPolicyQos Options.

This QoS also allows to add custom user properties that could be sent to the external entities. This could be done by setting as true the propagate value of the Property.

Example

C++

PropertyPolicyQos property_policy;
//Add new property for the Auth:PKI-DH plugin
property_policy.properties().emplace_back("dds.sec.auth.plugin", "builtin.PKI-DH");
//Add new property for the Access:Permissions plugin
property_policy.properties().emplace_back(eprosima::fastrtps::rtps::Property("dds.sec.access.plugin",
        "builtin.Access-Permissions"));

//Add new user custom property to send to external Participants
property_policy.properties().emplace_back("Custom Property Name", "Custom value", true);

XML

<participant profile_name="secure_participant_conf_all_plugin_xml_profile">
    <rtps>
        <propertiesPolicy>
            <properties>
                <!-- Activate Auth:PKI-DH plugin -->
                <property>
                    <name>dds.sec.auth.plugin</name>
                    <value>builtin.PKI-DH</value>
                </property>

                <!-- Activate Access:Permissions plugin -->
                <property>
                    <name>dds.sec.access.plugin</name>
                    <value>builtin.Access-Permissions</value>
                </property>

                <!-- User Custom Property to send externally -->
                <property>
                    <name>Custom Property Name</name>
                    <value>Custom value</value>
                    <propagate>true</propagate>
                </property>
            </properties>
        </propertiesPolicy>
    </rtps>
</participant>

3.1.2.2.6. PublishModeQosPolicy

This QoS Policy configures how the DataWriter sends the data. See PublishModeQosPolicy.

It also configures the name of the flow controller to use when asynchronous publishing is used. It should be the name of a flow controller registered on the creation of the DomainParticipant. See FlowControllersQos.

List of QoS Policy data members:

Data Member Name	Type	Default Value
kind	PublishModeQosPolicyKind	SYNCHRONOUS_PUBLISH_MODE
flow_controller_name	const char *	FASTDDS_FLOW_CONTROLLER_DEFAULT

Note

This QoS Policy concerns to DataWriter entities.
It cannot be changed on enabled entities.

PublishModeQosPolicyKind

There are two possible values (see PublishModeQosPolicyKind):

• SYNCHRONOUS_PUBLISH_MODE: The data is sent in the context of the user thread that calls the write operation.

• ASYNCHRONOUS_PUBLISH_MODE: An internal thread takes the responsibility of sending the data asynchronously. The write operation returns before the data is actually sent.

Example

C++

PublishModeQosPolicy publish_mode;
//The PublishModeQosPolicy is default constructed with kind = SYNCHRONOUS
//Change the kind to ASYNCHRONOUS
publish_mode.kind = ASYNCHRONOUS_PUBLISH_MODE;

XML

<data_writer profile_name="writer_profile_qos_publishmode">
    <qos>
        <publishMode>
            <kind>ASYNCHRONOUS</kind>
        </publishMode>
    </qos>
</data_writer>

3.1.2.2.7. ReaderResourceLimitsQos

This QoS Policy states the limits for the matched DataWriters’ resource limited collections based on the maximum number of DataWriters that are going to match with the DataReader. See ReaderResourceLimitsQos.

List of QoS Policy data members:

Data Member Name	Type
matched_publisher_allocation	ResourceLimitedContainerConfig

Note

This QoS Policy concerns to DataReader entities.
It cannot be changed on enabled entities.

Example

C++

ReaderResourceLimitsQos reader_limits;
//Set the maximum size for writer matched resource limits collection to 1 and its allocation configuration to fixed size
reader_limits.matched_publisher_allocation =
        eprosima::fastrtps::ResourceLimitedContainerConfig::fixed_size_configuration(1u);

XML

<data_reader profile_name="alloc_qos_example_sub">
    <!-- we know we will only have one matching publisher -->
    <matchedPublishersAllocation>
        <initial>1</initial>
        <maximum>1</maximum>
        <increment>0</increment>
    </matchedPublishersAllocation>
</data_reader>

3.1.2.2.8. RTPSEndpointQos

This QoS Policy configures the aspects of an RTPS endpoint, such as the list of locators, the identifiers, and the history memory policy. See RTPSEndpointQos.

List of QoS Policy data members:

Data Member Name	Type	Default Value
unicast_locator_list	LocatorList	Empty List
multicast_locator_list	LocatorList	Empty List
remote_locator_list	LocatorList	Empty List
external_unicast_locators	ExternalLocators	Empty
ignore_non_matching_locators	bool	false
user_defined_id	int16_t	-1
entity_id	int16_t	-1
history_memory_policy	MemoryManagementPolicy	PREALLOCATED_WITH_REALLOC_MEMORY_MODE

• unicast_locator_list: Defines the list of unicast locators associated to the DDS Entity. DataReaders and DataWriters inherit the list of unicast locators set in the DomainParticipant, but it can be changed by means of this QoS.

• multicast_locator_list: Stores the list of multicast locators associated to the DDS Entity. By default, DataReaders and DataWriters do not use any multicast locator, but it can be changed by means of this QoS.

• remote_locator_list: States the list of remote locators associated to the DDS Entity.

• external_unicast_locators: Defines the External Locators to announce for the communication with this DDS Entity.

• ignore_non_matching_locators: Defines whether to ignore locators received on announcements from other DDS entities when they don’t match with any of the locators announced by this DDS Entity.

• user_defined_id: Establishes the unique identifier used for StaticEndpointDiscovery.

• entity_id: The user can specify the identifier for the endpoint.

• history_memory_policy: Indicates the way the memory is managed in terms of dealing with the CacheChanges.

Note

This QoS Policy concerns to DataWriter and DataReader entities.
It cannot be changed on enabled entities.

MemoryManagementPolicy

There are four possible values (see MemoryManagementPolicy):

• PREALLOCATED_MEMORY_MODE: This option sets the size to the maximum of each data type. It produces the largest memory footprint but the smallest allocation count.

• PREALLOCATED_WITH_REALLOC_MEMORY_MODE: This option set the size to the default for each data type and it requires reallocation when a bigger message arrives. It produces a lower memory footprint at the expense of increasing the allocation count.

• DYNAMIC_RESERVE_MEMORY_MODE: This option allocates the size dynamically at the time of message arrival. It produces the least memory footprint but the highest allocation count.

• DYNAMIC_REUSABLE_MEMORY_MODE: This option is similar to DYNAMIC_RESERVE_MEMORY_MODE, but the allocated memory is reused for future messages.

Example

C++

RTPSEndpointQos endpoint;
//Add new unicast locator with port 7800
eprosima::fastrtps::rtps::Locator_t new_unicast_locator;
new_unicast_locator.port = 7800;
endpoint.unicast_locator_list.push_back(new_unicast_locator);
//Add new multicast locator with IP 239.255.0.4 and port 7900
eprosima::fastrtps::rtps::Locator_t new_multicast_locator;
eprosima::fastrtps::rtps::IPLocator::setIPv4(new_multicast_locator, "239.255.0.4");
new_multicast_locator.port = 7900;
endpoint.multicast_locator_list.push_back(new_multicast_locator);
// Add an external locator with IP 100.100.100.10, port 12345, mask 24, externality 1, and cost 0
eprosima::fastdds::rtps::LocatorWithMask external_locator;
external_locator.kind = LOCATOR_KIND_UDPv4;
external_locator.port = 12345;
external_locator.mask(24);
endpoint.external_unicast_locators[1][0].push_back(external_locator);
// Drop non matching locators
endpoint.ignore_non_matching_locators = true;
//Set 3 as user defined id
endpoint.user_defined_id = 3;
//Set 4 as entity id
endpoint.entity_id = 4;
//The RTPSEndpointQos is default constructed with history_memory_policy = PREALLOCATED
//Change the history_memory_policy to DYNAMIC_RESERVE
endpoint.history_memory_policy = eprosima::fastrtps::rtps::DYNAMIC_RESERVE_MEMORY_MODE;

XML

<data_writer profile_name="writer_xml_conf_unicast_locators_profile">
    <userDefinedID>3</userDefinedID>
    <entityID>2</entityID> <!-- Int16 -->
    <unicastLocatorList>
        <locator>
            <udpv4>
                <port>7800</port>
            </udpv4>
        </locator>
    </unicastLocatorList>
    <multicastLocatorList>
        <locator>
            <udpv4>
                <address>239.255.0.4</address>
                <port>7900</port>
            </udpv4>
        </locator>
    </multicastLocatorList>
    <external_unicast_locators>
        <udpv4 externality="1" cost="0" mask="24">
            <address>100.100.100.10</address>
            <port>12345</port>
        </udpv4>
    </external_unicast_locators>
    <ignore_non_matching_locators>true</ignore_non_matching_locators>
    <!-- The history memory policy is changed to DYNAMIC_RESERVE -->
    <historyMemoryPolicy>DYNAMIC</historyMemoryPolicy>
</data_writer>

<data_reader profile_name="reader_xml_conf_unicast_locators_profile">
    <userDefinedID>5</userDefinedID>
    <entityID>4</entityID> <!-- Int16 -->
    <unicastLocatorList>
        <locator>
            <udpv4>
                <port>7800</port>
            </udpv4>
        </locator>
    </unicastLocatorList>
    <multicastLocatorList>
        <locator>
            <udpv4>
                <address>239.255.0.4</address>
                <port>7900</port>
            </udpv4>
        </locator>
    </multicastLocatorList>
    <external_unicast_locators>
        <udpv4 externality="1" cost="0" mask="24">
            <address>100.100.100.10</address>
            <port>12345</port>
        </udpv4>
    </external_unicast_locators>
    <ignore_non_matching_locators>true</ignore_non_matching_locators>
    <historyMemoryPolicy>PREALLOCATED_WITH_REALLOC</historyMemoryPolicy>
</data_reader>

3.1.2.2.9. RTPSReliableReaderQos

This RTPS QoS Policy allows the configuration of several RTPS reliable reader’s aspects. See RTPSReliableReaderQos.

List of QoS Policy data members:

Data Member Name	Type
times	ReaderTimes
disable_positive_ACKs	DisablePositiveACKsQosPolicy

• times: Defines the duration of the RTPSReader events. See ReaderTimes for further details.

• disable_positive_ACKs: Configures the settings to disable the positive acks. See DisablePositiveACKsQosPolicy for further details.

Note

This QoS Policy concerns to DataReader entities.
Only the duration Data Member of the DisablePositiveACKsQosPolicy and the times Data Member can be modified on enabled entities.

ReaderTimes

This structure defines the times associated with the Reliable Readers’ events. See ReaderTimes.

List of structure members:

Member Name	Type	Default Value
initialAcknackDelay	Duration_t	70 ms
heartbeatResponseDelay	Duration_t	5 ms

• initialAcknackDelay: Defines the duration of the initial acknack delay.

• heartbeatResponseDelay: Establishes the duration of the delay applied when a heartbeat message is received.

Example

C++

RTPSReliableReaderQos reliable_reader_qos;
//The RTPSReliableReaderQos is default constructed with initialAcknackDelay = 70 ms
//Change the initialAcknackDelay to 70 nanoseconds
reliable_reader_qos.times.initialAcknackDelay = {0, 70};
//The RTPSReliableWriterQos is default constructed with heartbeatResponseDelay = 5 ms
//Change the heartbeatResponseDelay to 5 nanoseconds
reliable_reader_qos.times.heartbeatResponseDelay = {0, 5};
//You can also change the DisablePositiveACKsQosPolicy. For further details see DisablePositiveACKsQosPolicy section.
reliable_reader_qos.disable_positive_ACKs.enabled = true;

XML

<data_reader profile_name="sub_profile_name">
    <times> <!-- readerTimesType -->
        <initialAcknackDelay> <!-- DURATION -->
            <nanosec>70</nanosec>
        </initialAcknackDelay>
        <heartbeatResponseDelay> <!-- DURATION -->
            <nanosec>5</nanosec>
        </heartbeatResponseDelay>
    </times>
    <!--You can also change the values of DisablePositiveACKsQosPolicy.-->
    <!--See DisablePositiveACKsQosPolicy section for further details-->
</data_reader>

3.1.2.2.10. RTPSReliableWriterQos

This RTPS QoS Policy allows the configuration of several RTPS reliable writer’s aspects. See RTPSReliableWriterQos.

List of QoS Policy data members:

Data Member Name	Type
times	WriterTimes
disable_positive_acks	DisablePositiveACKsQosPolicy
disable_heartbeat_piggyback	DisableHeartbeatPiggyback

• times: Defines the duration of the RTPSWriter events. See WriterTimes for further details.

• disable_positive_acks: Configures the settings to disable the positive acks. See DisablePositiveACKsQosPolicy for further details.

• disable_heartbeat_piggyback: Configures the settings to disable the heartbeat piggyback mechanism. See DisableHeartbeatPiggyback for further details.

Note

This QoS Policy concerns to DataWriter entities.
Only the duration Data Member of the DisablePositiveACKsQosPolicy and the times Data Member can be modified on enabled entities.

WriterTimes

This structure defines the times associated with the Reliable Writers’ events.

List of structure members:

Member Name	Type	Default Value
initialHeartbeatDelay	Duration_t	12ms
heartbeatPeriod	Duration_t	3s
nackResponseDelay	Duration_t	5ms
nackSupressionDuration	Duration_t	0s

• initialHeartbeatDelay: Defines duration of the initial heartbeat delay.

• heartbeatPeriod: Specifies the interval between periodic heartbeats.

• nackResponseDelay: Establishes the duration of the delay applied to the response of an ACKNACK message.

• nackSupressionDuration: The RTPSWriter ignores the nack messages received after sending the data until the duration time elapses.

DisableHeartbeatPiggyback

Besides sending heartbeats periodically using the heartbeatPeriod (see WriterTimes), reliable DataWriters also use a mechanism to append a heartbeat submessage in the same message where data is being delivered to the DataReaders. This mechanism acts in specific situations where the reliable communication state must be up to date to maintain optimal communication:

• When the DataWriter sends as many bytes to the socket as the length of the socket buffer, a heartbeat submessage is appended after the last data.

• When the DataWriter’s history is full, the DataWriter starts to append heartbeat submessages after each data.

This mechanism can be disabled using this policy.

Example

C++

RTPSReliableWriterQos reliable_writer_qos;
//The RTPSReliableWriterQos is default constructed with initialHeartbeatDelay = 12 ms
//Change the initialHeartbeatDelay to 20 nanoseconds
reliable_writer_qos.times.initialHeartbeatDelay = {0, 20};
//The RTPSReliableWriterQos is default constructed with heartbeatPeriod = 3 s
//Change the heartbeatPeriod to 5 seconds
reliable_writer_qos.times.heartbeatPeriod = {5, 0};
//The RTPSReliableWriterQos is default constructed with nackResponseDelay = 5 ms
//Change the nackResponseDelay to 10 nanoseconds
reliable_writer_qos.times.nackResponseDelay = {0, 10};
//The RTPSReliableWriterQos is default constructed with nackSupressionDuration = 0 s
//Change the nackSupressionDuration to 20 nanoseconds
reliable_writer_qos.times.nackSupressionDuration = {0, 20};
//You can also change the DisablePositiveACKsQosPolicy. For further details see DisablePositiveACKsQosPolicy section.
reliable_writer_qos.disable_positive_acks.enabled = true;
//The RTPSReliableWriterQos is default constructed with disable_heartbeat_piggyback = false
//Disable the heartbeat piggyback mechanism.
reliable_writer_qos.disable_heartbeat_piggyback = true;

XML

<data_writer profile_name="pub_profile_name">
    <times> <!-- writerTimesType -->
        <initialHeartbeatDelay> <!-- DURATION -->
            <nanosec>20</nanosec>
        </initialHeartbeatDelay>
        <heartbeatPeriod> <!-- DURATION -->
            <sec>5</sec>
        </heartbeatPeriod>
        <nackResponseDelay> <!-- DURATION -->
            <nanosec>10</nanosec>
        </nackResponseDelay>
        <nackSupressionDuration> <!-- DURATION -->
            <nanosec>20</nanosec>
        </nackSupressionDuration>
    </times>

    <!--You can also change the values of DisablePositiveACKsQosPolicy.-->
    <!--See DisablePositiveACKsQosPolicy section for further details-->
    <qos>
        <!--Disable heartbeat piggyback mechanism.-->
        <disable_heartbeat_piggyback>true</disable_heartbeat_piggyback>
    </qos>
</data_writer>

3.1.2.2.11. ThreadSettings

This structure is part of other QoS policies, and allows controlling some OS settings for the threads created. The default values will leave the default OS settings on the created threads. Changing these values may require special permissions.

Data Member Name	Type	Default Value
scheduling_policy	int32_t	-1
priority	int32_t	-2^31
affinity	uint32_t	0
stack_size	int32_t	-1

• scheduling_policy: Configures the scheduling policy used for the thread. This value is platform specific and it is used as-is to configure the specific platform thread. It is ignored on Windows platforms.

• priority: Configures the thread’s priority. This value is platform specific and it is used as-is to configure the specific platform thread.

• affinity: On some systems (Windows, Linux), this is a bit mask for setting the threads affinity to each core individually. On MacOS, this sets the affinity tag for the thread, and the OS tries to share the L2 cache between threads with the same affinity. This value is platform specific and it is used as-is to configure the specific platform thread.

• stack_size: Configures the thread’s stack size in bytes. This value is platform specific and it is used as-is to configure the specific platform thread.

Example

C++XML

ThreadSettings thread_settings;
thread_settings.scheduling_policy = 2;
thread_settings.priority = 10;
thread_settings.affinity = 4;
thread_settings.stack_size = 2000;

3.1.2.2.12. TransportConfigQos

This QoS Policy allows the configuration of the transport layer settings. See TransportConfigQos.

List of QoS Policy data members:

Data Member Name	Type	Default Value
user_transports	std::vector<std::shared_ptr<TransportDescriptorInterface>>	Empty vector
use_builtin_transports	bool	true
send_socket_buffer_size	uint32_t	0
listen_socket_buffer_size	uint32_t	0
builtin_transports_reception_threads()	ThreadSettings

• user_transports: This data member defines the list of transports to use alongside or in place of builtins.

• use_builtin_transports: It controls whether the built-in transport layer is enabled or disabled. If it is set to false, the default UDPv4 implementation is disabled.

• send_socket_buffer_size: By default, Fast DDS creates socket buffers using the system default size. This data member allows to change the send socket buffer size used to send data.

• listen_socket_buffer_size: The listen socket buffer size is also created with the system default size, but it can be changed using this data member.

• builtin_transports_reception_threads(): The ThreadSettings for the reception threads of the builtin transports.

Note

This QoS Policy concerns to DomainParticipant entities.
It cannot be changed on enabled entities.

TransportDescriptorInterface

This structure is the base for the data type used to define transport configuration.

List of structure members:

Member Name	Type
maxMessageSize	uint32_t
maxInitialPeersRange	uint32_t

• maxMessageSize: This member sets the maximum size in bytes of the transport’s message buffer.

• maxInitialPeersRange: This member states the maximum number of guessed initial peers to try to connect.

Example

C++

TransportConfigQos transport;
// Add new transport to the list of user transports
std::shared_ptr<eprosima::fastdds::rtps::UDPv4TransportDescriptor> descriptor =
        std::make_shared<eprosima::fastdds::rtps::UDPv4TransportDescriptor>();
descriptor->sendBufferSize = 9126;
descriptor->receiveBufferSize = 9126;
transport.user_transports.push_back(descriptor);
// Set use_builtin_transports to false
transport.use_builtin_transports = false;
// [OPTIONAL] Set ThreadSettings for the builtin transports reception threads
transport.builtin_transports_reception_threads_ = eprosima::fastdds::rtps::ThreadSettings{2, 2, 2, 2};

XML

<transport_descriptors>
    <transport_descriptor>
        <transport_id>my_transport</transport_id>
        <type>UDPv4</type>
        <sendBufferSize>9216</sendBufferSize>
        <receiveBufferSize>9216</receiveBufferSize>
    </transport_descriptor>
</transport_descriptors>

<participant profile_name="my_transport">
    <rtps>
        <userTransports>
            <transport_id>my_transport</transport_id>
        </userTransports>
        <useBuiltinTransports>false</useBuiltinTransports>
    </rtps>
</participant>

Note

TransportConfigQos can also be configured modifying the builtin transports configuration by selecting one of the available builtin transports options. See Managing the Builtin Transports or setup_transports().

3.1.2.2.13. TypeConsistencyQos

This QoS Policy allows the configuration of the XTypes extension QoS on the DataReader. See TypeConsistencyQos.

List of QoS Policy data members:

Data Member Name	Type
type_consistency	TypeConsistencyEnforcementQosPolicy
representation	DataRepresentationQosPolicy

• type_consistency: It states the rules for the data types compatibility. See TypeConsistencyEnforcementQosPolicy for further details.

• representation: It specifies the data representations valid for the entities. See DataRepresentationQosPolicy for further details.

Note

This QoS Policy concerns to DataReader entities.
It cannot be changed on enabled entities.

Example

C++

TypeConsistencyQos consistency_qos;
//You can change the DataRepresentationQosPolicy. For further details see DataRepresentationQosPolicySection section.
consistency_qos.representation.m_value.push_back(DataRepresentationId_t::XCDR2_DATA_REPRESENTATION);
//You can change the TypeConsistencyEnforcementQosPolicy. For further details see TypeConsistencyEnforcementQosPolicy section.
consistency_qos.type_consistency.m_kind = TypeConsistencyKind::ALLOW_TYPE_COERCION;

XML

This QoS Policy cannot be configured using XML for the moment.

3.1.2.2.14. WireProtocolConfigQos

This QoS Policy allows the configuration of the wire protocol. See WireProtocolConfigQos.

List of QoS Policy data members:

Data Member Name	Type	Default Value
prefix	GuidPrefix_t	0
participant_id	int32_t	-1
builtin	BuiltinAttributes
port	PortParameters
default_unicast_locator_list	LocatorList	Empty List
default_multicast_locator_list	LocatorList	Empty List
default_external_unicast_locators	ExternalLocators	Empty
ignore_non_matching_locators	bool	false

• prefix: This data member allows the user to set manually the GUID prefix.

• participant_id: It sets the participant identifier. By default, it will be automatically generated by the Domain.

• builtin: This data member allows the configuration of the built-in parameters.

• port: This data member allows the configuration of the port parameters and gains related to the RTPS protocol (Well Known Ports).

• default_unicast_locator_list: States the default list of unicast locators to be used for any endpoint defined inside the RTPSParticipant in the case that it was defined without unicast locators. This list should include at least one locator.

• default_multicast_locator_list: Stores the default list of multicast locators to be used for any endpoint defined inside the RTPSParticipant in the case that it was defined without multicast locators. This list is usually left empty.

• default_external_unicast_locators: Defines the External Locators to be used for any endpoint defined inside the participant in the case that it was defined without unicast locators.

• ignore_non_matching_locators: Defines whether to ignore locators received on announcements from other DDS participants when they don’t match with any of the locators announced by this DDS participant.

Note

This QoS Policy concerns to DomainParticipant entities.

Important

The only mutable field on enabled entities is m_DiscoveryServers, which is contained in discovery_config within builtin (see Modifying remote servers list at run time).

Example

C++

WireProtocolConfigQos wire_protocol;
//Set the guid prefix
std::istringstream("72.61.73.70.66.61.72.6d.74.65.73.74") >> wire_protocol.prefix;
//Configure Builtin Attributes
wire_protocol.builtin.discovery_config.discoveryProtocol =
        eprosima::fastrtps::rtps::DiscoveryProtocol_t::SERVER;
//Add locator to unicast list
eprosima::fastrtps::rtps::Locator_t server_locator;
eprosima::fastrtps::rtps::IPLocator::setIPv4(server_locator, "192.168.10.57");
server_locator.port = 56542;
wire_protocol.builtin.metatrafficUnicastLocatorList.push_back(server_locator);
// Add a metatraffic external locator with IP 100.100.100.10, port 34567, mask 24, externality 1, and cost 0
eprosima::fastdds::rtps::LocatorWithMask meta_external_locator;
meta_external_locator.kind = LOCATOR_KIND_UDPv4;
meta_external_locator.port = 34567;
meta_external_locator.mask(24);
wire_protocol.builtin.metatraffic_external_unicast_locators[1][0].push_back(meta_external_locator);
//Add locator to default unicast locator list
eprosima::fastrtps::rtps::Locator_t unicast_locator;
eprosima::fastrtps::rtps::IPLocator::setIPv4(unicast_locator, 192, 168, 1, 41);
unicast_locator.port = 7400;
wire_protocol.default_unicast_locator_list.push_back(unicast_locator);
//Add locator to default multicast locator list
eprosima::fastrtps::rtps::Locator_t multicast_locator;
eprosima::fastrtps::rtps::IPLocator::setIPv4(multicast_locator, 192, 168, 1, 41);
multicast_locator.port = 7400;
wire_protocol.default_multicast_locator_list.push_back(multicast_locator);
// Add a default external locator with IP 100.100.100.10, port 23456, mask 24, externality 1, and cost 0
eprosima::fastdds::rtps::LocatorWithMask external_locator;
external_locator.kind = LOCATOR_KIND_UDPv4;
external_locator.port = 23456;
external_locator.mask(24);
wire_protocol.default_external_unicast_locators[1][0].push_back(external_locator);
// Drop non matching locators
wire_protocol.ignore_non_matching_locators = true;

XML

<participant profile_name="UDP SERVER WP" is_default_profile="true">
    <rtps>
        <prefix>72.61.73.70.66.61.72.6d.74.65.73.74</prefix>
        <builtin>
            <discovery_config>
                <discoveryProtocol>SERVER</discoveryProtocol>
            </discovery_config>
            <metatrafficUnicastLocatorList>
                <locator>
                    <udpv4>
                        <address>192.168.10.57</address>
                        <port>56542</port>
                    </udpv4>
                </locator>
            </metatrafficUnicastLocatorList>
            <metatraffic_external_unicast_locators>
                <udpv4 externality="1" cost="0" mask="24">
                    <address>100.100.100.10</address>
                    <port>34567</port>
                </udpv4>
            </metatraffic_external_unicast_locators>
        </builtin>
        <defaultUnicastLocatorList>
            <locator>
                <udpv4>
                    <!-- Access as physical, like UDP -->
                    <port>7400</port>
                    <address>192.168.1.41</address>
                </udpv4>
            </locator>
        </defaultUnicastLocatorList>

        <defaultMulticastLocatorList>
            <locator>
                <udpv4>
                    <!-- Access as physical, like UDP -->
                    <port>7400</port>
                    <address>192.168.1.41</address>
                </udpv4>
            </locator>
        </defaultMulticastLocatorList>

        <default_external_unicast_locators>
            <udpv4 externality="1" cost="0" mask="24">
                <address>100.100.100.10</address>
                <port>23456</port>
            </udpv4>
        </default_external_unicast_locators>

        <ignore_non_matching_locators>true</ignore_non_matching_locators>
    </rtps>
</participant>

3.1.2.2.15. WriterResourceLimitsQos

This QoS Policy states the limits for the matched DataReaders’ resource limited collections based on the maximum number of DataReaders that are going to match with the DataWriter. See WriterResourceLimitsQos.

List of QoS Policy data members:

Data Member Name	Type
matched_subscriber_allocation	ResourceLimitedContainerConfig
reader_filters_allocation	ResourceLimitedContainerConfig

Note

This QoS Policy concerns to DataWriter entities.
It cannot be changed on enabled entities.

Example

C++

WriterResourceLimitsQos writer_limits;
//Set the maximum size for reader matched resource limits collection to 3 and its allocation configuration to fixed size
writer_limits.matched_subscriber_allocation =
        eprosima::fastrtps::ResourceLimitedContainerConfig::fixed_size_configuration(3u);
// Set the maximum number of writer side content filters to 1 and its allocation configuration to fixed size
writer_limits.reader_filters_allocation =
        eprosima::fastrtps::ResourceLimitedContainerConfig::fixed_size_configuration(1u);

XML

<data_writer profile_name="alloc_qos_example_pub_for_topic_1">
    <!-- we know we will have three matching subscribers -->
    <matchedSubscribersAllocation>
        <initial>3</initial>
        <maximum>3</maximum>
        <increment>0</increment>
    </matchedSubscribersAllocation>

    <!-- reader_filters_allocation cannot be configured using XML (yet) -->
</data_writer>