Refs #11113: pull mode documentation (property)

Signed-off-by: JLBuenoLopez-eProsima <joseluisbueno@eprosima.com>
eProsima · Apr 6, 2021 · 8772557 · 8772557
1 parent 415029d
commit 8772557
Show file tree

Hide file tree

Showing 4 changed files with 77 additions and 1 deletion.
diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp
@@ -529,6 +529,17 @@ void dds_domain_examples()
         //!--
     }
 
+    {
+        // PULL_MODE_DATAWRITER
+        DataWriterQos wqos;
+
+        // Enable pull mode
+        wqos.properties().properties().emplace_back(
+            "pushMode",
+            "false");
+        //!--
+    }
+
     {
         //CONF-QOS-PARTITIONS
         PublisherQos pub_11_qos;

diff --git a/code/XMLTester.xml b/code/XMLTester.xml
@@ -2915,6 +2915,20 @@
 </participant>
 <!--><-->
 
+<!-->PULL_MODE_DATAWRITER<-->
+<data_writer profile_name="pull_mode_datawriter_xml_profile">
+    <propertiesPolicy>
+        <properties>
+            <!-- Enable pull mode -->
+            <property>
+                <name>pushMode</name>
+                <value>false</value>
+            </property>
+        </properties>
+    </propertiesPolicy>
+</data_writer>
+<!--><-->
+
 <!-->
 </profiles>
 <-->

diff --git a/docs/fastdds/property_policies/non_consolidated_qos.rst b/docs/fastdds/property_policies/non_consolidated_qos.rst
@@ -11,11 +11,61 @@ Before consolidating a new QoS Policy, it is usually set using this generic QoS
 Consequently, this section is prone to frequent updates so the user is advised to check latest changes after upgrading
 to a different release version.
 
+.. _push_mode_qos_policy:
+
 ``PushMode`` QoS Policy
 ^^^^^^^^^^^^^^^^^^^^^^^
 
+By default, Fast DDS DataWriters are enabled using the ``push mode``.
+This implies that the DataWriters start publishing and sending data following its own logic, disregarding if there are
+any DataReaders matched in the same topic.
+Using the :ref:`propertypolicyqos` DataWriters can be enabled using the ``pull mode``.
+This entails that the DataWriters thus enabled will only send data upon the reception of acknack submessages coming from
+the matched DataReaders.
+
+Enabling ``pull mode`` implies that the |DataWriter::write-api| operation will only include the sample in the
+DataWriter's History without notifying or sending the sample to any matched DataReader.
+Periodically, DataWriters send its status by means of a heartbeat.
+Upon reception of the heartbeat, DataReaders will be informed of samples on the DataWriter's History that are new.
+DataReaders will answer with an acknack submessage which will trigger the sending of the sample on the DataWriter's
+side.
+Consequently, the publishing rate can be tuned setting the heartbeat period accordingly.
+
+.. list-table::
+   :header-rows: 1
+   :align: left
+
+   * - PropertyPolicyQos name
+     - PropertyPolicyQos value
+     - Default value
+   * - ``"pushMode"``
+     - ``"true"``/``"false"``
+     - ``"true"``
+
++----------------------------------------------------------------------------------------------------------------------+
+| **C++**                                                                                                              |
++----------------------------------------------------------------------------------------------------------------------+
+| .. literalinclude:: /../code/DDSCodeTester.cpp                                                                       |
+|    :language: c++                                                                                                    |
+|    :start-after: // PULL_MODE_DATAWRITER                                                                             |
+|    :end-before: //!--                                                                                                |
+|    :dedent: 8                                                                                                        |
++----------------------------------------------------------------------------------------------------------------------+
+| **XML**                                                                                                              |
++----------------------------------------------------------------------------------------------------------------------+
+| .. literalinclude:: /../code/XMLTester.xml                                                                           |
+|    :language: xml                                                                                                    |
+|    :start-after: <!-->PULL_MODE_DATAWRITER<-->                                                                       |
+|    :end-before: <!--><-->                                                                                            |
++----------------------------------------------------------------------------------------------------------------------+
+
 .. warning::
-    This section is still under work.
+    It is inconsistent to enable the ``pull mode`` and also set the |ReliabilityQosPolicyKind-api| to
+    |BEST_EFFORT_RELIABILITY_QOS-api|.
+
+    It is inconsistent to enable the ``pull mode`` and also set the |WriterTimes::heartbeatPeriod-api| to
+    |c_TimeInfinite-api|.
+
 
 Unique network flows QoS Policy
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
@@ -140,6 +140,7 @@ preallocation
 preconfigure
 preprocessor
 programmatically
+pushMode
 QoS
 QosPolicyCount
 quadratically