From 3d9499d7120c9ab2cdc952b7c778aea287572edf Mon Sep 17 00:00:00 2001 From: "Tomoya.Fujita" Date: Thu, 2 Nov 2023 16:59:24 -0700 Subject: [PATCH 1/4] add note for LoanedMessages's unsafety issue and setting. Signed-off-by: Tomoya.Fujita --- source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst b/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst index f76bea70b79..74dbc3936a8 100644 --- a/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst +++ b/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst @@ -53,3 +53,9 @@ You can set the environment variable with the following command: .. code-block:: console setx ROS_DISABLE_LOANED_MESSAGES 1 + +.. note:: + + Currently using *Loaned Messages* is not safe on subscription, see more details for `this issue `_. + Because of this, by default *Loaned Messages* is ``disabled`` on subscription with `Set disable loan to on by default `_. + To enable *Loaned Messages* on subscription, you need to set the environment variable ``ROS_DISABLE_LOANED_MESSAGES`` to ``0`` explicitly. From 2fd90dba9be8e27a17b4ddc96621315707aa6fe1 Mon Sep 17 00:00:00 2001 From: "Tomoya.Fujita" Date: Fri, 17 Nov 2023 11:41:02 -0600 Subject: [PATCH 2/4] address review comment. Signed-off-by: Tomoya.Fujita --- source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst b/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst index 74dbc3936a8..e6d5d3203dc 100644 --- a/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst +++ b/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst @@ -56,6 +56,6 @@ You can set the environment variable with the following command: .. note:: - Currently using *Loaned Messages* is not safe on subscription, see more details for `this issue `_. + 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 `_. To enable *Loaned Messages* on subscription, you need to set the environment variable ``ROS_DISABLE_LOANED_MESSAGES`` to ``0`` explicitly. From 2b5e880cd4e4165a24e15159e6ea21da1279958a Mon Sep 17 00:00:00 2001 From: "Tomoya.Fujita" Date: Fri, 17 Nov 2023 11:56:45 -0600 Subject: [PATCH 3/4] rewrite doc how to configure loaned messages. Signed-off-by: Tomoya.Fujita --- source/How-To-Guides.rst | 2 +- .../Configure-ZeroCopy-loaned-messages.rst | 104 ++++++++++++++++++ .../Disabling-ZeroCopy-loaned-messages.rst | 61 ---------- source/Releases/Release-Humble-Hawksbill.rst | 2 +- 4 files changed, 106 insertions(+), 63 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 a6e737cc4e6..dc2cc42b076 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 e6d5d3203dc..00000000000 --- a/source/How-To-Guides/Disabling-ZeroCopy-loaned-messages.rst +++ /dev/null @@ -1,61 +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 - -.. note:: - - 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 `_. - To enable *Loaned Messages* on subscription, you need to set the environment variable ``ROS_DISABLE_LOANED_MESSAGES`` to ``0`` explicitly. diff --git a/source/Releases/Release-Humble-Hawksbill.rst b/source/Releases/Release-Humble-Hawksbill.rst index 019f53c153f..667ab11e024 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 ^^^^^^ From e9e3cb123e83e26f22c2a35c03cccbd9a6adac28 Mon Sep 17 00:00:00 2001 From: "Tomoya.Fujita" Date: Sat, 25 Nov 2023 22:15:07 -0800 Subject: [PATCH 4/4] add redirection from previous file. Signed-off-by: Tomoya.Fujita --- source/How-To-Guides/Configure-ZeroCopy-loaned-messages.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/How-To-Guides/Configure-ZeroCopy-loaned-messages.rst b/source/How-To-Guides/Configure-ZeroCopy-loaned-messages.rst index 9f1c988225e..6c14ce703a8 100644 --- a/source/How-To-Guides/Configure-ZeroCopy-loaned-messages.rst +++ b/source/How-To-Guides/Configure-ZeroCopy-loaned-messages.rst @@ -1,4 +1,6 @@ -.. _ZeroCopyLoanedMessages: +.. redirect-from:: + + How-To-Guides/Disabling-ZeroCopy-loaned-messages Configure Zero Copy Loaned Messages ===================================