holoscan::ChannelSubscriber< Tensor > | Holoscan SDK Documentation

Consume read-only Tensors from one manual or catalog-attached Channel endpoint.

Catalog attachment imports the endpoint’s opaque BufferHandle transport into a bounded Holoscan-owned read-only Tensor lifetime. The facade exposes no HoloMQ handle, pool slot, or endpoint-generation control. Each successful receive consumes one queued sample; copied Tensor wrappers retain the same read-only storage claim until the last wrapper or derived view retires.

#include <holoscan/tensor_endpoints.hpp>

Assignment operators

operator=

Move assign

Copy assign (deleted)

HOLOSCAN_CORE_EXPORT ChannelSubscriber & holoscan::ChannelSubscriber<Tensor>::operator=(
    ChannelSubscriber &&other
) noexcept

Methods

ChannelSubscriber

Overload 1

Overload 3

Deleted overload

HOLOSCAN_CORE_EXPORT holoscan::ChannelSubscriber<Tensor>::ChannelSubscriber(
    ChannelSubscriber &&other
) noexcept

Destructor

~ChannelSubscriber< Tensor >

HOLOSCAN_CORE_EXPORT holoscan::ChannelSubscriber<Tensor>::~ChannelSubscriber()

close

HOLOSCAN_CORE_EXPORT expected<void, Error> holoscan::ChannelSubscriber<Tensor>::close() noexcept

Retire this process’s local Tensor subscriber endpoint.

This externally serialized, consuming operation publishes no producer end-of-stream record and supplies no graph-completion evidence. Cancel and join any active waiter before closing. Already returned Tensors and derived views retain their ordinary owning lifetime; unread local data may be discarded. A cleanup failure still consumes the endpoint; later checked operations return ErrorCode::kClosed.

Returns: Success on the first live close, or a code-only cleanup error. Repeated close and close on a moved-from facade return ErrorCode::kClosed.

has_samples

HOLOSCAN_CORE_EXPORT expected<bool, Error> holoscan::ChannelSubscriber<Tensor>::has_samples() const

Return whether the transport reports a pending Tensor descriptor without consuming it.

Returns: The readiness state, or an error when the backend cannot query it.

readiness

HOLOSCAN_CORE_EXPORT expected<ChannelReadinessHandle, Error> holoscan::ChannelSubscriber<Tensor>::readiness()

Claim an externally pollable readiness descriptor for this subscriber.

Readability is a hint. A consumer calls ChannelReadinessHandle::acknowledge first, then drains receive or receive_sample until ErrorCode::kNotReady. Producer end of stream and a changed producer incarnation also wake the descriptor so the next receive reports ErrorCode::kClosed or ErrorCode::kStaleEndpoint.

Blocking wait operations return ErrorCode::kInvalidArgument while the handle is live.

Returns: A move-only handle, or a checked closed, capability, or ownership error.

receive

HOLOSCAN_CORE_EXPORT expected<Tensor, Error> holoscan::ChannelSubscriber<Tensor>::receive()

Receive the next Tensor handle.

Returns: The next Tensor, or ErrorCode::kNotReady when no descriptor is queued.

receive_sample

HOLOSCAN_CORE_EXPORT expected<Sample<Tensor>, Error> holoscan::ChannelSubscriber<Tensor>::receive_sample()

Receive the next Tensor handle together with public sample metadata.

Sidecar token, generation, process id, and other transport internals are intentionally not exposed through this API.

wait_and_receive_sample

Block until a Tensor sample is available

Overload 2

HOLOSCAN_CORE_EXPORT expected<Sample<Tensor>, Error> holoscan::ChannelSubscriber<Tensor>::wait_and_receive_sample(
    std::chrono::steady_clock::time_point deadline
)

Block until a Tensor sample is available, then receive and consume it.

A receive is attempted before any wait is built, so an already queued sample costs no wait context and no kernel wait. ErrorCode::kNotReady never escapes: readiness is a hint, so an attempt that loses its race against a dropped-oldest replacement waits again against the same absolute deadline. Queued data always drains before end of stream is observed, so a producer that emits N Tensors and then closes yields N samples and then ErrorCode::kClosed.

ErrorCode::kProtocolError, ErrorCode::kCodecError, ErrorCode::kReceiveError, and ErrorCode::kResourceExhausted pass through unchanged.

There is no duration overload by design. An absolute deadline cannot silently restart its budget on a spurious wake.

Readiness is a hint, so a subscriber that keeps reporting it while every receive loses its race retries at full speed until deadline. The absolute deadline is the only bound on that loop; there is no backoff. It is not reachable by an idle endpoint – something has to be producing readiness that no receive can consume, such as a competing consumer on the same endpoint – but a caller that shares a subscriber should size the deadline accordingly.

One subscriber supports one waiting thread and calls are not internally serialized. A second concurrent waiter is rejected with ErrorCode::kInvalidArgument rather than sharing the first one’s wait context. The facade must outlive an in-flight wait and must not be moved while one is in flight.

Returns: The sample on success, or the first checked error.

Parameters

deadline

std::chrono::steady_clock::time_point

Steady-clock coordinate after which the wait reports a timeout.

wait_for_sample

HOLOSCAN_CORE_EXPORT expected<void, Error> holoscan::ChannelSubscriber<Tensor>::wait_for_sample(
    std::chrono::steady_clock::time_point deadline,
    const std::stop_token &token = {}
)

Block until this endpoint may have a sample, without consuming one.

Success is a hint, exactly like has_samples. A following receive_sample may still report ErrorCode::kNotReady.

Returns: Empty success when a sample may be available, or a checked wait error.

Parameters

deadline

std::chrono::steady_clock::time_point

Steady-clock coordinate after which the wait reports a timeout.

token

const std::stop_token &Defaults to {}

Cancellation observer for this call; a default-constructed token never cancels.

refresh_connections

HOLOSCAN_CORE_EXPORT expected<void, Error> holoscan::ChannelSubscriber<Tensor>::refresh_connections()

Refresh the backend connection snapshot used by has_publishers().

This cold-path operation does not consume a sample or report receive readiness.

Returns: Empty success, or a checked closed/backend refresh error.

has_publishers

HOLOSCAN_CORE_EXPORT bool holoscan::ChannelSubscriber<Tensor>::has_publishers() const noexcept

Return whether this endpoint currently observes a publisher.

This cold-path advisory snapshot is neither receive readiness nor proof that a later sample arrives. Required-peer catalog attachment applies its finite wait before returning.

Returns: True when a publisher is connected; false when moved from, closed, or disconnected.

wait_set_subscriber

HOLOSCAN_CORE_EXPORT channel_internal::WaitSetSubscriber * holoscan::ChannelSubscriber<Tensor>::wait_set_subscriber() noexcept

receive_sample_if_data_accepted

HOLOSCAN_CORE_EXPORT expected<Sample<Tensor>, Error> holoscan::ChannelSubscriber<Tensor>::receive_sample_if_data_accepted(
    bool accept_data
)

accepted_end_of_stream_sequence

HOLOSCAN_CORE_EXPORT std::uint64_t holoscan::ChannelSubscriber<Tensor>::accepted_end_of_stream_sequence() const noexcept

Member variables

Name	Type	Description
`impl_`	`std::unique_ptr< Impl >`