Skip to navigation
API referenceC++ APIClasses

holoscan::Output

Beta
View as Markdown
template <PublishedPayload T>
class Output

Declare one typed sample output as a stable Operator member.

Runtime late-binds publication authority for an activation. The declaration owns no queue, scheduler, or backend endpoint. Ordinary values and forwarded samples are passed by value; direct generic allocation uses a distinct move-only loan. Ordinary generated schemas also support explicit synchronous reference publication through emit_ref.

#include <holoscan/port.hpp>

Template parameters

T
PublishedPayload

Inherits from: holoscan::OutputBase (public)

Constructors

Output

holoscan::Output<T>::Output() = default

Construct an unnamed unbound output declaration.

Destructor

~Output

holoscan::Output<T>::~Output() override = default

Destroy this stable output declaration after all runtime bindings have retired.

Methods

emit

expected<void, Error> holoscan::Output<T>::emit(
    T value,
    EmitOptions options = {}
)

Publish one owning logical value with optional semantic metadata.

Returns: Success after accepted publication, or a typed error.

Parameters

value
T

Value moved into Runtime ownership on every outcome. A retryable publication error preserves logical publication authority but does not restore this by-value argument; retry with a newly supplied equivalent value.

options
EmitOptionsDefaults to {}

Optional capture time, frame identity, trace, and semantic flags.

emit_ref

expected<void, Error> holoscan::Output<T>::emit_ref(
    const T &value,
    EmitOptions options = {}
) noexcept

Encode and publish one ordinary generated schema without copying its native value.

Runtime encodes into owned bounded storage before returning. The caller may then edit, reset, or destroy its value, even while consumers have not yet received the encoded message. Framework-owned sequence, publication time, byte size, and classification are stamped by Runtime. Semantic metadata must be supplied explicitly through options.

The caller retains its value on every outcome. This does not make partial or indeterminate publication retryable; ordinary publication authority rules still apply.

This is not zero-copy transport, input mutation, or an escaping receive loan. It does not require prepared scratch for unchanged pass-through. A generated scratch value is useful for bounded edits; by-value emit still copies an lvalue. Encoder/transport costs remain.

Tensor descriptors are excluded: use emit_tensor or emit_tensors with separately authoritative output loans. Existing owning and generic-loan APIs are unchanged.

Returns: Success after accepted publication, or the same typed publication error as emit.

Parameters

value
const T &

Caller-owned value, unchanged and valid throughout this call, including objects reachable through its shared pointers. No reference to this value escapes the call.

options
EmitOptionsDefaults to {}

Optional capture time, frame identity, trace, and semantic flags.

allocate

expected<LoanedSample<T>, Error> holoscan::Output<T>::allocate() noexcept

Acquire one already-constructed value from a finite output pool.

This operation never blocks, grows a pool, or falls back to heap allocation.

This overload participates only for supported inline POD or generated-schema payloads that are default-initializable, assignable from T, and no-throw default-constructible and destructible. Other admitted payloads remain available through the ordinary emit(T) path.

Returns: Sole unpublished authority, or an immediate bounded allocation/state error.

allocate_tensor

expected<TensorOutputLoan, Error> holoscan::Output<T>::allocate_tensor(
    TensorLoanRequest request
)

Request one shaped allocation for a descriptor-backed Tensor schema output.

The overload participates only for descriptor-backed Tensor schema payloads. The returned Tensor remains separate from schema metadata until emit_tensor.

Returns: Sole provider-backed Tensor loan, or a typed bounds/capacity/state error.

Parameters

request
TensorLoanRequest

Logical shape, element type, and optional byte strides.

emit_tensor

expected<void, Error> holoscan::Output<T>::emit_tensor(
    TensorOutputLoan loan,
    const T &descriptor,
    EmitOptions options = {}
)

Publish provider-backed Tensor storage with descriptor-schema metadata.

The overload participates only for descriptor-backed Tensor schema payloads. Neither the descriptor object nor its strings may be mutated concurrently with this call.

Returns: Publication result.

Parameters

loan
TensorOutputLoan

Sole shaped Tensor authority; consumed for success and every error.

descriptor
const T &

Schema value whose non-Tensor fields are encoded synchronously. Its embedded Tensor member is ignored; the provider-owned Tensor from loan is authoritative.

options
EmitOptionsDefaults to {}

Optional semantic sample metadata.

allocate_tensors

expected<TensorSchemaOutputLoan<T>, Error> holoscan::Output<T>::allocate_tensors(
    std::span<const TensorFieldLoanRequest<T>> requests
)

Transactionally request provider-backed storage for every Tensor schema field.

The overload participates only for descriptor-backed Tensor schema payloads. Requests may be supplied in any order; Runtime canonicalizes them by generated Tensor index.

Returns: One sole multi-field publication bundle, or a typed validation, capacity, or state error. No partial bundle escapes on failure.

Parameters

requests
std::span<const TensorFieldLoanRequest<T>>

Exactly one generated field selector and shaped request per schema field.

emit_tensors

expected<void, Error> holoscan::Output<T>::emit_tensors(
    TensorSchemaOutputLoan<T> loan,
    const T &descriptor,
    EmitOptions options = {}
)

Publish one provider-backed Tensor field bundle with descriptor-schema metadata.

Returns: Publication result.

Parameters

loan
TensorSchemaOutputLoan<T>

Sole multi-field authority; consumed for success and every error.

descriptor
const T &

Schema value whose non-Tensor fields are encoded synchronously. Embedded Tensor members are ignored; the bundle fields are authoritative.

options
EmitOptionsDefaults to {}

Optional semantic sample metadata.

project

ProjectedTensorOutput<T> holoscan::Output<T>::project(
    TensorFieldSelector<T> selector
) const noexcept

Name one Tensor field of this schema output for a Tensor-typed edge.

The returned view borrows this declaration and must not outlive it. Naming the field is required rather than inferred whenever the schema carries more than one Tensor, so the choice appears in the Graph instead of following from declaration order.

Returns: Borrowing projection usable as an add_flow source.

Parameters

selector
TensorFieldSelector<T>

Generated field constant, such as schema::ImageTensorFields::data.

name

std::string_view holoscan::Output::name() const noexcept

Return the cold declaration name.

Returns: View valid until this port is destroyed.

tensor_output_binding

detail::TensorOutputBinding & holoscan::Output::tensor_output_binding() noexcept

Return the private shaped-allocation binding for a Tensor-backed output.

Returns: Mutable binding used only by exact typed output specializations.

Member variables

NameTypeDescription
binding_detail::OutputBinding< T >