Add documents for rosidl::Buffer features (backport #6440)#6643
Merged
Add documents for rosidl::Buffer features (backport #6440)#6643
Conversation
Signed-off-by: CY Chen <cyc@nvidia.com> (cherry picked from commit d71b29a)
|
HTML artifacts: https://github.com/ros2/ros2_documentation/actions/runs/25545221104/artifacts/6875009638. To view the resulting site:
|
ahcorde
approved these changes
May 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Introduces documentation for the new
rosidl::Bufferfeature and its pluggable backend architecture.Pages created in this pull request to cover the features are::
Concepts/Intermediate/About-Buffer-Backends.rst— conceptual overview:the
Buffer<T>/BufferImplBase<T>/BufferBackendsplit, thedescriptor round-trip, discovery hooks, and the "base backend vs
composed backend" pattern (CUDA as a base; PyTorch as a composed
backend that can layer on top of multiple bases). Also clarifies that
the plugin interface is RMW-agnostic —
get_descriptor_type_support()returns a generic aggregate handle, and the RMW (currently
rmw_fastrtps_cpp) resolves it internally.How-To-Guides/Using-Buffer-Backends.rst— user guide for enabling abackend on a subscription via
SubscriptionOptions::acceptable_buffer_backends(
""/"cpu"/"any"/ comma-separated list), C++ and Pythonexamples, a per-RMW support matrix, and the three practical rules for a
compatible pub/sub pair (same backend installed on both sides, same RMW,
aligned package versions). Also emphasises that intra-process /
inter-process / inter-host transport scope is a property of each
backend, not of
rosidl::Buffer.Tutorials/Advanced/Writing-a-Buffer-Backend.rst— vendor-facingstep-by-step guide for implementing and packaging a new
BufferBackendplugin: interface walkthrough, descriptor design (including the 4096-byte
kMaxBufferDescriptorSizelimit),BufferImplBase<T>andBufferBackendimplementation,pluginlibregistration, CMake/package.xmlscaffolding, user-facing API patterns (
allocate_msg,from_buffer,to_buffer), the composed-backend pattern, and a ship checklist. Uses ageneric
mydevbackend in prose and cross-links the real CUDA, Torch,and demo backends for concrete reference.
Tutorials/Demos/GPU-Buffer-Transport.rst— runnable end-to-end demobased on
robot_arm_demofromros2/rosidl_buffer_backends_tutorials,comparing CUDA zero-copy vs CPU-serialised transport at several
resolutions, with the benchmark table reproduced from the demo README.
Other registration / discoverability page updates:
Concepts/Intermediate.rst,How-To-Guides.rst,Tutorials/Advanced.rst,Tutorials/Demos.rst— new pages added to therespective
toctrees.Glossary.rst— new entries for "Buffer", "Buffer backend", "Basebackend", "Composed backend", "Buffer descriptor", and "Acceptable
backend list".
The-ROS2-Project/Features.rst— added a "Pluggable buffer backends"row (marked experimental, currently supported in
rmw_fastrtps_cppand, C++ user-facing APIs only).Related-Projects.rst— added a "Communityrosidl::Bufferbackends"section linking to
ros2/rosidl_buffer_backendsandros2/rosidl_buffer_backends_tutorials.Did you use Generative AI?
Yes. Cursor with Claude Opus 4.7 was used to assist with the draft version of the docs included in this pull request.
This is an automatic backport of pull request #6440 done by [Mergify](https://mergify.com).