[11113] Pull mode property documentation

code/DDSCodeTester.cpp

@@ -526,6 +526,17 @@ void dds_domain_examples()
         //!--
     }
 
+    {
+        // PULL_MODE_DATAWRITER
+        DataWriterQos wqos;
+
+        // Enable pull mode
+        wqos.properties().properties().emplace_back(
+            "fastdds.push_mode",
+            "false");
+        //!--
+    }
+
     {
         //CONF-QOS-PARTITIONS
         PublisherQos pub_11_qos;

code/XMLTester.xml

@@ -2915,6 +2915,24 @@
 </participant>
 <!--><-->
 
+<!-->PULL_MODE_DATAWRITER<-->
+<!--
+<?xml version="1.0" encoding="UTF-8" ?>
+<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
+-->
+<data_writer profile_name="pull_mode_datawriter_xml_profile">
+    <propertiesPolicy>
+        <properties>
+            <!-- Enable pull mode -->
+            <property>
+                <name>fastdds.push_mode</name>
+                <value>false</value>
+            </property>
+        </properties>
+    </propertiesPolicy>
+</data_writer>
+<!--><-->
+
 <!-->
 </profiles>
 <-->

docs/fastdds/dds_layer/publisher/dataWriter/dataWriter.rst

@@ -77,6 +77,14 @@ Internally it contains the following |QosPolicy-api| objects:
 | |DataSharingQosPolicy|           | |DataWriterQos::data_sharing-api|               | No       |
 +----------------------------------+-------------------------------------------------+----------+
 
+The following non-consolidated property-assigned QoS apply to DataWriters:
+
++----------------------------------+-------------------------------------------------+
+| Property name                    | Non-consolidated QoS                            |
++==================================+=================================================+
+| fastdds.push_mode                | :ref:`push_mode_qos_policy`                     |
++----------------------------------+-------------------------------------------------+
+
 Refer to the detailed description of each |QosPolicy-api| class for more information about their usage and
 default values.
 

docs/fastdds/property_policies/non_consolidated_qos.rst

@@ -11,11 +11,67 @@ 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.
 
-``PushMode`` QoS Policy
-^^^^^^^^^^^^^^^^^^^^^^^
+.. _push_mode_qos_policy:
+
+``DataWriter operating mode`` QoS Policy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, *Fast DDS* |DataWriters| are enabled using ``push mode``.
+This implies that they will add new samples into their queue, and then immediately deliver them to matched readers.
+For writers that produce non periodic bursts of data, this may imply saturating the network with a lot of packets,
+increasing the possibility of losing them on unreliable (i.e. UDP) transports.
+Depending on their QoS, DataReaders may also have to ignore some received samples, so they will have to be resent.
+
+Configuring the DataWriters on ``pull mode`` offers an alternative by letting each reader pace its own data stream.
+It works by the writer notifying the reader what it is available, and wait for it to request only as much as it can
+handle.
+At the cost of greater latency, this model can deliver reliability while using far fewer packets than ``push mode``.
+
+DataWriters periodically announce the state of their queue by means of a heartbeat.
+Upon reception of the heartbeat, DataReaders will request the DataWriter to send the samples they want to process.
+Consequently, the publishing rate can be tuned setting the heartbeat period accordingly.
+See :ref:`tuning-heartbeat-period` for more details.
+
+.. list-table::
+   :header-rows: 1
+   :align: left
+
+   * - PropertyPolicyQos name
+     - PropertyPolicyQos value
+     - Default value
+   * - ``"fastdds.push_mode"``
+     - ``"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: <!--><-->                                                                                            |
+|    :lines: 2-3,5-                                                                                                    |
+|    :append: </profiles>                                                                                              |
++----------------------------------------------------------------------------------------------------------------------+
+
+.. note::
+    * Communication to readers running on the same process (:ref:`intraprocess-delivery`) will always use ``push mode``.
+    * Communication to |BEST_EFFORT_RELIABILITY_QOS-api| readers will always use ``push mode``.
 
 .. 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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^