From 67c68c9d53b725895d4a5c8c627f65a3eb2d3a04 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Mon, 27 Nov 2023 12:05:11 -0500 Subject: [PATCH] add note for LoanedMessages's unsafety issue and setting. (#4002) (#4035) * add note for LoanedMessages's unsafety issue and setting. * add redirection from previous file. Signed-off-by: Tomoya.Fujita (cherry picked from commit 97bd9fe70ceee22fa5cd02f8668f537c5a8e4b98) Co-authored-by: Tomoya Fujita --- source/How-To-Guides.rst | 2 +- .../Configure-ZeroCopy-loaned-messages.rst | 106 ++++++++++++++++++ .../Disabling-ZeroCopy-loaned-messages.rst | 55 --------- source/Releases/Release-Humble-Hawksbill.rst | 2 +- 4 files changed, 108 insertions(+), 57 deletions(-) create mode 100644 source/How-To-Guides/Configure-ZeroCopy-loaned-messages.rst delete mode 100644 source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst diff --git a/source/How-To-Guides.rst b/source/How-To-Guides.rst index d6fc3b2e6c5..347ba1e4d05 100644 --- a/source/How-To-Guides.rst +++ b/source/How-To-Guides.rst @@ -45,7 +45,7 @@ If you are new and looking to learn the ropes, start with the :doc:`Tutorials `__ article for details on how loaned messages work. + +How to disable Loaned Messages +------------------------------ + +Publishers +~~~~~~~~~~ + +By default, *Loaned Messages* will try to borrow the memory from underlying middleware if it supports *Loaned Messages*. +The ``ROS_DISABLE_LOANED_MESSAGES`` environment variable can be used to disable *Loaned Messages*, and fallback to normal publisher behavior, without any code changes or middleware configuration. +You can set the environment variable with the following command: + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: console + + export ROS_DISABLE_LOANED_MESSAGES=1 + + To maintain this setting between shell sessions, you can add the command to your shell startup script: + + .. code-block:: console + + echo "export ROS_DISABLE_LOANED_MESSAGES=1" >> ~/.bashrc + + .. group-tab:: macOS + + .. code-block:: console + + export ROS_DISABLE_LOANED_MESSAGES=1 + + To maintain this setting between shell sessions, you can add the command to your shell startup script: + + .. code-block:: console + + echo "export ROS_DISABLE_LOANED_MESSAGES=1" >> ~/.bash_profile + + .. group-tab:: Windows + + .. code-block:: console + + set ROS_DISABLE_LOANED_MESSAGES=1 + + If you want to make this permanent between shell sessions, also run: + + .. code-block:: console + + setx ROS_DISABLE_LOANED_MESSAGES 1 + + +Subscriptions +~~~~~~~~~~~~~ + +Currently using *Loaned Messages* is not safe on subscription, see more details in `this issue `_. +Because of this, by default *Loaned Messages* is ``disabled`` on subscription with `Set disable loan to on by default `_ even though underlying middleware supports that. +To enable *Loaned Messages* on subscription, you need to set the environment variable ``ROS_DISABLE_LOANED_MESSAGES`` to ``0`` explicitly. + +.. tabs:: + + .. group-tab:: Linux + + .. code-block:: console + + export ROS_DISABLE_LOANED_MESSAGES=0 + + To maintain this setting between shell sessions, you can add the command to your shell startup script: + + .. code-block:: console + + echo "export ROS_DISABLE_LOANED_MESSAGES=0" >> ~/.bashrc + + .. group-tab:: macOS + + .. code-block:: console + + export ROS_DISABLE_LOANED_MESSAGES=0 + + To maintain this setting between shell sessions, you can add the command to your shell startup script: + + .. code-block:: console + + echo "export ROS_DISABLE_LOANED_MESSAGES=0" >> ~/.bash_profile + + .. group-tab:: Windows + + .. code-block:: console + + set ROS_DISABLE_LOANED_MESSAGES=0 + + If you want to make this permanent between shell sessions, also run: + + .. code-block:: console + + setx ROS_DISABLE_LOANED_MESSAGES 0 diff --git a/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst b/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst deleted file mode 100644 index f76bea70b79..00000000000 --- a/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. _ZeroCopyLoanedMessages: - -Disabling Zero Copy Loaned Messages -=================================== - -.. contents:: Contents - :depth: 1 - :local: - -See the `Loaned Messages `__ article for details on how loaned messages work. - -How to disable Loaned Messages ------------------------------- - -By default, *Loaned Messages* will try to borrow the memory from underlying middleware if it supports *Loaned Messages*. -The ``ROS_DISABLE_LOANED_MESSAGES`` environment variable can be used to disable *Loaned Messages*, and fallback to normal publisher and subscription behavior, without any code changes or middleware configuration. -You can set the environment variable with the following command: - -.. tabs:: - - .. group-tab:: Linux - - .. code-block:: console - - export ROS_DISABLE_LOANED_MESSAGES=1 - - To maintain this setting between shell sessions, you can add the command to your shell startup script: - - .. code-block:: console - - echo "export ROS_DISABLE_LOANED_MESSAGES=1" >> ~/.bashrc - - .. group-tab:: macOS - - .. code-block:: console - - export ROS_DISABLE_LOANED_MESSAGES=1 - - To maintain this setting between shell sessions, you can add the command to your shell startup script: - - .. code-block:: console - - echo "export ROS_DISABLE_LOANED_MESSAGES=1" >> ~/.bash_profile - - .. group-tab:: Windows - - .. code-block:: console - - set ROS_DISABLE_LOANED_MESSAGES=1 - - If you want to make this permanent between shell sessions, also run: - - .. code-block:: console - - setx ROS_DISABLE_LOANED_MESSAGES 1 diff --git a/source/Releases/Release-Humble-Hawksbill.rst b/source/Releases/Release-Humble-Hawksbill.rst index 5dd1a3a08e9..3a5ebd13f37 100644 --- a/source/Releases/Release-Humble-Hawksbill.rst +++ b/source/Releases/Release-Humble-Hawksbill.rst @@ -565,7 +565,7 @@ ROS_DISABLE_LOANED_MESSAGES environment variable added """""""""""""""""""""""""""""""""""""""""""""""""""""" This environment variable can be used to disable loaned messages support, independently if the rmw supports them or not. -For more details, see the guide :doc:`Disabling Zero Copy Loaned Messages <../How-To-Guides/Disabling-ZeroCopy-loaned-messages>`. +For more details, see the guide :doc:`Configure Zero Copy Loaned Messages <../How-To-Guides/Configure-ZeroCopy-loaned-messages>`. rclcpp ^^^^^^