From dfee72ea406481740a80fe96441b62659809fe03 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 1/3] 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 (cherry picked from commit 157375dddeed38833da31f0458b0f22c586fa209) # Conflicts: # docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst --- .../core/policy/standardQosPolicies.rst | 343 +++++++++++------- 1 file changed, 206 insertions(+), 137 deletions(-) diff --git a/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst b/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst index a243990d2..8c8e804b9 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: //! +.. tabs:: + + .. tab:: 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: <--> + + .. 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: //! +.. tabs:: -XML -*** -.. literalinclude:: ../../../../../code/XMLTester.xml - :language: xml - :start-after: PUBSUB_API_CONF_PUBSUB_DURABILITY - :end-before: <--> + .. 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:: -XML -*** -This QoS Policy cannot be configured using XML for the moment. + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_ENTITY_FACTORY_QOS_POLICY + :end-before: //! + + .. tab:: XML + + 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: //! +.. 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: <--> -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: //! +.. tabs:: -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: XML_LIFESPAN - :end-before: <--> + .. 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: //! +.. tabs:: -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: PUBSUB_API_CONF_PUBSUB_LIVELINESS - :end-before: <--> + .. 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: @@ -759,17 +799,28 @@ Table with the possible combinations: Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_OWNERSHIP_QOS_POLICY - :end-before: //! +.. tabs:: +<<<<<<< HEAD XML *** This QoS Policy cannot be configured using XML for the moment. +======= + .. 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: <--> +>>>>>>> 157375d (Improve History QoS documentation and compatibility rules (#664)) .. _ownershipstrengthqospolicy: @@ -797,17 +848,29 @@ 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:: +<<<<<<< HEAD XML *** This QoS Policy cannot be configured using XML for the moment. +======= + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_OWNERSHIP_STRENGTH_QOS_POLICY + :end-before: //! + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: PUBSUB_API_CONF_PUBSUB_OWNERSHIP_STRENGTH + :end-before: <--> + +>>>>>>> 157375d (Improve History QoS documentation and compatibility rules (#664)) .. _partitionqospolicy: @@ -845,20 +908,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: //! +.. tabs:: -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: XML-PARTITION - :end-before: <--> + .. 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: @@ -1113,20 +1178,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: //! +.. tabs:: -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: XML_RELIABILITY - :end-before: <--> + .. 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: @@ -1192,20 +1259,22 @@ conditions: Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_RESOURCE_LIMITS_QOS_POLICY - :end-before: //! +.. tabs:: -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: XML_RESOURCE_LIMITS - :end-before: <--> + .. 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: @@ -1268,7 +1337,7 @@ Example .. tab:: C++ - .. literalinclude:: ../../../../../code/DDSCodeTester.cpp + .. literalinclude:: /../code/DDSCodeTester.cpp :language: c++ :dedent: 8 :start-after: //DDS_CHANGE_TOPIC_DATA_QOS_POLICY @@ -1276,7 +1345,7 @@ Example .. tab:: XML - .. literalinclude:: ../../../../../code/XMLTester.xml + .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: XML_CHANGE_TOPIC_DATA_QOS_POLICY :end-before: <--> @@ -1339,7 +1408,7 @@ Example .. tab:: C++ - .. literalinclude:: ../../../../../code/DDSCodeTester.cpp + .. literalinclude:: /../code/DDSCodeTester.cpp :language: c++ :dedent: 8 :start-after: //DDS_CHANGE_USER_DATA_QOS_POLICY @@ -1347,7 +1416,7 @@ Example .. tab:: XML - .. literalinclude:: ../../../../../code/XMLTester.xml + .. literalinclude:: /../code/XMLTester.xml :language: xml :start-after: XML_CHANGE_USER_DATA_QOS_POLICY :end-before: <--> From ddee78b9ba93baa2ee815ed31be5821504b45e4a Mon Sep 17 00:00:00 2001 From: JesusPoderoso Date: Tue, 20 Feb 2024 15:24:07 +0100 Subject: [PATCH 2/3] Refs #20401: Fix conlficts Signed-off-by: JesusPoderoso --- .../core/policy/standardQosPolicies.rst | 23 ++----------------- 1 file changed, 2 insertions(+), 21 deletions(-) diff --git a/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst b/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst index 8c8e804b9..6c8e12eb9 100644 --- a/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst +++ b/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst @@ -801,11 +801,6 @@ Example .. tabs:: -<<<<<<< HEAD -XML -*** -This QoS Policy cannot be configured using XML for the moment. -======= .. tab:: C++ .. literalinclude:: /../code/DDSCodeTester.cpp @@ -816,11 +811,7 @@ This QoS Policy cannot be configured using XML for the moment. .. tab:: XML - .. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: PUBSUB_API_CONF_PUBSUB_OWNERSHIP - :end-before: <--> ->>>>>>> 157375d (Improve History QoS documentation and compatibility rules (#664)) + This QoS Policy cannot be configured using XML for the moment. .. _ownershipstrengthqospolicy: @@ -850,11 +841,6 @@ Example .. tabs:: -<<<<<<< HEAD -XML -*** -This QoS Policy cannot be configured using XML for the moment. -======= .. tab:: C++ .. literalinclude:: /../code/DDSCodeTester.cpp @@ -865,12 +851,7 @@ This QoS Policy cannot be configured using XML for the moment. .. tab:: XML - .. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: PUBSUB_API_CONF_PUBSUB_OWNERSHIP_STRENGTH - :end-before: <--> - ->>>>>>> 157375d (Improve History QoS documentation and compatibility rules (#664)) + This QoS Policy cannot be configured using XML for the moment. .. _partitionqospolicy: From 717e786fafbff3f94e3451654ffcb424b1da28fa Mon Sep 17 00:00:00 2001 From: Eduardo Ponz Segrelles Date: Thu, 22 Feb 2024 14:49:37 +0100 Subject: [PATCH 3/3] Clarify depth vs max_samples_per_instance inconsistency (#679) Signed-off-by: EduPonz --- .../core/policy/standardQosPolicies.rst | 35 ++++++++++--------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst b/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst index 6c8e12eb9..511953457 100644 --- a/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst +++ b/docs/fastdds/dds_layer/core/policy/standardQosPolicies.rst @@ -478,24 +478,27 @@ The HistoryQos must be set consistently with the :ref:`resourcelimitsqospolicy`, * 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 + that the |HistoryQosPolicy::depth-api| must be lower or equal 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 + Also, |ResourceLimitsQosPolicy::max_samples-api| must be equal or higher than the product of + |ResourceLimitsQosPolicy::max_samples_per_instance-api| times |ResourceLimitsQosPolicy::max_instances-api|. +* The |HistoryQosPolicy::depth-api| cannot be lower or equal than zero. + If an unlimited depth is required, please consider using |HistoryQosPolicy::kind-api| as |KEEP_ALL_HISTORY_QOS-api|. +* Setting the |HistoryQosPolicy::kind-api| as |KEEP_ALL_HISTORY_QOS-api| entails that limits are set by 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. +* In the case of the :ref:`reliabilityqospolicy` |ReliabilityQosPolicyKind-api| being set to + |RELIABLE_RELIABILITY_QOS-api| and the :ref:`historyqospolicy` |HistoryQosPolicy::kind-api| being set to + |KEEP_ALL_HISTORY_QOS-api|, when the resource limits are reached, the behavior of the service is depends on the + :ref:`durabilityqospolicy`: + + * If the :ref:`durabilityqospolicy` |DurabilityQosPolicy::kind-api| is configured as |VOLATILE_DURABILITY_QOS-api|, + the DataWriter |DataWriter::write-api| call will discard the oldest sample in the history. + Note that the removed sample may belong to different :ref:`instances` than the newly + written one. + * If the :ref:`durabilityqospolicy` |DurabilityQosPolicy::kind-api| is configured as + |TRANSIENT_LOCAL_DURABILITY_QOS-api| or |TRANSIENT_DURABILITY_QOS-api|, the DataWriter |DataWriter::write-api| call + will be blocked until the history has space for the new sample. Example """""""