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 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 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 ^^^^^^