Skip to content

Add documents for rosidl::Buffer features (backport #6440)#6643

Merged
ahcorde merged 1 commit intolyricalfrom
mergify/bp/lyrical/pr-6440
May 8, 2026
Merged

Add documents for rosidl::Buffer features (backport #6440)#6643
ahcorde merged 1 commit intolyricalfrom
mergify/bp/lyrical/pr-6440

Conversation

@mergify
Copy link
Copy Markdown
Contributor

@mergify mergify Bot commented May 8, 2026

Description

Introduces documentation for the new rosidl::Buffer feature 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> / BufferBackend split, the
    descriptor 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 a
    backend on a subscription via
    SubscriptionOptions::acceptable_buffer_backends
    (""/"cpu" / "any" / comma-separated list), C++ and Python
    examples, 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-facing
    step-by-step guide for implementing and packaging a new BufferBackend
    plugin: interface walkthrough, descriptor design (including the 4096-byte
    kMaxBufferDescriptorSize limit), BufferImplBase<T> and
    BufferBackend implementation, pluginlib registration, CMake/package.xml
    scaffolding, user-facing API patterns (allocate_msg, from_buffer,
    to_buffer), the composed-backend pattern, and a ship checklist. Uses a
    generic mydev backend 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 demo
    based on robot_arm_demo from ros2/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 the
    respective toctrees.
  • Glossary.rst — new entries for "Buffer", "Buffer backend", "Base
    backend", "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_cpp and, C++ user-facing APIs only).
  • Related-Projects.rst — added a "Community rosidl::Buffer backends"
    section linking to ros2/rosidl_buffer_backends and
    ros2/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).

Signed-off-by: CY Chen <cyc@nvidia.com>
(cherry picked from commit d71b29a)
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 8, 2026

HTML artifacts: https://github.com/ros2/ros2_documentation/actions/runs/25545221104/artifacts/6875009638.

To view the resulting site:

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

@ahcorde ahcorde merged commit 4e562fc into lyrical May 8, 2026
7 checks passed
@ahcorde ahcorde deleted the mergify/bp/lyrical/pr-6440 branch May 8, 2026 08:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants