add note for LoanedMessages's unsafety issue and setting. (#4002)

* add note for LoanedMessages's unsafety issue and setting.

* add redirection from previous file.

Signed-off-by: Tomoya.Fujita <Tomoya.Fujita@sony.com>

source/How-To-Guides.rst

@@ -45,7 +45,7 @@ If you are new and looking to learn the ropes, start with the :doc:`Tutorials <T
    How-To-Guides/Using-Variants
    How-To-Guides/Using-ros2-param
    How-To-Guides/Using-ros1_bridge-Jammy-upstream
-   How-To-Guides/Disabling-ZeroCopy-loaned-messages
+   How-To-Guides/Configure-ZeroCopy-loaned-messages
    How-To-Guides/Installing-on-Raspberry-Pi
    How-To-Guides/Using-callback-groups
    How-To-Guides/ROS-2-IDEs

source/How-To-Guides/Configure-ZeroCopy-loaned-messages.rst

@@ -0,0 +1,106 @@
+.. redirect-from::
+
+  How-To-Guides/Disabling-ZeroCopy-loaned-messages
+
+Configure Zero Copy Loaned Messages
+===================================
+
+.. contents:: Contents
+   :depth: 1
+   :local:
+
+See the `Loaned Messages <https://design.ros2.org/articles/zero_copy.html>`__ 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 <https://github.com/ros2/rmw_cyclonedds/issues/469>`_.
+Because of this, by default *Loaned Messages* is ``disabled`` on subscription with `Set disable loan to on by default <https://github.com/ros2/rcl/pull/1110>`_ 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

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