Skip to content

Latest commit

 

History

History
1127 lines (898 loc) · 48.6 KB

eprosimaExtensions.rst

File metadata and controls

1127 lines (898 loc) · 48.6 KB
Raw

eProsima Extensions

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

DataSharingQosPolicy

This additional QoS allows configuring the data-sharing delivery communication between a writer and a reader. Please, see :ref:`datasharing-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 :ref:`datasharingkind` |DataSharingQosPolicy::kind-api| AUTO
Shared memory directory string |DataSharingQosPolicy::shm_directory-api| Empty string
Maximum domain number uint32_t |DataSharingQosPolicy::max_domains-api| 0 (unlimited)
Data-sharing domain IDs vector<uint64_t> |DataSharingQosPolicy::domain_ids-api| Empty
  • Data-sharing kind: Specifies the behavior of data-sharing delivery. See :ref:`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.

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-api|):

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 :ref:`datasharingkind` flavor:

Function Resulting DataSharingKind Shared memory directory Data sharing domain IDs
|DataSharingQosPolicy::auto-api| |DATASHARING_AUTO-api| Optional Optional
|DataSharingQosPolicy::on-api| |DATASHARING_ON-api| Mandatory Optional
|DataSharingQosPolicy::off-api| |DATASHARING_OFF-api| N/A N/A

Instead of defining the data-sharing domain IDs on these helper functions, you can add them later with the |DataSharingQosPolicy::add_domain_id-api| 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++

.. literalinclude:: ../../../../../code/DDSCodeTester.cpp
   :language: c++
   :dedent: 8
   :start-after: //DDS_CHANGE_DATASHARING_QOS_POLICY
   :end-before: //!

XML

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->CONF-QOS-DATASHARING<-->
    :end-before: <!--><-->

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-api|.

List of QoS Policy data members:

Data Member Name Type Default Value
|DisablePositiveACKsQosPolicy::enabled-api| bool false
|DisablePositiveACKsQosPolicy::duration-api| |Duration_t-api| |c_TimeInfinite-api|

Note

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

Warning

For DataWriters and DataReaders to match, they must follow the compatibility rule. See :ref:`disableacks_compatibilityrule` 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++

.. literalinclude:: ../../../../../code/DDSCodeTester.cpp
   :language: c++
   :dedent: 8
   :start-after: //DDS_CHANGE_DISABLE_POSITIVE_ACKS_QOS_POLICY
   :end-before: //!

XML

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->PUBSUB_API_CONF_PUBSUB_DISABLE_POSITIVE_ACKS
    :end-before: <!--><-->

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-api|, which has the following fields:

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

Please refer to :ref:`flow-controllers` section for more information.

Note

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

ParticipantResourceLimitsQos

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

List of QoS Policy data members:

Data Member Name Type
|ParticipantResourceLimitsQos::locators-api| :ref:`remotelocatorsallocationattributes`
|ParticipantResourceLimitsQos::participants-api| :ref:`resourcelimitedcontainerconfig`
|ParticipantResourceLimitsQos::readers-api| :ref:`resourcelimitedcontainerconfig`
|ParticipantResourceLimitsQos::writers-api| :ref:`resourcelimitedcontainerconfig`
|ParticipantResourceLimitsQos::send_buffers-api| :ref:`sendbuffersallocationattributes`
|ParticipantResourceLimitsQos::data_limits-api| :ref:`variablelengthdatalimits`
|ParticipantResourceLimitsQos::content_filter-api| :ref:`contentfilterlimits`

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-api|.

List of structure members:

Member Name Type Default Value
|RemoteLocatorsAllocationAttributes::max_unicast_locators-api| size_t 4
|RemoteLocatorsAllocationAttributes::max_multicast_locators-api| size_t 1

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
|ResourceLimitedContainerConfig::initial-api| size_t 0
|ResourceLimitedContainerConfig::maximum-api| size_t :func:`std::numeric_limits<size_t>::max()`
|ResourceLimitedContainerConfig::increment-api| size_t 1 (dynamic size), 0 (fixed size)

SendBuffersAllocationAttributes

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

List of structure members:

Member Name Type Default Value
|SendBuffersAllocationAttributes::preallocated_number-api| size_t 0
|SendBuffersAllocationAttributes::dynamic-api| bool false
  • |SendBuffersAllocationAttributes::preallocated_number-api|: 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.
  • |SendBuffersAllocationAttributes::dynamic-api|: 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-api|.

List of structure members:

Member Name Type Default Value
|VariableLengthDataLimits::max_properties-api| size_t 0
|VariableLengthDataLimits::max_user_data-api| size_t 0
|VariableLengthDataLimits::max_partitions-api| size_t 0

ContentFilterProperty::AllocationConfiguration

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

List of structure members:

Member Name Type Default Value
|ContentFilterProperty::AllocationConfiguration::expression_initial_size-api| size_t 0
|ContentFilterProperty::AllocationConfiguration::expression_parameters-api| :ref:`resourcelimitedcontainerconfig` {0, 100, 1}

Example

C++

.. literalinclude:: ../../../../../code/DDSCodeTester.cpp
   :language: c++
   :dedent: 8
   :start-after: //DDS_CHANGE_PARTICIPANT_RESOURCE_LIMITS_QOS_POLICY
   :end-before: //!

XML

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->CONF-ALLOCATION-QOS-EXAMPLE
    :end-before: <data_writer

PropertyPolicyQos

This additional QoS Policy (|PropertyPolicyQos-api|) 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 :ref:`property_policies`.

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++

.. literalinclude:: ../../../../../code/DDSCodeTester.cpp
   :language: c++
   :dedent: 8
   :start-after: //DDS_CHANGE_PROPERTY_POLICY_QOS
   :end-before: //!

XML

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML_PROPERTY_POLICY
    :end-before: <!--><-->

PublishModeQosPolicy

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

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
|PublishModeQosPolicy::kind-api| :ref:`publishmodeqospolicykind` |SYNCHRONOUS_PUBLISH_MODE-api|
|PublishModeQosPolicy::flow_ctrl_name-api| const char * |FASTDDS_FLOW_CONTROLLER_DEFAULT-api|

Note

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

PublishModeQosPolicyKind

There are two possible values (see |PublishModeQosPolicyKind-api|):

Example

C++

.. literalinclude:: ../../../../../code/DDSCodeTester.cpp
   :language: c++
   :dedent: 8
   :start-after: //DDS_CHANGE_PUBLISH_MODE_QOS
   :end-before: //!

XML

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->CONF-QOS-PUBLISHMODE<-->
    :end-before: <!--><-->

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-api|.

List of QoS Policy data members:

Data Member Name Type
|ReaderResourceLimitsQos::matched_publisher_allocation-api| :ref:`resourcelimitedcontainerconfig`

Note

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

Example

C++

.. literalinclude:: ../../../../../code/DDSCodeTester.cpp
   :language: c++
   :dedent: 8
   :start-after: //DDS_CHANGE_READER_RESOURCE_LIMITS_QOS
   :end-before: //!

XML

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML_READER_RESOURCE_LIMITS_QOS<-->
    :end-before: <!--><-->

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-api|.

List of QoS Policy data members:

Data Member Name Type Default Value
|RTPSEndpointQos::unicast_locator_list-api| |LocatorList_t-api| Empty List
|RTPSEndpointQos::multicast_locator_list-api| |LocatorList_t-api| Empty List
|RTPSEndpointQos::remote_locator_list-api| |LocatorList_t-api| Empty List
|RTPSEndpointQos::external_unicast_locators-api| |ExternalLocators-api| Empty
|RTPSEndpointQos::ignore_non_matching_locators-api| bool false
|RTPSEndpointQos::user_defined_id-api| int16_t -1
|RTPSEndpointQos::entity_id-api| int16_t -1
|RTPSEndpointQos::history_memory_policy-api| :ref:`memorymanagementpolicy` |PREALLOCATED_WITH_REALLOC_MEMORY_MODE-api|

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-api|):

  • |PREALLOCATED_MEMORY_MODE-api|: 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-api|: 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-api|: 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-api|: This option is similar to DYNAMIC_RESERVE_MEMORY_MODE, but the allocated memory is reused for future messages.

Example

C++

.. literalinclude:: ../../../../../code/DDSCodeTester.cpp
   :language: c++
   :dedent: 8
   :start-after: //DDS_CHANGE_RTPS_ENDPOINT_QOS
   :end-before: //!

XML

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML_RTPS_ENDPOINT_QOS<-->
    :end-before: <!--><-->

RTPSReliableReaderQos

This RTPS QoS Policy allows the configuration of several RTPS reliable reader's aspects. See |RTPSReliableReaderQos-api|.

List of QoS Policy data members:

Data Member Name Type
|RTPSReliableReaderQos::times-api| :ref:`readertimes`
|RTPSReliableReaderQos::disable_positive_ACKs-api| :ref:`disablepositiveacksqospolicy`

Note

This QoS Policy concerns to |DataReader| entities.
Only the |DisablePositiveACKsQosPolicy::duration-api| Data Member of the :ref:`disablepositiveacksqospolicy` and the |RTPSReliableReaderQos::times-api| Data Member can be modified on enabled entities.

ReaderTimes

This structure defines the times associated with the Reliable Readers' events. See |ReaderTimes-api|.

List of structure members:

Member Name Type Default Value
|ReaderTimes::initialAcknackDelay-api| |Duration_t-api| 70 ms
|ReaderTimes::heartbeatResponseDelay-api| |Duration_t-api| 5 ms

Example

C++

.. literalinclude:: ../../../../../code/DDSCodeTester.cpp
   :language: c++
   :dedent: 8
   :start-after: //DDS_CHANGE_RTPS_RELIABLE_READER_QOS
   :end-before: //!

XML

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML_RTPS_RELIABLE_READER_QOS<-->
    :end-before: <!--><-->

RTPSReliableWriterQos

This RTPS QoS Policy allows the configuration of several RTPS reliable writer's aspects. See |RTPSReliableWriterQos-api|.

List of QoS Policy data members:

Data Member Name Type
|RTPSReliableWriterQos::times-api| :ref:`writertimes`
|RTPSReliableWriterQos::disable_positive_acks-api| :ref:`disablepositiveacksqospolicy`
|RTPSReliableWriterQos::disable_heartbeat_piggyback-api| :ref:`disableheartbeatpiggyback`

Note

This QoS Policy concerns to |DataWriter| entities.
Only the |DisablePositiveACKsQosPolicy::duration-api| Data Member of the :ref:`disablepositiveacksqospolicy` and the |RTPSReliableWriterQos::times-api| 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
|WriterTimes::initialHeartbeatDelay-api| |Duration_t-api| 12ms
|WriterTimes::heartbeatPeriod-api| |Duration_t-api| 3s
|WriterTimes::nackResponseDelay-api| |Duration_t-api| 5ms
|WriterTimes::nackSupressionDuration-api| |Duration_t-api| 0s

DisableHeartbeatPiggyback

Besides sending heartbeats periodically using the |WriterTimes::heartbeatPeriod-api| (see :ref:`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++

.. literalinclude:: ../../../../../code/DDSCodeTester.cpp
   :language: c++
   :dedent: 8
   :start-after: //DDS_CHANGE_RTPS_RELIABLE_WRITER_QOS
   :end-before: //!

XML

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML_RTPS_RELIABLE_WRITER_QOS<-->
    :end-before: <!--><-->

TransportConfigQos

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

List of QoS Policy data members:

Data Member Name Type Default Value
|TransportConfigQos::user_transports-api| std::vector<std::shared_ptr<TransportDescriptorInterface>> Empty vector
|TransportConfigQos::use_builtin_transports-api| bool true
|TransportConfigQos::send_socket_buffer_size-api| uint32_t 0
|TransportConfigQos::listen_socket_buffer_size-api| uint32_t 0

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
|TransportDescriptorInterface::maxMessageSize-api| uint32_t
|TransportDescriptorInterface::maxInitialPeersRange-api| uint32_t

Example

C++

.. literalinclude:: ../../../../../code/DDSCodeTester.cpp
   :language: c++
   :dedent: 8
   :start-after: //DDS_CHANGE_TRANSPORT_CONFIG_QOS
   :end-before: //!

XML

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->CONF-COMMON-TRANSPORT-SETTING<-->
    :end-before: <!--><-->

Note

:ref:`transportconfigqos` can also be configured modifying the builtin transports configuration by selecting one of the available builtin transports options. See :ref:`rtps_layer_builtin_transports` or |DomainParticipantQoS::setup_transports-api|.

TypeConsistencyQos

This QoS Policy allows the configuration of the :ref:`XTypes extension QoS<xtypes_extensions>` on the |DataReader|. See |TypeConsistencyQos-api|.

List of QoS Policy data members:

Data Member Name Type
|TypeConsistencyQos::type_consistency-api| :ref:`typeconsistencyenforcementqospolicy`
|TypeConsistencyQos::representation-api| :ref:`datarepresentationqospolicy`

Note

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

Example

C++

.. literalinclude:: ../../../../../code/DDSCodeTester.cpp
   :language: c++
   :dedent: 8
   :start-after: //DDS_CHANGE_TYPE_CONSISTENCY_QOS
   :end-before: //!

XML

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

WireProtocolConfigQos

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

List of QoS Policy data members:

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

Note

This QoS Policy concerns to DomainParticipant entities.

Important

The only mutable field on enabled entities is |m_DiscoveryServers|, which is contained in |BuiltinAttributes::discovery_config-api| within |WireProtocolConfigQos::builtin-api| (see :ref:`DS_modify_server_list`).

Example

C++

.. literalinclude:: ../../../../../code/DDSCodeTester.cpp
   :language: c++
   :dedent: 8
   :start-after: //DDS_CHANGE_WIRE_PROTOCOL_CONFIG_QOS
   :end-before: //!

XML

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML_WIRE_PROTOCOL_CONFIG_QOS<-->
    :end-before: <!--><-->

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-api|.

List of QoS Policy data members:

Data Member Name Type
|WriterResourceLimitsQos::matched_subscriber_allocation-api| :ref:`resourcelimitedcontainerconfig`
|WriterResourceLimitsQos::reader_filters_allocation-api| :ref:`resourcelimitedcontainerconfig`

Note

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

Example

C++

.. literalinclude:: ../../../../../code/DDSCodeTester.cpp
   :language: c++
   :dedent: 8
   :start-after: //DDS_CHANGE_WRITER_RESOURCE_LIMITS_QOS
   :end-before: //!

XML

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML_WRITER_RESOURCE_LIMITS_QOS<-->
    :end-before: <!--><-->