Gather-send implementation Docs (#724)

* Refs #20352: Update ChainingTransport API Signed-off-by: cferreiragonz <[email protected]> * Refs #20291: Use vector instead of list Signed-off-by: cferreiragonz <[email protected]> * Refs #20291: Include new Allocation QoS Signed-off-by: cferreiragonz <[email protected]> * Refs #20291: Mention payloads_to_send_ Signed-off-by: cferreiragonz <[email protected]> * Refs #20291: Revision - Use RLContainerConfig Signed-off-by: cferreiragonz <[email protected]> * Refs #20291: Improve format Signed-off-by: cferreiragonz <[email protected]> * Refs #20291: Revision - docs Signed-off-by: cferreiragonz <[email protected]> --------- Signed-off-by: cferreiragonz <[email protected]>
eProsima · Jun 13, 2024 · 71c7c6e · 71c7c6e
1 parent 6802780
commit 71c7c6e
Show file tree

Hide file tree

Showing 6 changed files with 53 additions and 23 deletions.
diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp
@@ -49,6 +49,7 @@
 #include <fastdds/rtps/transport/TCPv6TransportDescriptor.h>
 #include <fastdds/rtps/transport/UDPv4TransportDescriptor.h>
 #include <fastdds/rtps/transport/UDPv6TransportDescriptor.h>
+#include <fastdds/rtps/transport/NetworkBuffer.hpp>
 #include <fastdds/statistics/dds/domain/DomainParticipant.hpp>
 #include <fastdds/statistics/dds/publisher/qos/DataWriterQos.hpp>
 #include <fastdds/statistics/topic_names.hpp>
@@ -105,8 +106,8 @@ class CustomChainingTransport : public eprosima::fastdds::rtps::ChainingTranspor
 
  bool send(
  eprosima::fastrtps::rtps::SenderResource* low_sender_resource,
- const eprosima::fastrtps::rtps::octet* send_buffer,
- uint32_t send_buffer_size,
+ const std::vector<eprosima::fastdds::rtps::NetworkBuffer>& buffers,
+ uint32_t total_bytes,
  eprosima::fastrtps::rtps::LocatorsIterator* destination_locators_begin,
  eprosima::fastrtps::rtps::LocatorsIterator* destination_locators_end,
  const std::chrono::steady_clock::time_point& timeout) override
@@ -116,7 +117,7 @@ class CustomChainingTransport : public eprosima::fastdds::rtps::ChainingTranspor
  //
 
  // Call low level transport
- return low_sender_resource->send(send_buffer, send_buffer_size, destination_locators_begin,
+ return low_sender_resource->send(buffers, total_bytes, destination_locators_begin,
  destination_locators_end, timeout);
  }
 

diff --git a/code/XMLTester.xml b/code/XMLTester.xml
@@ -1555,6 +1555,11 @@
  <send_buffers>
  <preallocated_number>127</preallocated_number>
  <dynamic>true</dynamic>
+ <network_buffers_config>
+ <initial>16</initial>
+ <maximum>0</maximum>
+ <increment>16</increment>
+ </network_buffers_config>
  </send_buffers>
 
  <!-- content_filter cannot be configured using XML (yet) -->

diff --git a/code/XMLTesterExample.xml b/code/XMLTesterExample.xml
@@ -449,6 +449,11 @@
  <send_buffers>
  <preallocated_number>127</preallocated_number>
  <dynamic>true</dynamic>
+ <network_buffers_config>
+ <initial>16</initial>
+ <maximum>0</maximum>
+ <increment>16</increment>
+ </network_buffers_config>
  </send_buffers>
  </allocation>
 

diff --git a/docs/03-exports/aliases-api.include b/docs/03-exports/aliases-api.include
@@ -527,6 +527,7 @@
 .. |SendBuffersAllocationAttributes-api| replace:: :cpp:struct:`SendBuffersAllocationAttributes<eprosima::fastrtps::rtps::SendBuffersAllocationAttributes>`
 .. |SendBuffersAllocationAttributes::preallocated_number-api| replace:: :cpp:member:`preallocated_number<eprosima::fastrtps::rtps::SendBuffersAllocationAttributes::preallocated_number>`
 .. |SendBuffersAllocationAttributes::dynamic-api| replace:: :cpp:member:`dynamic<eprosima::fastrtps::rtps::SendBuffersAllocationAttributes::dynamic>`
+.. |SendBuffersAllocationAttributes::network_buffers_config-api| replace:: :cpp:member:`network_buffers_config<eprosima::fastrtps::rtps::SendBuffersAllocationAttributes::network_buffers_config>`
 
 .. |ReaderTimes-api| replace:: :cpp:class:`ReaderTimes<eprosima::fastrtps::rtps::ReaderTimes>`
 .. |ReaderTimes::initial_acknack_delay-api| replace:: :cpp:member:`initial_acknack_delay<eprosima::fastrtps::rtps::ReaderTimes::initial_acknack_delay>`

diff --git a/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst b/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst
@@ -384,13 +384,22 @@ See |SendBuffersAllocationAttributes-api|.
 
 List of structure members:
 
-+------------------------------------------------------------------------+-------------------------+-------------------+
-| Member Name | Type | Default Value |
-+========================================================================+=========================+===================+
-| |SendBuffersAllocationAttributes::preallocated_number-api| | ``size_t`` | 0 |
-+------------------------------------------------------------------------+-------------------------+-------------------+
-| |SendBuffersAllocationAttributes::dynamic-api| | ``bool`` | ``false`` |
-+------------------------------------------------------------------------+-------------------------+-------------------+
+.. list-table::
+ :header-rows: 1
+ :align: left
+
+ * - Member Name
+ - Type
+ - Default Value
+ * - |SendBuffersAllocationAttributes::preallocated_number-api|
+ - ``size_t``
+ - 0
+ * - |SendBuffersAllocationAttributes::dynamic-api|
+ - ``bool``
+ - ``false``
+ * - |SendBuffersAllocationAttributes::network_buffers_config-api|
+ - :ref:`resourcelimitedcontainerconfig`
+ - (16, inf, 16)
 
 * |SendBuffersAllocationAttributes::preallocated_number-api|:
  This member controls the initial number of send buffers to be allocated.
@@ -399,6 +408,15 @@ List of structure members:
 * |SendBuffersAllocationAttributes::dynamic-api|:
  This member controls how the buffer manager behaves when a send buffer is not available.
  When true, a new buffer will be created. Otherwise, it will wait for a buffer to be returned.
+* |SendBuffersAllocationAttributes::network_buffers_config-api|:
+ This attribute defines the allocation behavior and limits of the network buffers contained in each send buffer.
+ The default value will preallocate 16 network buffers and dynamically allocate 16 network buffers every time
+ that growing the vector is needed.
+
+.. note::
+ |SendBuffersAllocationAttributes::network_buffers_config-api| will also be used to instantiate a vector of
+ |SerializedPayload_t-api| that contains the metadata necessary to avoid payload copies during the creation of the
+ RTPS message.
 
 .. _variablelengthdatalimits:
 

diff --git a/docs/fastdds/xml_configuration/domainparticipant.rst b/docs/fastdds/xml_configuration/domainparticipant.rst
@@ -172,8 +172,7 @@ These elements allow the user to define the DomainParticipant configuration.
  -
  * - ``<allocation>``
  - Configuration regarding allocation behavior. |br|
- It expects a |br|
- |PartAlloc|.
+ It expects a |PartAlloc|.
  - |PartAlloc|
  -
  * - ``<userData>``
@@ -570,53 +569,44 @@ configuration.
  * - Name
  - Description
  - Values
- - Default
  * - ``<remote_locators>``
  - Defines the limits for the remote locators' collections. |br|
  See :ref:`remotelocatorsallocationattributes`.
  - :ref:`remote_locators_allocations`
- -
  * - ``<total_participants>``
  - DomainParticipant :ref:`CommonAlloc` to specify the |br|
  total number of DomainParticipants in the domain |br|
  (local and remote). See |br|
  :ref:`ResourceLimitedContainerConfig`.
  - :ref:`CommonAlloc`
- -
  * - ``<total_readers>``
  - DomainParticipant :ref:`CommonAlloc` to specify the |br|
  total number of DataReader on each DomainParticipant |br|
  (local and remote). See |br|
  :ref:`ResourceLimitedContainerConfig`.
  - :ref:`CommonAlloc`
- -
  * - ``<total_writers>``
  - DomainParticipant :ref:`CommonAlloc` related to the |br|
  total number of DataWriters on each DomainParticipant |br|
  (local and remote).
  See :ref:`resourcelimitedcontainerconfig`.
  - :ref:`CommonAlloc`
- -
  * - ``<max_partitions>``
  - Maximum size of the partitions submessage. |br|
  Set to zero for no limit.
  - ``uint32_t``
- -
  * - ``<max_user_data>``
  - Maximum size of the user data submessage. |br|
  Set to zero for no limit.
  - ``uint32_t``
- -
  * - ``<max_properties>``
  - Maximum size of the properties submessage. |br|
  Set to zero for no limit.
  - ``uint32_t``
- -
  * - ``<send_buffers>``
  - Allocation behaviour for the send buffer |br|
  manager.
  - :ref:`SendBuffers`
- -
 
 **Example**
 
@@ -672,12 +662,22 @@ Send buffers
  - ``uint32_t``
  - 0
  * - ``<dynamic>``
- - Whether the number of send buffers is allowed to grow. |br|
- See :ref:`sendbuffersallocationattributes`.
+ - Whether the number of send buffers is allowed to |br|
+ grow. See :ref:`sendbuffersallocationattributes`.
  - ``bool``
  - false
+ * - ``<network_buffers_config>``
+ - Network buffer :ref:`CommonAlloc` to specify the |br|
+ number of network buffers to be allocated for each |br|
+ send buffer. See :ref:`ResourceLimitedContainerConfig`.
+ - :ref:`CommonAlloc`
+ - (16, inf, 16)
 
 .. note::
  The default value ``0`` of ``<preallocated_number>`` will perform an initial guess of the number of buffers
  required, based on the number of threads from which a send operation could be started.
  So it does not mean there are no buffers, instead it would use the maximum amount of buffers available.
+ On the contrary, ``<network_buffers_config>`` will default to an initial number of 16 buffers, with an infinite
+ maximum and an increment of 16 buffers per send buffer.
+ An initial value of ``0`` will imply more dynamic allocations, especially at the beginning of the execution.
+ In case of doubt, it should be left to the default values.