Skip to navigation
API referenceC++ APIClasses

holoscan::LifecycleContext

Beta
View as Markdown

Provide cold, callback-lifetime lifecycle services.

This facade contains one hidden-state pointer. It exposes immutable phase-bound state and identity binding only; it cannot submit or await a restart, mutate graph topology, or invoke another lifecycle callback. References returned from it expire no later than the callback or lifecycle generation stated by the returned value’s own contract.

#include <holoscan/lifecycle.hpp>

Constructors

LifecycleContext

holoscan::LifecycleContext::LifecycleContext(
    detail::LifecycleContextState *state
) noexcept

Methods

cancellation

CancellationView holoscan::LifecycleContext::cancellation() const noexcept

Return the callback-lifetime cooperative cancellation view.

Returns: Borrowed monotonic stop/fatal-shutdown latch. Restart acceptance alone does not set it.

params

template <typename ParamsT>
const ParamsT & holoscan::LifecycleContext::params() const noexcept

Return the complete immutable parameter aggregate selected for this callback phase.

A wrong exact type terminates through the bounded Core contract handler.

Returns: Callback-lifetime reference. Repeated calls return the same address.

Template parameters

ParamsT
typename

Exact unqualified aggregate type declared by the callback’s Operator.

params_generation

ParamGeneration holoscan::LifecycleContext::params_generation() const noexcept

Return the phase-selected complete parameter generation.

Returns: Generation zero for startup/NoParams or the exact old, candidate, or current value.

transition_phase

LifecycleTransitionPhase holoscan::LifecycleContext::transition_phase() const noexcept

Return the transition phase that selected this callback’s state view.

Returns: One non-kNone phase inside a callback; kNone for an inert context.

report_error

void holoscan::LifecycleContext::report_error(
    ErrorCode code,
    std::string_view message
) noexcept

Supply bounded explanatory detail for a failed advanced lifecycle callback.

The first report wins. The callback’s returned LifecycleStatus remains authoritative; successful callbacks discard this detail. Reporting never allocates or throws.

Parameters

code
ErrorCode

Original error category.

message
std::string_view

Borrowed text copied before returning; do not include secrets.

resolve_clock

expected<ClockRef, Error> holoscan::LifecycleContext::resolve_clock(
    ClockKey key
) const noexcept

Resolve a declared clock for this lifecycle generation.

Resolution is cold-only and installs no compute-time lookup.

Returns: Generation-scoped reference or a typed binding/capability error.

Parameters

key
ClockKey

Owned cold clock identity; the omitted key requests the admitted default.

notification_sender

expected<NotificationSender, Error> holoscan::LifecycleContext::notification_sender(
    NotificationSource &source
) const noexcept

Return the current generation’s bounded notification capability.

Returns: Generation-bound sender or a typed ownership/stage/binding error.

Parameters

source
NotificationSource &

Declared notification source owned by the callback’s Operator.

restart_target

expected<OperatorRef, Error> holoscan::LifecycleContext::restart_target(
    OperatorRef plan_ref
) const noexcept

Bind an already-authorized plan target to the current run generation.

This operation resolves identity only; it neither submits nor waits for lifecycle work.

Returns: Fixed-size run-bound target or a stale/foreign/unauthorized error.

Parameters

plan_ref
OperatorRef

Plan-bound target whose run generation is zero.

bind_nominal_rate

template <PublishedPayload T>
expected<void, Error> holoscan::LifecycleContext::bind_nominal_rate(
    Output<T> &output,
    Rate value
) noexcept

Bind this output’s lifecycle-selected nominal rate for the current candidate.

Any declaration or value validation failure during a forward binding phase permanently rejects the private candidate. A later forward-phase call in that candidate returns the original failure; retrying with a fallback value cannot repair it. Return a lifecycle failure status instead.

Returns: Success, including an identical normalized repeat, or a typed ownership, stage, deadline, conflict, maximum, or capacity error.

Template parameters

T
PublishedPayload

Exact published payload type.

Parameters

output
Output<T> &

Output owned by the callback’s Operator and declared lifecycle-selectable.

value
Rate

Exact positive rational nominal average selected for this candidate.

rate

template <PublishedPayload T>
expected<PortRateView, Error> holoscan::LifecycleContext::rate(
    const Input<T> &input
) const noexcept

Return the phase-visible rate view for one owned input.

Call only during the active lifecycle callback and do not retain the context after callback return. The returned PortRateView is a value and may be retained. The query is O(1) and allocation-free.

Returns: Candidate rate view during startup/restart forward or forward rollback; otherwise the current published view, or a typed error without state change.

Template parameters

T
PublishedPayload

Exact published payload type.

Parameters

input
const Input<T> &

Exact Input member subobject registered by this callback’s Operator during setup(). A copied declaration, foreign Operator declaration, or output declaration does not carry query authority.

parameter_address

const void * holoscan::LifecycleContext::parameter_address(
    const void *exact_type
) const noexcept

bind_nominal_rate_port

expected<void, Error> holoscan::LifecycleContext::bind_nominal_rate_port(
    const void *output,
    Rate value
) noexcept

rate_port

expected<PortRateView, Error> holoscan::LifecycleContext::rate_port(
    const void *declaration,
    bool output
) const noexcept

record_callback_failure

void holoscan::LifecycleContext::record_callback_failure(
    Error error
) noexcept

Member variables

NameTypeDescription
state_detail::LifecycleContextState *