10.11. Common

The preceding XML profiles define some XML elements that are common to several profiles. This section aims to explain these common elements.

10.11.1. LocatorListType

It represents a list of Locator_t. LocatorListType is used inside other configuration parameter labels that expect a list of locators, for example, in <defaultUnicastLocatorList>. Therefore, LocatorListType is defined as a set of <locator> elements. The <locator> element has a single child element that defines the transport protocol for which the locator is defined. These are: <udpv4>, <tcpv4>, <udpv6>, and <tcpv6>. The table presented below outlines each possible Locator’s field.

Note

SHM transport locators cannot be configured as they are automatically handled by SHM.

Name

Description

Values

Default

<port>

RTPS port number of the locator.
Physical port in UDP, logical port in TCP.

uint16_t

0

<physical_port>

TCP’s physical port.

uint16_t

0

<address>

IP address of the locator.

string (IPv4/IPv6 format
or DNS name)

Empty

<unique_lan_id>

The LAN ID uniquely identifies the LAN the
locator belongs to (TCPv4 only).

string (16 bytes)

Empty

<wan_address>

WAN IPv4 address (TCPv4 only).

string (IPv4 format)

0.0.0.0

Example

The following example shows the implementation of one locator of each transport protocol in <defaultUnicastLocatorList>.

<defaultUnicastLocatorList>
    <locator>
        <udpv4>
            <!-- Access as physical, typical UDP usage -->
            <port>7400</port>
            <address>192.168.1.41</address>
        </udpv4>
        <udpv4>
            <!-- Access as physical, typical UDP usage -->
            <port>7600</port>
            <address>localhost</address>
        </udpv4>
    </locator>
    <locator>
        <tcpv4>
            <!-- Both physical and logical (port), useful in TCP transports -->
            <physical_port>5100</physical_port>
            <port>7400</port>
            <unique_lan_id>192.168.1.1.1.1.2.55</unique_lan_id>
            <wan_address>80.80.99.45</wan_address>
            <address>192.168.1.55</address>
        </tcpv4>
    </locator>
    <locator>
        <udpv6>
            <port>8844</port>
            <address>::1</address>
        </udpv6>
        <udpv6>
            <port>8888</port>
            <address>localhost</address>
        </udpv6>
    </locator>
    <locator>
        <tcpv6>
            <!-- Both physical and logical (port), useful in TCP transports -->
            <physical_port>5100</physical_port>
            <port>7400</port>
            <address>fe80::55e3:290:165:5af8</address>
        </tcpv6>
    </locator>
</defaultUnicastLocatorList>

10.11.2. ExternalLocatorListType

It represents a list of external locator entries. Each entry can be a <udpv4> or a <udpv6> tag. These tags can be configured with the following attributes:

Name

Description

Values

Default

externality

Number of hops from the participant’s host to the
LAN represented by the external locator.
Valid values: from 1 to 255.

uint8_t

1

cost

Communication cost relative to other locators on
the same externality level.
Valid values: from 0 to 255.

uint8_t

0

mask

Number of significant bits on the LAN represented
by the external locator.
Valid values: from 1 to 31 (UDPv4) or 127 (UDPv6)

uint8_t

24

They should contain the following tags:

Name

Description

Values

<port>

UDP port number of the locator.
The UDP port number should be valid.

uint16_t

<address>

IP address of the locator.

string (IPv4/IPv6 format
or DNS name)

Example

The following example shows the implementation of one locator of each transport protocol in <default_external_unicast_locators>.

<default_external_unicast_locators>
    <udpv4 externality="1" cost="0" mask="24">
        <address>100.100.100.10</address>
        <port>23456</port>
    </udpv4>
    <udpv6 externality="2" cost="0" mask="48">
        <address>::1</address>
        <port>1234</port>
    </udpv6>
</default_external_unicast_locators>

10.11.3. PropertiesPolicyType

PropertiesPolicyType defines the <propertiesPolicy> element. It allows the user to define a set of generic properties inside a <properties> element. It is useful at defining extended or custom configuration parameters.

Name

Description

Values

Default

<name>

Name to identify the property.

string

<value>

Property’s value.

string

<propagate>

Indicates if it is going to be serialized along with the
object it belongs to.

bool

false

Example

<propertiesPolicy>
    <properties>
        <property>
            <name>Property1Name</name>
            <value>Property1Value</value>
            <propagate>false</propagate>
        </property>
        <property>
            <name>Property2Name</name>
            <value>Property2Value</value>
            <propagate>true</propagate>
        </property>
    </properties>
</propertiesPolicy>

10.11.4. DurationType

DurationType expresses a period of time and it is commonly used inside other XML elements, such as in <leaseAnnouncement> or <leaseDuration>. A DurationType is defined by at least one mandatory element of two possible ones: <sec> plus <nanosec>. An infinite value can be specified by using the values DURATION_INFINITY, DURATION_INFINITE_SEC and DURATION_INFINITE_NSEC.

Name

Description

Values

Default

<sec>

Number of seconds.

int32_t

0

<nanosec>

Number of nanoseconds.

uint32_t

0

Example

<discovery_config>
    <leaseDuration>
        <sec>DURATION_INFINITY</sec>
    </leaseDuration>
    <leaseAnnouncement>
        <sec>1</sec>
        <nanosec>856000</nanosec>
    </leaseAnnouncement>
</discovery_config>

10.11.5. TopicType

This XML element allows the configuration of the specific HistoryQosPolicy and ResourceLimitsQosPolicy QoS of the Datawriters and DataReaders in which this element is defined inside of. Also, it sets the TopicQos configuration with the policies detailed.

Name

Description

Values

<historyQos>

It controls the behavior of Fast DDS
when the value of an instance changes
before it is finally communicated to
some of its existing DataReaders.

HistoryQoS

<resourceLimitsQos>

It controls the resources that Fast DDS
can use in order to meet the
requirements imposed by the application
and other QoS settings.

ResourceLimitsQos

Example

<data_writer profile_name="dataWriter_topic_example">
    <topic>
        <historyQos>
            <kind>KEEP_LAST</kind>
            <depth>20</depth>
        </historyQos>
        <resourceLimitsQos>
            <max_samples>5</max_samples>
            <max_instances>2</max_instances>
            <max_samples_per_instance>1</max_samples_per_instance>
            <allocated_samples>20</allocated_samples>
            <extra_samples>10</extra_samples>
        </resourceLimitsQos>
    </topic>
</data_writer>

10.11.5.1. HistoryQoS

It controls the behavior of Fast DDS when the value of an instance changes before it is finally communicated to some of its existing DataReaders. Please refer to HistoryQosPolicyKind for further information on HistoryQoS.

Name

Description

Values

Default

<kind>

Fast DDS will only attempt to keep the latest values of the instance
and discard the older ones.

KEEP_LAST

KEEP_LAST

Fast DDS will attempt to maintain and deliver all the values of the instance
to existing DataReaders.

KEEP_ALL

<depth>

It must be consistent with the ResourceLimitsQos <max_samples_per_instance>
element value. It must be verified that:
<depth> <= <max_samples_per_instance>.

uint32_t

1

10.11.5.2. ResourceLimitsQos

It controls the resources that Fast DDS can use in order to meet the requirements imposed by the application and other QoS settings. Please refer to ResourceLimitsQosPolicy for further information on ResourceLimitsQos.

Name

Description

Values

Default

<max_samples>

It must verify that: <max_samples> >= <max_samples_per_instance>.

uint32_t

5000

<max_instances>

It defines the maximum number of instances.

uint32_t

10

<max_samples_per_instance>

It must verify that: HistoryQos <depth> <= <max_samples_per_instance>.

uint32_t

400

<allocated_samples>

It controls the maximum number of samples to be stored.

uint32_t

100

<extra_samples>

The number of extra samples to allocate on the pool.

uint32_t

1

10.11.6. ThreadSettings

It controls some OS settings for the Fast DDS created threads. Please refer to ThreadSettings for further information on ResourceLimitsQos.

Name

Description

Values

Default

scheduling_policy

Configures the scheduling policy used for the thread.

int32_t

-1

priority

Configures the thread’s priority.

int32_t

-2^31

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.

uint32_t

0

stack_size

Configures the thread’s stack size in bytes.

int32_t

-1

10.11.7. QoS

The Quality of Service (QoS) is used to specify the behavior of the Service, allowing the user to define how each Entity will behave. Please refer to the Policy section for more information on QoS.

Name

Description

Values

<data_sharing>

See DataSharingQosPolicy

Data-Sharing

<deadline>

See DeadlineQosPolicy.

Deadline

<disable_heartbeat_piggyback>

See DisableHeartbeatPiggyback.

DisableHeartbeatPiggyback

<disablePositiveAcks>

See DisablePositiveACKsQosPolicy.

DisablePositiveAcks

<durability>

See DurabilityQosPolicy.

Durability

<entity_factory>

See EntityFactoryQosPolicy.

Entity Factory

<groupData>

See GroupDataQosPolicy.

GroupData

<latencyBudget>

See LatencyBudgetQosPolicy.

LatencyBudget

<lifespan>

See LifespanQosPolicy.

Lifespan

<liveliness>

See LivelinessQosPolicy.

Liveliness

<ownership>

See OwnershipQosPolicy.

Ownership

<ownershipStrength>

See OwnershipStrengthQosPolicy.

Ownership Strength

<partition>

See PartitionQosPolicy.

Partition

<publishMode>

See PublishModeQosPolicy.

PublishMode

<reliability>

See ReliabilityQosPolicy.

ReliabilityQosPolicy

<topicData>

See TopicDataQosPolicy.

TopicData

<userData>

See UserDataQosPolicy.

UserData

Example

<data_writer profile_name="pub_topic_qos">
<qos> <!-- writerQosPoliciesType -->
    <data_sharing>
        <kind>AUTOMATIC</kind>
        <shared_dir>/home</shared_dir>
        <max_domains>10</max_domains>
        <domain_ids>
            <domainId>0</domainId>
            <domainId>11</domainId>
        </domain_ids>
    </data_sharing>

    <deadline>
        <period>
            <sec>1</sec>
        </period>
    </deadline>

    <!-- DataWriter specific QoS -->
    <disable_heartbeat_piggyback>true</disable_heartbeat_piggyback>

    <disablePositiveAcks>
        <enabled>true</enabled>
        <duration>
            <sec>1</sec>
        </duration>
    </disablePositiveAcks>

    <durability>
        <kind>VOLATILE</kind>
    </durability>

    <groupData>
        <value>1.a.2</value>
    </groupData>

    <!-- QoS policy pending implementation -->
    <latencyBudget>
        <duration>
            <sec>1</sec>
        </duration>
    </latencyBudget>

    <lifespan>
        <duration>
            <sec>1</sec>
        </duration>
    </lifespan>

    <liveliness>
        <kind>AUTOMATIC</kind>

        <lease_duration>
            <sec>1</sec>
        </lease_duration>

        <announcement_period>
            <sec>1</sec>
        </announcement_period>
    </liveliness>

    <ownership>
        <kind>EXCLUSIVE</kind>
    </ownership>

    <!-- DataWriter specific QoS -->
    <ownershipStrength>
        <value>50</value>
    </ownershipStrength>

    <partition>
        <names>
            <name>part1</name>
            <name>part2</name>
        </names>
    </partition>

    <!-- DataWriter specific QoS -->
    <publishMode>
        <kind>ASYNCHRONOUS</kind>
    </publishMode>

    <reliability>
        <kind>BEST_EFFORT</kind>
        <max_blocking_time>
            <sec>1</sec>
        </max_blocking_time>
    </reliability>

    <topicData>
        <value>2.b.1</value>
    </topicData>

    <userData>
        <value>3.c.0</value>
    </userData>
</qos>

10.11.7.1. Data-Sharing

Name

Description

Values

Default

<kind>

See DataSharingKind

AUTOMATIC
ON
OFF

AUTOMATIC

<shared_dir>

Directory used for the memory-mapped files.

string

Empty

<max_domains>

Maximum number of Data-Sharing domain IDs
in the local or remote endpoints.

uint32_t

0 (unlimited)

<domain_ids>

List of Data-Sharing domain IDs configured
for the current endpoint.

<domainId>

Empty list

Name

Description

Values

<domainId>

Domain ID to be used by the endpoint for Data-Sharing.

uint32_t

10.11.7.2. Deadline

Name

Description

Values

Default

<period>

See DeadlineQosPolicy.

DurationType

c_TimeInfinite

10.11.7.3. DisableHeartbeatPiggyback

Name

Description

Values

Default

<disable_heartbeat_piggyback>

See DisableHeartbeatPiggyback.

bool

false

Important

This configuration is only available for DataWriter QoS profile configuration.

10.11.7.4. DisablePositiveAcks

Name

Description

Values

Default

<enabled>

See DisablePositiveACKsQosPolicy.

bool

false

<duration>

See DisablePositiveACKsQosPolicy.

DurationType

c_TimeInfinite

10.11.7.5. Durability

Name

Description

Values

Default

<kind>

See DurabilityQosPolicyKind.

VOLATILE
TRANSIENT_LOCAL
TRANSIENT
PERSISTENT

DataReaders: VOLATILE
DataWriters: TRANSIENT_LOCAL

10.11.7.6. Entity Factory

Name

Description

Values

Default

<autoenable_created_entities>

See EntityFactoryQosPolicy.

bool

true

10.11.7.7. GroupData

Name

Description

Values

Default

<value>

See GroupDataQosPolicy.

string (std::vector<octet>)

Empty

10.11.7.8. LatencyBudget

Name

Description

Values

Default

<duration>

See LatencyBudgetQosPolicy.

DurationType

0

10.11.7.9. Lifespan

Name

Description

Values

Default

<duration>

See LifespanQosPolicy.

DurationType

c_TimeInfinite

10.11.7.10. Liveliness

Name

Description

Values

Default

<kind>

See LivelinessQosPolicyKind.

AUTOMATIC

AUTOMATIC

MANUAL_BY_PARTICIPANT

MANUAL_BY_TOPIC

<lease_duration>

See LivelinessQosPolicy.

DurationType

c_TimeInfinite

<announcement_period>

See LivelinessQosPolicy.

DurationType

c_TimeInfinite

10.11.7.11. Ownership

Name

Description

Values

Default

<kind>

See OwnershipQosPolicyKind.

SHARED
EXCLUSIVE

SHARED

10.11.7.12. Ownership Strength

Name

Description

Values

Default

<value>

See OwnershipStrengthQosPolicy.

uint32_t

0

Important

This configuration is only available for DataWriter QoS profile configuration.

10.11.7.13. Partition

Name

Description

Values

<names>

It comprises a set of <name> elements containing the name of each partition.
See PartitionQosPolicy.

<name>

10.11.7.14. PublishMode

Name

Description

Values

Default

<kind>

See PublishModeQosPolicy.

ASYNCHRONOUS

ASYNCHRONOUS

SYNCHRONOUS

Important

This configuration is only available for DataWriter QoS profile configuration.

10.11.7.15. ReliabilityQosPolicy

Name

Description

Values

Default

<kind>

See ReliabilityQosPolicyKind.

BEST_EFFORT

DataReaders: BEST_EFFORT
DataWriters: RELIABLE

RELIABLE

<max_blocking_time>

See ReliabilityQosPolicy.

DurationType

100 ms

10.11.7.16. TopicData

Name

Description

Values

Default

<value>

See TopicDataQosPolicy.

string (std::vector<octet>)

Empty

10.11.7.17. UserData

Name

Description

Values

Default

<value>

See UserDataQosPolicy.

string (std::vector<octet>)

Empty

10.11.8. HistoryMemoryPolicy

Indicates the way the memory is managed in terms of dealing with the CacheChanges of the RTPSEndpointQos.

Name

Description

Values

Default

<historyMemoryPolicy>

Four different options as described
in MemoryManagementPolicy.

PREALLOCATED
PREALLOCATED_WITH_REALLOC
DYNAMIC
DYNAMIC_REUSABLE

PREALLOCATED

Example

<data_writer profile_name="data_writer_historyMemoryPolicy">
    <!-- ...  -->
    <historyMemoryPolicy>DYNAMIC</historyMemoryPolicy>
</data_writer>

<data_reader profile_name="data_reader_historyMemoryPolicy">
    <!-- ...  -->
    <historyMemoryPolicy>DYNAMIC</historyMemoryPolicy>
</data_reader>

10.11.9. Allocation Configuration

The <allocation> element allows to control the allocation behavior of internal collections for which the number of elements depends on the number of entities in the system. For instance, there are collections inside a DataWriter which depend on the number of DataReaders matching with it. Please refer to ParticipantResourceLimitsQos for a detailed documentation on DomainParticipant allocation, and to Tuning allocations for detailed information on how to tune allocation related parameters.

Name

Description

Values

Default

<initial>

Number of elements for which space is initially allocated.

uint32_t

0

<maximum>

Maximum number of elements for which space will be allocated.

uint32_t

0 (Means no limit)

<increment>

Number of new elements that will be allocated when more space is
necessary.

uint32_t

1