From 936a5a045de0fb635d8023f198c44baba3f4058e Mon Sep 17 00:00:00 2001 From: Tomoya Fujita Date: Wed, 4 Oct 2023 10:11:03 -0700 Subject: [PATCH] add doc section for Zero Copy Data Sharing. (#718) * add doc section for Zero Copy Data Sharing. Signed-off-by: Tomoya Fujita --- README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/README.md b/README.md index b8fa2f4c7..9b8dcc57c 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,7 @@ However, `rmw_fastrtps` offers the possibility to further configure Fast DDS: * [Change publication mode](#change-publication-mode) * [Full QoS configuration](#full-qos-configuration) * [Change participant discovery options](#change-participant-discovery-options) +* [Enable Zero Copy Data Sharing](#enable-zero-copy-data-sharing) ### Change publication mode @@ -234,6 +235,40 @@ ROS 2 allows controlling participant discovery with two environment variables: ` Full configuration of participant discovery can also be set with XML files; however, the ROS specific environment variables should be disabled to prevent them from interfering. Set `ROS_AUTOMATIC_DISCOVERY_RANGE` to the value `SYSTEM_DEFAULT` to disable both ROS specific environment variables. +### Enable Zero Copy Data Sharing + +ROS 2 provides [Loaned Messages](https://design.ros2.org/articles/zero_copy.html) that allows the user application to loan the message memory from the RMW implementation to eliminate the copy between the ROS 2 application and RMW implementation. +And Fast DDS `rmw_fastrtps_cpp` provides [Shared Memory Transport](https://fast-dds.docs.eprosima.com/en/latest/fastdds/transport/shared_memory/shared_memory.html) and [Data-sharing delivery](https://fast-dds.docs.eprosima.com/en/latest/fastdds/transport/datasharing.html) features to speed up the localhost communication. +Taking advantage of these features all together, it provides significant performance improvement to ROS 2 application. + +By default, `rmw_fastrtps_cpp` tries to use [Shared Memory Transport](https://fast-dds.docs.eprosima.com/en/latest/fastdds/transport/shared_memory/shared_memory.html) and [Data-sharing delivery](https://fast-dds.docs.eprosima.com/en/latest/fastdds/transport/datasharing.html) for localhost communication along with network communication if the message data type is a bounded type (a fixed sized data object). + +To enable [Loaned Messages](https://design.ros2.org/articles/zero_copy.html) with `rmw_fastrtps_cpp`, [Plain Old Data](https://en.wikipedia.org/wiki/Passive_data_structure) is the only requirement to `Iron Irwini` or later. +For `Humble Hawksbill`, the following XML file needs to be applied to set Fast-DDS `data_sharing` is explicitly enabled. (see more details for https://github.com/ros2/rmw_fastrtps/pull/568) + +```xml + + + + + + + + AUTOMATIC + + + + + + + + AUTOMATIC + + + + +``` + ## Quality Declaration files Quality Declarations for each package in this repository: