.. _dds_layers_infrastructure_policies:

Policy
======

The Quality of Service (QoS) is used to specify the behavior of the Service, defining how each entity will behave.
To increase the flexibility of the system, the QoS is decomposed in several QoS Policies that can be configured independently.
However, there may be cases where several policies conflict.
Those conflicts will make the entities to :ref:`fail on enable <dds_layers_infrastructure_entities_enabling>`.

Each Qos Policy has a unique ID defined in the ``QosPolicyId`` enumerator.
This ID is used in some :ref:`Status <dds_layers_infrastructure_status>` instances to identify the specific Qos Policy to which the Status refers.

.. include:: ../../../safety_manual/rules/RULE_ALLOW_QOS_POLICIES.inc
.. include:: ../../../safety_manual/rules/RULE_CHANGE_QOS.inc

.. admonition:: Safe DDS Usage
   :class: caution

   In Safe DDS, entity QoS are immutable and cannot be modified after the entity has been created.

.. _dds_layers_infrastructure_standard_policies:

Standard QoS Policies
---------------------

This section explains each of the DDS standard QoS Policies:

.. _deadlineqospolicy:

DeadlineQosPolicy
^^^^^^^^^^^^^^^^^

This QoS policy raises an alarm when the frequency of new samples falls below a certain threshold.
It is useful for cases where data is expected to be updated periodically.

On the publishing side, the deadline defines the maximum period in which the application is expected to supply a new sample.
On the subscribing side, it defines the maximum period in which new samples should be received.

For Topics with keys, this QoS is applied by key.

Compatibility Rule
""""""""""""""""""
To maintain the compatibility between DeadlineQosPolicy in DataReaders and DataWriters, the offered deadline period
(configured on the DataWriter) must be less than or equal to the requested deadline period (configured on the
DataReader), otherwise, the entities are considered to be incompatible.

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_DEADLINE_QOS_POLICY
   :end-before: //! DDS_DEADLINE_QOS_POLICY


.. _durabilityqospolicy:

DurabilityQosPolicy
^^^^^^^^^^^^^^^^^^^

A DataWriter can send messages throughout a Topic even if there are no DataReaders on the network.
Moreover, a DataReader that joins to the Topic after some data has been written could be interested in accessing that information.

The DurabilityQoSPolicy defines how the system will behave regarding those samples that existed on the Topic before the DataReader joins.
The behavior of the system depends on the value of the :ref:`DurabilityQosPolicyKind<durabilitykind>`.

.. _durabilitykind:

DurabilityQosPolicyKind
"""""""""""""""""""""""

There are two supported values:

* ``VOLATILE_DURABILITY_QOS``
    Past samples are ignored and a joining DataReader receives samples generated after the moment it matches.
* ``TRANSIENT_LOCAL_DURABILITY_QOS``
    When a new DataReader joins, its History is filled with past samples.

.. _durability_compatibilityrule:

Compatibility Rule
""""""""""""""""""

To maintain the compatibility between DurabilityQosPolicy in DataReaders and DataWriters when they have different kind values, the DataWriter kind must be higher or equal to the DataReader kind.
And the order between the different kinds is:

``VOLATILE_DURABILITY_QOS`` < ``TRANSIENT_LOCAL_DURABILITY_QOS``

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_DURABILITY_QOS_POLICY
   :end-before: //! DDS_DURABILITY_QOS_POLICY

.. _entityfactoryqospolicy:

EntityFactoryQosPolicy
^^^^^^^^^^^^^^^^^^^^^^

This QoS Policy controls the behavior of :ref:`dds_layers_infrastructure_entities` when they act as factories for other entities.
By default, all the entities are automatically enabled on their creation. This behavior can be modified with the value of the ``EntityFactoryQosPolicy::autoenable_created_entities`` parameter.

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_ENTITYFACTORY_QOS_POLICY
   :end-before: //! DDS_ENTITYFACTORY_QOS_POLICY

.. _historyqospolicy:

HistoryQosPolicy
^^^^^^^^^^^^^^^^

This QoS Policy controls the behavior of the system when the value of an instance changes one or more times before it can be successfully communicated to the existing DataReader entities.

List of QoS Policy data members:

* ``HistoryQosPolicy::kind``
    Controls if the service should deliver only the most recent values, all the intermediate values or do something in between.
    See :ref:`historyqospolicykind` for further details.
* ``HistoryQosPolicy::depth``
    Establishes the maximum number of samples that must be kept on the history.
    It only has effect if the kind is set to ``KEEP_LAST_HISTORY_QOS`` and it needs to be consistent with the :ref:`resourcelimitsqospolicy`, which means that its value must be lower or equal to ``max_samples_per_instance``.

.. _historyqospolicykind:

HistoryQosPolicyKind
""""""""""""""""""""
There are two possible values:

* ``KEEP_LAST_HISTORY_QOS``
    The service will only attempt to keep the most recent values of the instance and discard the older ones.
    The maximum number of samples to keep and deliver is defined by the `depth` of the HistoryQosPolicy, which needs to be consistent with the :ref:`resourcelimitsqospolicy` settings.
    If the limit defined by `depth` is reached, the system will discard the oldest sample to make room for a new one.
* ``KEEP_ALL_HISTORY_QOS``
    The service will attempt to keep all the values of the instance until it can be delivered to all the existing Subscribers.
    If this option is selected, the depth will not have any effect, so the history is only limited by the values set in :ref:`resourcelimitsqospolicy`.
    If the limit is reached, the behavior of the system depends on the :ref:`reliabilityqospolicy`, if its kind is *BEST_EFFORT* the older values will be discarded but if it is RELIABLE the service blocks the DataWriter until the old values are delivered to all existing Subscribers.

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_HISTORY_QOS_POLICY
   :end-before: //! DDS_HISTORY_QOS_POLICY

.. _livelinessqospolicy:

LivelinessQosPolicy
^^^^^^^^^^^^^^^^^^^

This QoS Policy controls the mechanism used by the service to ensure that a particular entity on the network is still alive.
There are different settings that allow distinguishing between applications where data is updated periodically and applications where data is changed sporadically.
It also allows customizing the application regarding the kind of failures that should be detected by the liveliness mechanism.

List of QoS Policy data members:

* ``LivelinessQosPolicy::kind``
    This data member establishes if the service needs to assert the liveliness automatically or if it needs to wait until the liveliness is asserted by the publishing side.
    See :ref:`livelinessqospolicykind` for further details.
* ``LivelinessQosPolicy::lease_duration``
    Amount of time to wait since the last time the DataWriter asserts its liveliness to consider that it is no longer alive.

.. _livelinessqospolicykind:

LivelinessQosPolicyKind
"""""""""""""""""""""""

There are three possible values:

* ``AUTOMATIC_LIVELINESS_QOS``
    The service takes the responsibility for renewing the leases at the required rates, as long as the local process where the participant is running and the link connecting it to remote participants exists, the entities within the remote participant will be considered alive.
    This kind is suitable for applications that only need to detect whether a remote application is still running.
* The two manual modes require that the application on the publishing side asserts the liveliness periodically before the `lease_duration` timer expires.
  Publishing any new data value implicitly asserts the DataWriter's liveliness, but it can be done explicitly by calling the ``assert_liveliness()`` member function.

  * ``MANUAL_BY_PARTICIPANT_LIVELINESS_QOS``
        If one of the entities in the publishing side asserts its liveliness, the service deduces that all other entities within the same DomainParticipant are also alive.
  * ``MANUAL_BY_TOPIC_LIVELINESS_QOS``
        This mode is more restrictive and requires that at least one instance within the DataWriter is asserted to consider that the DataWriter is alive.

.. _liveliness_compatibilityrule:

Compatibility Rule
""""""""""""""""""

To maintain the compatibility between LivelinessQosPolicy in DataReaders and DataWriters, the DataWriter kind must be higher or equal to the DataReader kind.
And the order between the different kinds is:

``AUTOMATIC_LIVELINESS_QOS`` < ``MANUAL_BY_PARTICIPANT_LIVELINESS_QOS`` < ``MANUAL_BY_TOPIC_LIVELINESS_QOS``

Additionally, the ``LivelinessQosPolicy::lease_duration`` of the DataWriter must not be greater than the ``LivelinessQosPolicy::lease_duration`` of the DataReader.

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_LIVELINESS_QOS_POLICY
   :end-before: //! DDS_LIVELINESS_QOS_POLICY

.. _reliabilityqospolicy:

ReliabilityQosPolicy
^^^^^^^^^^^^^^^^^^^^

This QoS Policy indicates the level of reliability offered and requested by the service.

List of QoS Policy data members:

* ``ReliabilityQosPolicy::kind``
    Specifies the behavior of the service regarding delivery of the samples.
    See :ref:`reliabilityqospolicykind` for further details.
* ``ReliabilityQosPolicy::max_blocking_time``
    Configures the maximum duration that the write operation can be blocked.

.. include:: ../../../safety_manual/rules/RULE_MAX_BLOCKING_TIME.inc

.. _reliabilityqospolicykind:

ReliabilityQosPolicyKind
""""""""""""""""""""""""

There are two possible values:

* ``BEST_EFFORT_RELIABILITY_QOS``
    It indicates that it is acceptable not to retransmit the missing samples, so the messages are sent without waiting for an arrival confirmation.
    Presumably new values for the samples are generated often enough that it is not necessary to re-send any sample.
    However, the data samples sent by the same DataWriter will be stored in the DataReader history in the same order they occur.
    In other words, even if the DataReader misses some data samples, an older value will never overwrite a newer value.
* ``RELIABLE_RELIABILITY_QOS``
    It indicates that the service will attempt to deliver all samples of the DataWriter's history expecting an arrival confirmation from the DataReader.
    The data samples sent by the same DataWriter cannot be made available to the DataReader if there are previous samples that have not been received yet.
    The service will retransmit the lost data samples in order to reconstruct a correct snapshot of the DataWriter history before it is accessible by the DataReader.

.. _reliability_compatibilityrule:

Compatibility Rule
""""""""""""""""""

To maintain the compatibility between ReliabilityQosPolicy in DataReaders and DataWriters, the DataWriter kind
must be higher or equal to the DataReader kind.
And the order between the different kinds is:

``BEST_EFFORT_RELIABILITY_QOS`` < ``RELIABLE_RELIABILITY_QOS``

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_RELIABILITY_QOS_POLICY
   :end-before: //! DDS_RELIABILITY_QOS_POLICY

.. _resourcelimitsqospolicy:

ResourceLimitsQosPolicy
^^^^^^^^^^^^^^^^^^^^^^^

This QoS Policy controls the resources that the service can use in order to meet the requirements imposed by the
application and other QoS Policies.

List of QoS Policy data members:

* ``ResourceLimitsQosPolicy::max_samples``
    Controls the maximum number of samples that the DataWriter or DataReader can manage across all the instances associated with it.
    In other words, it represents the maximum samples that the middleware can store for a DataReader or DataWriter.
* ``ResourceLimitsQosPolicy::max_instances``
    Controls the maximum number of instances that a DataWriter or DataReader can manage.
* ``ResourceLimitsQosPolicy::max_samples_per_instance``
    Controls the maximum number of samples within an instance that the DataWriter or DataReader can manage.

.. _resourcelimits_consistencyrule:

Consistency Rule
""""""""""""""""

To maintain the consistency within the ResourceLimitsQosPolicy, the values of the data members must follow the next
conditions:

* The value of ``ResourceLimitsQosPolicy::max_samples`` must be higher or equal to the value of ``ResourceLimitsQosPolicy::max_samples_per_instance``.
* The value established for the :ref:`historyqospolicy` ``HistoryQosPolicy::depth`` must be lower or equal to the value stated for ``ResourceLimitsQosPolicy::max_samples_per_instance``.

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_RESOURCELIMIT_QOS_POLICY
   :end-before: //! DDS_RESOURCELIMIT_QOS_POLICY

.. _writerdatalifecycleqospolicy:

WriterDataLifecycleQosPolicy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This QoS Policy has a single ``autodispose_unregistered_instances`` attribute that controls the behavior of the :ref:`dds_layers_publication_datawriter` with regards to the lifecycle of the data-instances it manages, that is, the data-instances that have been either explicitly registered with the :ref:`dds_layers_publication_datawriter` using the register operations or implicitly by directly writing the data.
Setting it to true causes the DataWriter to dispose the instance each time it is unregistered. Setting it to false will not cause this automatic disposal upon unregistering. The application can still call one of the dispose operations prior to unregistering the instance and accomplish the same effect.
The default value is ``autodispose_unregistered_instances = true``.

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_WRITERDATALIFECYCLE_QOS_POLICY
   :end-before: //! DDS_WRITERDATALIFECYCLE_QOS_POLICY

.. _datarepresentationqospolicy:

DataRepresentationQosPolicy
"""""""""""""""""""""""""""

This QoS Policy indicates offered/requested data representation for the service.
DataWriters offer a single representation.
A writer will use its offered policy to communicate with its matched readers.
DataReaders request one or more representations.

List of Data Representations:

* ``XCDR_DATA_REPRESENTATION``
    Extended CDR Encoding version 1 (Set by default).
* ``XCDR2_DATA_REPRESENTATION``
    Extended CDR Encoding version 2.
* ``XML_DATA_REPRESENTATION``
    XML Data Representation (Unsupported).

If no data representation is set it is considered an ``INCONSISTENT_POLICY``.

.. _datarepresentation_compatibilityrule:

Compatibility Rule
""""""""""""""""""

If a DataWriter's offered representation is contained within DataReader's requested data representations, the offer
satisfies the request and the policies are compatible.
Otherwise, they are incompatible.

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_DATA_REPRESENTATION_QOS_POLICY
   :end-before: //! DDS_DATA_REPRESENTATION_QOS_POLICY

.. _dds_layers_infrastructure_safedds_policies:

Safe DDS QoS Policies
---------------------

The following QoS Policies are defined in the Safe DDS API, but they are not part of the DDS specification.

.. _dds_layers_infrastructure_safedds_policies_domainparticipantwireprotocolconfigqospolicy:

DomainParticipantWireProtocolQosPolicy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This QoS Policy controls the protocol used to exchange messages between the DataWriters and DataReaders at the DomainParticipant level.

List of QoS Policy data members:

* ``DomainParticipantWireProtocolQosPolicy::guid_prefix``
    The prefix used to identify the DDS entities of the :ref:`dds_layers_domain_participant`.
* ``DomainParticipantWireProtocolQosPolicy::lease_duration``
    The lease duration for the :ref:`dds_layers_domain_participant`.
* ``DomainParticipantWireProtocolQosPolicy::announcement_period``
    The announcement period for the :ref:`dds_layers_domain_participant`.
* ``DomainParticipantWireProtocolQosPolicy::announced_locator``
    The announced locator for the :ref:`dds_layers_domain_participant`.
* ``DomainParticipantWireProtocolQosPolicy::use_multicast_discovery``
    Enable or disable multicast locators on the discovery protocol.
* ``DomainParticipantWireProtocolQosPolicy::input_integrity``
    The :ref:`dds_layers_infrastructure_safedds_policies_integritychecks_inputintegritycheck` configuration for received messages on the :ref:`dds_layers_domain_participant`.
* ``DomainParticipantWireProtocolQosPolicy::builtin_output_integrity``
    The :ref:`dds_layers_infrastructure_safedds_policies_integritychecks_outputintegritycheck` configuration for the :ref:`dds_layers_domain_participant` builtin entities.
* ``DomainParticipantWireProtocolQosPolicy::initial_peers``
    The initial peers locator list for the :ref:`dds_layers_domain_participant`.
* ``DomainParticipantWireProtocolQosPolicy::discovery_heartbeat_period``
    The heartbeat period for the discovery protocol.
* ``DomainParticipantWireProtocolQosPolicy::discovery_acknack_delay``
    The delay for the discovery protocol acknowledgment.


.. include:: ../../../safety_manual/rules/RULE_DOMAINPARTICIPANT_WIREPROTOCOLCONFIGQOS.inc

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_DOMAINPARTICIPANTWIREPROTOCOLCONFIG_QOS_POLICY
   :end-before: //! DDS_DOMAINPARTICIPANTWIREPROTOCOLCONFIG_QOS_POLICY

.. _dds_layers_infrastructure_safedds_policies_datareaderwireprotocolconfigqospolicy:

DataReaderWireProtocolQosPolicy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This QoS Policy controls the protocol used to exchange messages between the DataWriters and DataReaders at the DataReader level.

List of QoS Policy data members:

* ``DataReaderWireProtocolQosPolicy::output_integrity``
    The :ref:`dds_layers_infrastructure_safedds_policies_integritychecks_outputintegritycheck` configuration for message sent from the :ref:`dds_layers_subscription_datareader`.
* ``DataReaderWireProtocolQosPolicy::acknack_delay``
    The delay for the acknowledgment of the received messages.
* ``DataReaderWireProtocolQosPolicy::unicast_endpoint_locator``
    An optional announced unicast endpoint locator for the :ref:`dds_layers_subscription_datareader`.
* ``DataReaderWireProtocolQosPolicy::multicast_endpoint_locator``
    An optional announced multicast endpoint locator for the :ref:`dds_layers_subscription_datareader`.
* ``DataReaderWireProtocolQosPolicy::max_samples_per_request``
    The maximum number of samples that the :ref:`dds_layers_subscription_datareader` will request for each sample notification.
    The value of ``0`` means that the DataReader will request all the samples available.

.. include:: ../../../safety_manual/rules/RULE_DATAREADER_WIREPROTOCOLCONFIGQOS.inc

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_DATAREADERWIREPROTOCOLCONFIG_QOS_POLICY
   :end-before: //! DDS_DATAREADERWIREPROTOCOLCONFIG_QOS_POLICY

.. _dds_layers_infrastructure_safedds_policies_datawriterwireprotocolconfigqospolicy:

DataWriterWireProtocolQosPolicy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This QoS Policy controls the protocol used to exchange messages between the DataWriters and DataReaders at the DataWriter level.

List of QoS Policy data members:

* ``DataWriterWireProtocolQosPolicy::output_integrity``
    The :ref:`dds_layers_infrastructure_safedds_policies_integritychecks_outputintegritycheck` configuration for message sent from the :ref:`dds_layers_publication_datawriter`.
* ``DataWriterWireProtocolQosPolicy::heartbeat_period``
    The heartbeat period for the :ref:`dds_layers_publication_datawriter`.
* ``DataWriterWireProtocolQosPolicy::unicast_endpoint_locator``
    An optional announced unicast endpoint locator for the :ref:`dds_layers_publication_datawriter`.
* ``DataWriterWireProtocolQosPolicy::push_mode``
    The transmission mode for the :ref:`dds_layers_publication_datawriter`.
    If set to ``true``, the DataWriter will push the data to the DataReaders, otherwise, the DataReaders will pull the data from the DataWriter.
    Best effort DataWriters will be incompatible with push mode set to ``false``.

.. include:: ../../../safety_manual/rules/RULE_DATAWRITER_WIREPROTOCOLCONFIGQOS.inc

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_DATAWRITERWIREPROTOCOLCONFIG_QOS_POLICY
   :end-before: //! DDS_DATAWRITERWIREPROTOCOLCONFIG_QOS_POLICY

.. _dds_layers_infrastructure_safedds_preallocmemoryconfig:

PreallocMemoryConfig
^^^^^^^^^^^^^^^^^^^^

This QoS Policy controls the resources that a certain object can use in order to meet the requirements imposed by the application.

As explained in :ref:`architecture_platform_memory_management`, Safe DDS can operate in a preallocated memory mode where the referred objects or entities has the ability of having a preallocated memory pool that can increase to a maximum size.

List of QoS Policy data members:

* ``PreallocMemoryConfig::preallocated``
    Number of preallocated elements in the memory pool.
* ``PreallocMemoryConfig::max_elements``
    Maximum number of elements in the memory pool.

Safe DDS defines ``DEFAULT_MEMORY_CONFIG`` as the default memory configuration for all the objects that can be configured with this QoS Policy.
For this value, the preallocated memory pool size is 0 and the maximum size is ``UINT32_MAX``, which means that the memory pool can grow to the maximum size of the memory available.

.. include:: ../../../safety_manual/rules/RULE_PREALLOCMEMORYCONFIG.inc

.. note::

   Check :ref:`architecture_platform_memory_management` to understand how memory is managed in Safe DDS.

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_PREALLOCMEMORYCONFIG_QOS_POLICY
   :end-before: //! DDS_PREALLOCMEMORYCONFIG_QOS_POLICY

.. _dds_layers_infrastructure_safedds_policies_domainparticipantallocationsqospolicy:

DomainParticipantAllocationsQosPolicy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This QoS Policy controls the memory involved in the behaviour of :ref:`dds_layers_domain_participant`.

It contains a set of :ref:`dds_layers_infrastructure_safedds_preallocmemoryconfig` QoS Policies that controls the memory pools involved in the operation of the :ref:`dds_layers_domain_participant`.

List of QoS Policy data members:

* ``DomainParticipantAllocationsQosPolicy::local_participants``
    The configuration of the memory used by the local DomainParticipants storage.
* ``DomainParticipantAllocationsQosPolicy::remote_participants``
    The configuration of the memory used by the remote DomainParticipants storage.
* ``DomainParticipantAllocationsQosPolicy::local_datawriters``
    The configuration of the memory used by the local DataWriters storage.
* ``DomainParticipantAllocationsQosPolicy::remote_datawriters``
    The configuration of the memory used by the remote DataWriters storage.
* ``DomainParticipantAllocationsQosPolicy::local_datareaders``
    The configuration of the memory used by the local DataReaders storage.
* ``DomainParticipantAllocationsQosPolicy::remote_datareaders``
    The configuration of the memory used by the remote DataReaders storage.
* ``DomainParticipantAllocationsQosPolicy::local_subscriptions``
    The configuration of the memory used by the local Subscriptions storage.
* ``DomainParticipantAllocationsQosPolicy::local_publications``
    The configuration of the memory used by the local Publications storage.
* ``DomainParticipantAllocationsQosPolicy::participant_observers``
    The configuration of the memory used by the ParticipantObservers storage.
* ``DomainParticipantAllocationsQosPolicy::local_topics``
    The configuration of the memory used by the local Topics storage.
* ``DomainParticipantAllocationsQosPolicy::local_types``
    The configuration of the memory used by the local Types storage.

.. note::

   Check :ref:`architecture_platform_memory_management` to understand how memory is managed in Safe DDS.

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_DOMAINPARTICIPANTALLOCATIONS_QOS_POLICY
   :end-before: //! DDS_DOMAINPARTICIPANTALLOCATIONS_QOS_POLICY

.. _dds_layers_infrastructure_safedds_policies_topicallocationsqospolicy:

TopicAllocationsQosPolicy
^^^^^^^^^^^^^^^^^^^^^^^^^

.. include:: ../../../safety_manual/rules/RULE_TOPIC_ALLOCATIONSQOS.inc

This QoS Policy controls the memory involved in the behaviour of :ref:`dds_layers_topic`.

It contains a set of :ref:`dds_layers_infrastructure_safedds_preallocmemoryconfig` QoS Policies that controls the memory pools of topic samples and topic interactions with other entities.

List of QoS Policy data members:

* ``TopicAllocationsQosPolicy::observers``
    Memory configuration of observers attached to the topic.
    This value shall match the maximum number of :ref:`dds_layers_subscription_datareader` and :ref:`dds_layers_publication_datawriter` that will be attached to the topic.
* ``TopicAllocationsQosPolicy::preallocated_samples``
    Number of samples allocated upon creation of the topic.
* ``TopicAllocationsQosPolicy::extra_payload_size``
    Allowed extra payload size allocated for each sample in the topic. Defaults to 0.
    This value is intended to be used when handling extensible (such as Appendable or Mutable IDL types) data types that may come with a size larger than the ``TypeSupport::max_serialized_size`` of the type.

.. note::

   Check :ref:`architecture_platform_memory_management` to understand how memory is managed in Safe DDS.

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_TOPICALLOCATIONS_QOS_POLICY
   :end-before: //! DDS_TOPICALLOCATIONS_QOS_POLICY

.. _dds_layers_infrastructure_safedds_policies_datawriterallocationsqospolicy:

DataWriterAllocationsQosPolicy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This QoS Policy controls the memory involved in the behaviour of :ref:`dds_layers_publication_datawriter`.

It contains a set of :ref:`dds_layers_infrastructure_safedds_preallocmemoryconfig` QoS Policies and ``uint32_t`` values that controls the memory pools involved in the operation of the :ref:`dds_layers_publication_datawriter`.

List of QoS Policy data members:

* ``DataWriterAllocationsQosPolicy::preallocated_instances``
    Numeric value with preallocated memory configuration of instances that the :ref:`dds_layers_publication_datawriter` can manage.
* ``DataWriterAllocationsQosPolicy::preallocated_samples_per_instance``
    Numeric value with preallocated memory configuration of samples per instance that the :ref:`dds_layers_publication_datawriter` can manage.
* ``DataWriterAllocationsQosPolicy::remote_readers``
    Memory configuration of remote readers that the :ref:`dds_layers_publication_datawriter` can manage.

.. include:: ../../../safety_manual/rules/RULE_DATAWRITER_ALLOCATIONSQOS.inc

.. note::

   Maximum elements for the instances and samples configuration is retrieved from the :ref:`resourcelimitsqospolicy` configuration of the parent :ref:`dds_layers_datawriter_qos`

.. note::

   Check :ref:`architecture_platform_memory_management` to understand how memory is managed in Safe DDS.

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_DATAWRITERALLOCATIONS_QOS_POLICY
   :end-before: //! DDS_DATAWRITERALLOCATIONS_QOS_POLICY

.. _dds_layers_infrastructure_safedds_policies_datareaderallocationsqospolicy:

DataReaderAllocationsQosPolicy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This QoS Policy controls the memory involved in the behaviour of :ref:`dds_layers_subscription_datareader`.

It contains a set of :ref:`dds_layers_infrastructure_safedds_preallocmemoryconfig` QoS Policies and ``uint32_t`` values that controls the memory pools involved in the operation of the :ref:`dds_layers_publication_datawriter`.

List of QoS Policy data members:

* ``DataReaderAllocationsQosPolicy::preallocated_instances``
    Numeric value with preallocated memory configuration of instances that the :ref:`dds_layers_subscription_datareader` can manage.
* ``DataReaderAllocationsQosPolicy::preallocated_samples_per_instance``
    Numeric value with preallocated memory configuration of samples per instance that the :ref:`dds_layers_subscription_datareader` can manage.
* ``DataReaderAllocationsQosPolicy::writers_per_instance``
    Memory configuration of how many writes can write in a :ref:`dds_layers_subscription_datareader` instance.
* ``DataReaderAllocationsQosPolicy::remote_writers``
    Memory configuration of remote writers that the :ref:`dds_layers_subscription_datareader` can manage.
* ``DataReaderAllocationsQosPolicy::local_writers``
    Memory configuration of remote writers that the :ref:`dds_layers_subscription_datareader` can manage.

.. include:: ../../../safety_manual/rules/RULE_DATAREADER_ALLOCATIONSQOS.inc

.. note::

   Maximum elements for the instances and samples configuration is retrieved from the :ref:`resourcelimitsqospolicy` configuration of the parent :ref:`dds_layers_datareader_qos`

.. note::

   Check :ref:`architecture_platform_memory_management` to understand how memory is managed in Safe DDS.

Example
"""""""

.. literalinclude:: ../../../code/policies_examples/main.cpp
   :language: c++
   :dedent: 8
   :start-after: // DDS_DATAREADERALLOCATIONS_QOS_POLICY
   :end-before: //! DDS_DATAREADERALLOCATIONS_QOS_POLICY

.. _dds_layers_infrastructure_safedds_policies_integritychecks:

Integrity Checks
^^^^^^^^^^^^^^^^

Safe DDS provides a Cyclic Redundancy Check (CRC) mechanism to ensure the integrity of the data exchanged.
The integrity data is calculated over the RTPS messages and included in the RTPS HeaderExtension submessage.
It can be configured both for different levels of enforcement in the incoming packages, as well as for enabling/disabling its use for sent packages.

.. _dds_layers_infrastructure_safedds_policies_integritychecks_inputintegritycheck:

InputIntegrityCheck
"""""""""""""""""""

Input integrity check configurations available are:

* ``INPUT_INTEGRITY_CHECK_DISABLED``: Integrity data is not processed.
* ``INPUT_INTEGRITY_CHECK_ENABLED``: Integrity data is processed if present.
* ``INPUT_INTEGRITY_CHECK_REQUIRED``: Integrity data is processed and messages where its not present are discarded.

.. _dds_layers_infrastructure_safedds_policies_integritychecks_outputintegritycheck:

OutputIntegrityCheck
""""""""""""""""""""

Output integrity check configurations available are:

* ``OUTPUT_INTEGRITY_CHECK_DISABLED``: Integrity data is not sent.
* ``OUTPUT_INTEGRITY_CHECK_ENABLED``: Integrity data is sent on each datagram.