Skip to navigation
API referenceC++ APIClasses

holoscan::ChannelPublisher< Tensor >

Beta
View as Markdown

Publish Tensors through one catalog-attached, endpoint-owned allocation domain.

The attached import endpoint owns a finite preallocated publication pool and supplies the logical Tensor contract, capture-clock authority, and optional clock-health lane. The facade never exposes allocator injection, a bare-Tensor emit, publisher-created Sample<Tensor>, HoloMQ/BufferHandle state, or a process-local physical resource handle. The caller must serialize every publication call on one live facade, including emit*, close(), and report_clock_health(). Transport release callbacks are synchronized internally. Filling distinct acquired loans may overlap only within bounds later admitted by the attached endpoint.

#include <holoscan/tensor_endpoints.hpp>

Assignment operators

operator=

The following overloads are deleted to prevent misuse:

ChannelPublisher & holoscan::ChannelPublisher< Tensor >::operator=(ChannelPublisher &&other) = delete;
ChannelPublisher & holoscan::ChannelPublisher< Tensor >::operator=(const ChannelPublisher &other) = delete;

Methods

ChannelPublisher

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

Transfer endpoint publication authority from another facade.

Postconditions

other is closed and its checked operations return ErrorCode::kClosed.

Parameters

other
ChannelPublisher &&

Publisher whose authority becomes moved from.

Destructor

~ChannelPublisher< Tensor >

HOLOSCAN_CORE_EXPORT holoscan::ChannelPublisher<Tensor>::~ChannelPublisher() noexcept

Destroy the facade and release its source-private endpoint ownership.

loan_tensor

HOLOSCAN_CORE_EXPORT expected<TensorPublishLoan, Error> holoscan::ChannelPublisher<Tensor>::loan_tensor(
    TensorLoanRequest request
)

Acquire one endpoint-owned external Tensor publication loan without blocking.

Request shape and stride views are copied before this call returns. Pool exhaustion is reported immediately and never falls back to allocation or blocking.

Returns: Sole unpublished loan, ErrorCode::kResourceExhausted when a finite admitted resource is unavailable, or another checked endpoint/layout error.

Parameters

request
TensorLoanRequest

Logical shape, dtype, and optional byte strides copied during this call.

emit

HOLOSCAN_CORE_EXPORT expected<std::uint32_t, Error> holoscan::ChannelPublisher<Tensor>::emit(
    TensorPublishLoan loan,
    EmitOptions options = {}
)

Consume and publish one ready endpoint-owned Tensor loan.

A post-submit outcome that cannot prove zero delivery returns ErrorCode::kPublicationIndeterminate or ErrorCode::kPublicationPartial and must not be retried as the same sample.

Returns: Exact reached-recipient count, or a checked publication error.

Parameters

loan
TensorPublishLoan

Sole unpublished authority consumed on success or failure.

options
EmitOptionsDefaults to {}

Optional capture, frame, trace, and admitted flag metadata.

emit_captured

HOLOSCAN_CORE_EXPORT expected<std::uint32_t, Error> holoscan::ChannelPublisher<Tensor>::emit_captured(
    TensorPublishLoan loan,
    std::int64_t capture_timestamp_ns,
    EmitOptions options = {}
)

Consume and publish one loan with a coordinate in the bound capture clock.

Returns: Exact reached-recipient count, or a checked capture/publication error.

Parameters

loan
TensorPublishLoan

Sole unpublished authority consumed on success or failure.

capture_timestamp_ns
std::int64_t

Exact caller-supplied capture coordinate in nanoseconds.

options
EmitOptionsDefaults to {}

Remaining metadata; an existing capture time is invalid.

emit_sample

HOLOSCAN_CORE_EXPORT expected<std::uint32_t, Error> holoscan::ChannelPublisher<Tensor>::emit_sample(
    TensorPublishLoan loan,
    SampleMetadata metadata
)

Consume and publish one loan with explicit public sample metadata.

This overload deliberately does not accept Sample<Tensor> because a copyable Tensor cannot represent sole unpublished loan authority.

Returns: Exact reached-recipient count, or a checked metadata/publication error.

Parameters

loan
TensorPublishLoan

Sole unpublished authority consumed on success or failure.

metadata
SampleMetadata

Caller semantic metadata. Runtime replaces sequence, publication time/clock, byte size, and payload kind with locally authoritative values.

emit_copy

HOLOSCAN_CORE_EXPORT expected<std::uint32_t, Error> holoscan::ChannelPublisher<Tensor>::emit_copy(
    const Tensor &source,
    ::cuda::stream_ref producer_stream,
    EmitOptions options = {}
)

Copy an admitted foreign Tensor into endpoint-owned catalog storage and publish it.

This is the sole catalog-backed foreign-storage path. It never changes the source into exportable storage in place. A host destination performs one producer-stream-ordered device-to-host materialization and synchronizes before submission. A same-device CUDA destination enqueues one device-to-device copy and generation fence without blocking the host. Direct zero-copy export requires separately admitted physical resources.

Returns: Exact reached-recipient count, or a checked source/copy/publication error.

Parameters

source
const Tensor &

Contiguous CPU, CUDA device, or CUDA managed source. Device source backing is retained or release-ordered internally until the asynchronous copy completes.

producer_stream
::cuda::stream_ref

Borrowed producer stream. CPU sources require a null stream; CUDA device and managed sources require the non-null stream that orders producer completion.

options
EmitOptionsDefaults to {}

Optional capture, frame, trace, and admitted flag metadata.

make_capture_time

HOLOSCAN_CORE_EXPORT expected<TimePoint, Error> holoscan::ChannelPublisher<Tensor>::make_capture_time(
    std::int64_t timestamp_ns
) const noexcept

Label one coordinate with this catalog endpoint’s capture clock.

Returns: Bound time point, or a checked closed/authority error.

Parameters

timestamp_ns
std::int64_t

Exact caller-supplied nanosecond coordinate.

report_clock_health

HOLOSCAN_CORE_EXPORT expected<void, Error> holoscan::ChannelPublisher<Tensor>::report_clock_health(
    ClockHealthReport report
)

Publish one endpoint-bound clock-health report without borrowing a Tensor slot.

Returns: Empty success after local bounded acceptance, or a checked contract/publication error.

Parameters

report
ClockHealthReport

Valid payload-independent assessment and portable reason.

close

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

Publish an explicit ordered end-of-stream operation and consume this generation.

Destruction, disconnect, silence, and process exit do not publish or imply EOS.

With a lossy replacement policy, BufferHandle EOS uses a bounded protected terminal lane and a recipient drains its Tensor data lane before observing EOS. New data may replace stale data, but EOS cannot replace the final unread Tensor accepted by that recipient. QueuePolicy::kBlocking keeps data and EOS on its existing lossless FIFO lane.

Returns: Success after every frozen recipient accepts EOS.

update_connections

HOLOSCAN_CORE_EXPORT expected<void, Error> holoscan::ChannelPublisher<Tensor>::update_connections() noexcept

Refresh the backend connection snapshot used by has_subscribers.

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

has_subscribers

HOLOSCAN_CORE_EXPORT bool holoscan::ChannelPublisher<Tensor>::has_subscribers() noexcept

Return the most recently refreshed subscriber-presence snapshot.

This advisory value is not proof that a later emit reaches any recipient.

Returns: True when a subscriber was observed; false when moved from, closed, or disconnected.

Member variables

NameTypeDescription
state_void *
ops_const channel_internal::TensorPublisherOps *