supplement how to use Loaned Messages.

[fujitatomoya]

ROS 2 documentation does not really explains how to use LoanedMessages or demonstration but only how to disable it.
It would be better to add more general description about LoanedMessages including RMW implementation support status.

[fujitatomoya]

@christophebedard @MiguelCompany can you review this?
CC: @kscottz

Note

We can backport this as it is to jazzy and humble.

[github-actions]

HTML artifacts: https://github.com/ros2/ros2_documentation/actions/runs/13682385638/artifacts/2698157881.

To view the resulting site:

1. Click on the above link to download the artifacts archive
2. Extract it
3. Open html-artifacts-5068/index.html in your favorite browser

[fujitatomoya]

@MiguelCompany i addressed your comment, could you take a look again? thanks in advance.

[alsora]

We should at least point out this critical bug: ros2/rclcpp#2401
Until it's fixed, using loaned messages is not really possible outside of trivial examples or very specific and controlled use-cases

[fujitatomoya]

@alsora i think the problem is already linked in https://docs.ros.org/en/humble/How-To-Guides/Configure-ZeroCopy-loaned-messages.html#subscriptions to disable loaned message on subscription side. but i can also add ros2/rmw_cyclonedds#469 to the doc too.

[fujitatomoya]

We should at least point out this critical bug: ros2/rclcpp#2401 Until it's fixed, using loaned messages is not really possible outside of trivial examples or very specific and controlled use-cases

@alsora i just added ed3e8bf, what do you think?

[alsora]

Thanks, I didn't notice that it was already there at the end of the file.
However I still think that it should be very prominent.

My understanding is that as of today, loaned messages do not allow to achieve zero copy because as that ticket points out, they are disabled in subscriptions (and are unsafe to enable).

Advertising a broken feature can be dangerous.

Are there advantages in using this feature until that bug is resolved?

[fujitatomoya]

yeah, right there could be consequences on the subscription if user changes the setting from default, that is why in default it copies the message data from middleware. but how about publisher aspect? i thought that is still benefic for user application as a feature and it is safe as long as being with default setting?

what i am trying to add here is to add general explanation about LoanedMessage feature with sample. i am not trying to push unsafe behavior to enable LoanedMessage on the subscription, that is well-described the following section.