Channels and HoloMQ

A process boundary is useful when a camera service, inference service, user interface, or hardware-facing component needs its own lifecycle or deployment location. Holoscan provides graph ports and external topics for graph composition, while channels and HoloMQ provide the transport path between processes.

Choose the boundary API from the responsibility you need. A graph operator should use typed ports and contracts. A separate program that attaches to an accepted endpoint should use the catalog-backed client path. An application that owns transport setup, pools, and buffer exchange directly should use the public HoloMQ surface.

If your application already has separate camera, inference, or display services, they need a clear way to exchange data and manage shared buffers. RidgeRun can help connect those services to a Holoscan pipeline and handle startup, shutdown, and reconnecting. Contact RidgeRun for process integration support.

The Ports, Samples, and Payload Types page defines the values exchanged by operators. The Building Graphs and Queue Policies page explains graph connections before data crosses a process boundary.

Choose the boundary first

Need	Start with
Connect operators inside one graph	Typed ports, samples, triggers, and graph contracts.
Connect a graph to a declared process endpoint	External Endpoints and Endpoint Catalogs and a matching catalog.
Write a separate publisher or subscriber	Standalone ChannelRuntime Clients and the endpoint's accepted catalog.
Own transport services and buffer exchange directly	The public HoloMQ API, with its own service, pool, buffer, and shutdown responsibilities.

The Tensor Contracts and Memory Types and External Memory: VPI, PVA, NvSci, and DLPack pages define the payload facts that still apply at a process boundary.

Choose the payload path

The transport can carry different kinds of application data:

Payload path	What crosses the boundary
Inline scalar, POD, or schema value	The message carries a bounded value and its metadata.
Descriptor-backed Tensor	The message carries metadata that identifies Tensor fields; the backing storage is exported, imported, or copied through the endpoint contract.
Explicit endpoint copy	The receiving side gets destination-owned storage and the application follows its completion and release rules.
Direct HoloMQ buffer exchange	A transport buffer or buffer handle carries a storage claim that the producer and consumer must release according to the HoloMQ API.

Metadata movement, storage export or import, readiness, and copy completion are separate events. A small descriptor does not make a large image inline, and copying a handle does not transfer ownership of the bytes. Follow Descriptor-Tensor External Topics for multiple Tensor fields and Copy Paths and Memory Conversion for explicit materialization.

Use a standalone client when the graph is outside the process

A standalone client is a separate program that attaches to an endpoint exposed by a graph or another client. ChannelRuntime is the Holoscan facade for that path. It does not replace operator ports and it does not turn a transport name into an accepted graph contract.

Use the client in this order:

Load the catalog that describes the endpoint and its payload contract.
Attach the endpoint factory with the names and direction declared by that catalog.
Publish or receive values using the checked result returned by the operation.
Keep the payload owner alive through the last read, copy, or export.
Close streams and endpoint handles after publication or receive work has ended.

The Standalone ChannelRuntime Clients page provides a complete one-sample client flow. The Descriptor-Tensor External Topic Example shows a graph and client exchanging structured Tensor data.

Direct HoloMQ programs have more responsibilities. The HoloMQ public API guide covers service creation, buffer pools, imported buffers, and transport messages. Use this path when the application owns those resources and can define their startup and shutdown order.

Continue the flow

External Endpoints and Endpoint Catalogs shows how to declare a graph boundary and save its accepted catalog.
Standalone ChannelRuntime Clients shows the checked client setup.
Dynamic External Peers explains peer absence, end-of-stream, and replacement.

Bound capacity before runtime pressure

Every process-boundary design needs a finite capacity decision:

Resource	Capacity question
Endpoint metadata	How many fields, dimensions, and descriptor bytes can one message contain?
Tensor backing	What is the largest byte span for each field, including strides, planes, and padding?
In-flight messages	How many published values can wait while consumers process or retain them?
Exported or imported storage	How many buffer claims can remain live before the provider or pool is exhausted?
Inline payload	Which values fit the endpoint's inline limit, and which values need a storage path?

Queue depth, publisher loans, subscriber borrows, fan-out, and retained samples consume different capacity. Check the accepted endpoint contract before describing a path as copy-free. A copy-capable policy may need a bounded staging pool, as described in External Endpoints and Endpoint Catalogs.

Separate connection, delivery, and end-of-stream

These observations answer different questions:

Observation	What it tells you
Endpoint presence or refresh	A peer or endpoint is currently discoverable. It does not prove that a message was delivered.
Publication result	The operation accepted, rejected, or reached a reported set of recipients. Check the result before counting delivery.
Receive result	A value, timeout, cancellation, or error occurred. A timeout does not by itself mean end-of-stream.
Ordered end-of-stream	The producer has closed the generation in a way the endpoint contract exposes as EOS. A local subscriber close only retires that subscriber.

Do not retry a publication with a consumed buffer or treat a partial or indeterminate result as a clean delivery. When a generation has ended, reconnecting to the same name does not automatically revive that generation. Dynamic External Peers explains peer replacement and generation changes.

Deploy the processes that the contract requires

A catalog describes endpoints and accepted payloads. It does not launch graph workers or standalone clients. The deployment must provide the shared-memory discovery service, buffer-import service, permissions, and socket namespace required by the actual processes.

The graph runner also does not select or launch workers for every possible process group. run_async(plan) reports an explicit process-group selection error when a plan needs a choice that the application has not supplied. Standalone clients and example child processes still need their own launch configuration.

Process boundary checklist

Use one catalog and endpoint identity for every participant.
Start the discovery and transport services before attaching clients.
Verify permissions and socket namespaces in the target deployment.
Give each process an explicit close and error path.
Record whether each Tensor field is exported, imported, or copied.

Related examples and concepts

Examples

HoloMQ Example follows direct transport publishers and subscribers.
Descriptor-Tensor External Topic Example demonstrates a graph and catalog client exchanging Tensor fields.

Concepts

External Endpoints and Endpoint Catalogs defines endpoint identity, direction, and capacity.
Descriptor-Tensor External Topics explains structured Tensor fields.
External Memory: VPI, PVA, NvSci, and DLPack separates ownership, readiness, and exportability.
Standalone ChannelRuntime Clients covers checked client setup and cleanup.

Further reading

HoloMQ public API guide describes direct transport setup and buffer ownership.
NVIDIA Holoscan SDK official documentation provides the broader channel and core API reference.

Source

❯