Add cuda_buffer_py

[nvcyc]

Description

This PR adds Python bindings for the CUDA buffer backend, enabling rclpy publishers and subscribers to exchange CUDA-backed ROS message fields without converting them to CPU memory.

The new cuda_buffer_py package exposes CUDA allocation and scoped read/write APIs that follow the existing C++ buffer lifecycle model.

Python API

The package adds:

• CudaBuffer.from_cpu(data) — copy CPU data into a CUDA-backed buffer.
• CudaBuffer.from_size(size) — create a zero-initialized CUDA-backed buffer.
• CudaBuffer.allocate_buffer(size) — allocate uninitialized CUDA storage without synchronization.
• CudaBuffer.from_output_buffer(buffer, stream) — acquire a CudaWriteHandle.
• CudaBuffer.from_input_buffer(buffer, stream) — acquire a CudaReadHandle.

CudaReadHandle and CudaWriteHandle are context managers that expose the CUDA device pointer through device_ptr and get_ptr().

Python type stubs and a py.typed marker are included.

Synchronization and lifecycle

The scoped Python handles preserve the synchronization and lifetime guarantees of the C++ implementation:

• Closing a write handle records producer completion on the supplied CUDA stream.
• Acquiring a read handle waits for the producer event on the consumer stream.
• Closing a read handle records consumer completion before the allocation can be recycled.
• Handles retain ownership of the underlying or promoted buffer for the required lifetime.
• CUDA-backed input remains on the GPU without CPU conversion.
• CUDA-to-CUDA synchronization uses stream-ordered CUDA events without synchronizing the producer or consumer stream.

CPU-backed inputs can still be promoted to CUDA automatically. The from_cpu() and from_size() convenience APIs synchronize initialization before returning, while allocate_buffer() and the scoped-
handle path support asynchronous device-only workflows.

The bindings use the process-wide CUDA allocation pool provided by the installed cuda_buffer shared library. This allows the Python extension and dynamically loaded serialization backend to resolve
the same CUDA allocations during descriptor creation.

rclpy usage

Publishers can allocate and populate message fields directly on the GPU:

msg.data = CudaBuffer.allocate_buffer(size)

with CudaBuffer.from_output_buffer(msg.data, stream_ptr) as handle:
    produce_device_data(handle.device_ptr, size, stream_ptr)

publisher.publish(msg)

Subscribers opt into the CUDA backend and consume the device pointer directly:

subscription = node.create_subscription(
    Image,
    'image',
    callback,
    10,
    acceptable_buffer_backends='cuda',
)

def callback(msg):
    with CudaBuffer.from_input_buffer(msg.data, stream_ptr) as handle:
        consume_device_data(handle.device_ptr, len(msg.data), stream_ptr)

Testing

The package includes unit tests for allocation, conversion, scoped handles, synchronization, error handling, and lifetime management.

It also includes a Fast RTPS multiprocess regression test that:

• Runs the Python publisher and subscriber in separate OS processes.
• Uses regular DDS inter-process transport.
• Publishes five CUDA-backed messages with known payloads.
• Checks that each received field reports the cuda backend before creating a read handle.
• Copies the final data to host and validates every payload.
• Fails if the backend falls back to CPU, payload validation fails, or fewer than five explicit validations are observed.