From 157375dddeed38833da31f0458b0f22c586fa209 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Poderoso?= <120394830+JesusPoderoso@users.noreply.github.com> Date: Tue, 20 Feb 2024 14:34:17 +0100 Subject: [PATCH] Improve History QoS documentation and compatibility rules (#664) * Refs #20401: Improve History documentation Signed-off-by: JesusPoderoso * Refs #20401: Update example to out last standard tabs format Signed-off-by: JesusPoderoso * Refs #20401: Update all file examples Signed-off-by: JesusPoderoso * Refs #20401: Add NIT to explanation Signed-off-by: JesusPoderoso * Refs #20401: Fix doc tab Signed-off-by: JesusPoderoso * Refs #20401: Apply spaces rev suggestion Signed-off-by: JesusPoderoso * Refs #20401: Apply documentation rev suggestions Signed-off-by: JesusPoderoso * Refs #20401: Apply documentation update based on internal discussion Signed-off-by: JesusPoderoso * Refs #20401: Remove old explanation Signed-off-by: JesusPoderoso * Refs #20401: Improve documentation Signed-off-by: JesusPoderoso * Refs #20401: Apply NIT Signed-off-by: JesusPoderoso --------- Signed-off-by: JesusPoderoso --- .../core/policy/standardQosPolicies.rst | 366 ++++++++++-------- 1 file changed, 208 insertions(+), 158 deletions(-) diff --git a/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst b/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst index d0c36ac41..ac18b4ca1 100644 --- a/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst +++ b/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst @@ -70,20 +70,23 @@ period must be higher or equal to the minimum separation. Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_DEADLINE_QOS_POLICY - :end-before: //! - -XML -*** -.. literalinclude:: ../../../../../code/XMLTester.xml - :language: xml - :start-after: XML_DEADLINE - :end-before: <--> +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_DEADLINE_QOS_POLICY + :end-before: //! + + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: XML_DEADLINE + :end-before: <--> .. _destinationorderqospolicy: @@ -252,20 +255,22 @@ Table with the possible combinations: Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_DURABILITY_QOS_POLICY - :end-before: //! - -XML -*** -.. literalinclude:: ../../../../../code/XMLTester.xml - :language: xml - :start-after: PUBSUB_API_CONF_PUBSUB_DURABILITY - :end-before: <--> +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_DURABILITY_QOS_POLICY + :end-before: //! + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: PUBSUB_API_CONF_PUBSUB_DURABILITY + :end-before: <--> .. _durabilityserviceqospolicy: @@ -357,17 +362,19 @@ List of QoS Policy data members: Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_ENTITY_FACTORY_QOS_POLICY - :end-before: //! +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_ENTITY_FACTORY_QOS_POLICY + :end-before: //! + + .. tab:: XML -XML -*** -This QoS Policy cannot be configured using XML for the moment. + This QoS Policy cannot be configured using XML for the moment. .. _groupqospolicy: @@ -401,7 +408,7 @@ Example .. tab:: C++ - .. literalinclude:: ../../../../../code/DDSCodeTester.cpp + .. literalinclude:: /../code/DDSCodeTester.cpp :language: c++ :dedent: 8 :start-after: //DDS_CHANGE_GROUP_DATA_QOS_POLICY @@ -409,7 +416,7 @@ Example .. tab:: XML - .. literalinclude:: ../../../../../code/XMLTester.xml + .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: XML_CHANGE_GROUP_DATA_QOS_POLICY :end-before: <--> @@ -459,28 +466,57 @@ There are two possible values (see |HistoryQosPolicyKind-api|): 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. +.. _historyqospolicy_consistency: + +Consistency rule +"""""""""""""""" + +The HistoryQos must be set consistently with the :ref:`resourcelimitsqospolicy`, but also other QoS as +:ref:`durabilityqospolicy` and :ref:`reliabilityqospolicy`, so there are several cases to take into account: + +* The |HistoryQosPolicy::depth-api| is only considered if the |HistoryQosPolicy::kind-api| is set to + |KEEP_LAST_HISTORY_QOS-api|. +* The |HistoryQosPolicy::depth-api| must be consistent with the :ref:`resourcelimitsqospolicy` settings, which means + that the |HistoryQosPolicy::depth-api| must be equal or lower than the :ref:`resourcelimitsqospolicy`'s + |ResourceLimitsQosPolicy::max_samples_per_instance-api|. + Also, |ResourceLimitsQosPolicy::max_samples-api| must be equal or higher than + |ResourceLimitsQosPolicy::max_samples_per_instance-api|. +* The |HistoryQosPolicy::depth-api| cannot be less or equal than zero. + If unlimited resources required, please consider using |HistoryQosPolicy::kind-api| as |KEEP_ALL_HISTORY_QOS-api|. +* Setting the |HistoryQosPolicy::kind-api| as |KEEP_ALL_HISTORY_QOS-api| uses the :ref:`resourcelimitsqospolicy` + limits (|ResourceLimitsQosPolicy::max_samples_per_instance-api| prior than + |ResourceLimitsQosPolicy::max_samples-api|). +* In case the :ref:`reliabilityqospolicy` is set as |RELIABLE_RELIABILITY_QOS-api|, the |HistoryQosPolicy::kind-api| is + configured as |KEEP_ALL_HISTORY_QOS-api|, the resource limits are reached, and based on the :ref:`durabilityqospolicy` + configuration: + + * If the |DurabilityQosPolicy::kind-api| is configured as |VOLATILE_DURABILITY_QOS-api|, the DataWriter publication + will discard the oldest samples. + Those samples may belong to different :ref:`instances`. + * If the |DurabilityQosPolicy::kind-api| is configured as |TRANSIENT_LOCAL_DURABILITY_QOS-api| or + |TRANSIENT_DURABILITY_QOS-api|, the DataWriter publication will be blocked. Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_HISTORY_QOS_POLICY - :end-before: //! - -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: XML-HISTORY<--> - :end-before: <--> +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_HISTORY_QOS_POLICY + :end-before: //! + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: XML-HISTORY<--> + :end-before: <--> + .. _latencybudgetqospolicy: @@ -553,20 +589,22 @@ List of QoS Policy data members: Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_LIFESPAN_QOS_POLICY - :end-before: //! - -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: XML_LIFESPAN - :end-before: <--> +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_LIFESPAN_QOS_POLICY + :end-before: //! + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: XML_LIFESPAN + :end-before: <--> .. _livelinessqospolicy: @@ -674,20 +712,22 @@ the |LivelinessQosPolicy::lease_duration-api| of the DataReader. Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_LIVELINESS_QOS_POLICY - :end-before: //! - -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: PUBSUB_API_CONF_PUBSUB_LIVELINESS - :end-before: <--> +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_LIVELINESS_QOS_POLICY + :end-before: //! + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: PUBSUB_API_CONF_PUBSUB_LIVELINESS + :end-before: <--> .. _ownershipqospolicy: @@ -761,20 +801,22 @@ Table with the possible combinations: Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_OWNERSHIP_QOS_POLICY - :end-before: //! - -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: PUBSUB_API_CONF_PUBSUB_OWNERSHIP - :end-before: <--> +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_OWNERSHIP_QOS_POLICY + :end-before: //! + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: PUBSUB_API_CONF_PUBSUB_OWNERSHIP + :end-before: <--> .. _ownershipstrengthqospolicy: @@ -802,20 +844,22 @@ List of QoS Policy data members: Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_OWNERSHIP_STRENGTH_QOS_POLICY - :end-before: //! +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_OWNERSHIP_STRENGTH_QOS_POLICY + :end-before: //! -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: PUBSUB_API_CONF_PUBSUB_OWNERSHIP_STRENGTH - :end-before: <--> + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: PUBSUB_API_CONF_PUBSUB_OWNERSHIP_STRENGTH + :end-before: <--> .. _partitionqospolicy: @@ -854,20 +898,22 @@ List of QoS Policy data members: Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_PARTITION_QOS_POLICY - :end-before: //! - -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: XML-PARTITION - :end-before: <--> +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_PARTITION_QOS_POLICY + :end-before: //! + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: XML-PARTITION + :end-before: <--> .. _presentationqospolicy: @@ -1122,20 +1168,22 @@ Table with the possible combinations: Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_RELIABILITY_QOS_POLICY - :end-before: //! - -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: XML_RELIABILITY - :end-before: <--> +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_RELIABILITY_QOS_POLICY + :end-before: //! + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: XML_RELIABILITY + :end-before: <--> .. _resourcelimitsqospolicy: @@ -1204,20 +1252,22 @@ conditions: Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_RESOURCE_LIMITS_QOS_POLICY - :end-before: //! - -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: XML_RESOURCE_LIMITS - :end-before: <--> +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_RESOURCE_LIMITS_QOS_POLICY + :end-before: //! + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: XML_RESOURCE_LIMITS + :end-before: <--> .. _timebasedfilterqospolicy: @@ -1280,7 +1330,7 @@ Example .. tab:: C++ - .. literalinclude:: ../../../../../code/DDSCodeTester.cpp + .. literalinclude:: /../code/DDSCodeTester.cpp :language: c++ :dedent: 8 :start-after: //DDS_CHANGE_TOPIC_DATA_QOS_POLICY @@ -1288,7 +1338,7 @@ Example .. tab:: XML - .. literalinclude:: ../../../../../code/XMLTester.xml + .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: XML_CHANGE_TOPIC_DATA_QOS_POLICY :end-before: <--> @@ -1351,7 +1401,7 @@ Example .. tab:: C++ - .. literalinclude:: ../../../../../code/DDSCodeTester.cpp + .. literalinclude:: /../code/DDSCodeTester.cpp :language: c++ :dedent: 8 :start-after: //DDS_CHANGE_USER_DATA_QOS_POLICY @@ -1359,7 +1409,7 @@ Example .. tab:: XML - .. literalinclude:: ../../../../../code/XMLTester.xml + .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: XML_CHANGE_USER_DATA_QOS_POLICY :end-before: <-->