HoloMQ Example

Exchange buffers between a publisher and subscriber through HoloMQ's iceoryx2 backend. The publisher loans a buffer, fills it, sends a handle in an application payload, and the subscriber imports the handle and checks the sample sequence.

Begin with Channels and HoloMQ for the transport vocabulary. The example runner launches both roles in one environment and handles the basic timeouts and cleanup.

Prerequisites

Use the examples-enabled SDK installation from Build the SDK on AGX Orin. A working CUDA driver, the iceoryx2 backend, and shared memory through /dev/shm are required.

What you will learn

How the publisher and subscriber coordinate through one message type.
How an exported BufferHandle crosses the process boundary.
Why both roles need compatible storage and shared discovery paths.
How the supplied runner reports failures from either process.

Build and run

Build the example through the shared SDK build page. The example has no install rule, so run the executable from the SDK build tree:

WORKSPACE="$HOME/holoscan-5.0"
cd "$WORKSPACE/holoscan-sdk"
BUILD_DIR="$(./run get_build_dir)"
./run launch "$BUILD_DIR" --run-cmd "cmake --build . --target holomq_main"
RUN_BIN="/workspace/holoscan-sdk/$BUILD_DIR/examples/holomq/holomq_main/holomq_main"
RUNNER="/workspace/holoscan-sdk/examples/holomq/holomq_main/test_holomq_main.sh"
./run launch "$BUILD_DIR" --run-cmd "bash $RUNNER $RUN_BIN"

Follow the workflow

Operators used

Component	Role in this example
`DemoPublisher`	Loans and fills a buffer, then sends its handle with the frame payload.
`DemoSubscriber`	Receives the payload, imports the buffer, and checks the sample sequence.
`FramePayload`	Carries the sequence, dimensions, and exported buffer handle.

The publisher and subscriber exchange a FramePayload with a sequence number, dimensions, and a BufferHandle. The publisher waits for the subscriber, loans a slot from its pool, fills the buffer, and sends the handle. The subscriber receives the payload and imports the buffer using its CUDA stream.

The runner keeps both roles in one container so they see the same Unix socket and shared-memory environment. The default demonstration uses three samples. A changed sample count must be applied consistently to both roles.

Expected result

The runner returns zero when the publisher and subscriber complete their checks. On failure, it prints the separate process logs. A successful run checks sequence order and buffer import. It does not read the buffer back to validate image contents or provide a zero-copy performance result.

Related examples and concepts

Examples

Descriptor-Tensor External Topic Example carries a schema with multiple Tensor fields.
Interprocess External-Endpoint Demo shows catalog-backed external endpoints in a RidgeRun application.

Concepts

Channels and HoloMQ explains transport boundaries and delivery.
Zero-Copy Data Flow and CUDA Stream Ordering explains readiness and lifetime across CUDA boundaries.
Allocation Ownership and Tensor Pools explains pool capacity and retained backing.

Source The publisher, subscriber, payload, and runner are in the HoloMQ example. The implementation defines the roles and options, while the payload definition describes the exchanged fields.

Official documentation

NVIDIA Holoscan SDK official documentation provides the current interprocess and payload reference.

❯