Skip to navigation
API referenceC++ APIClasses

holoscan::LifecycleControlHandle

Beta
View as Markdown

Submit and observe bounded lifecycle restart transactions.

A handle is a restriction-only run capability. It retains a bounded tombstone/control block, not the RunSession, ExecutionPlan, or any Operator object. Copying a handle preserves exactly the same restriction authority, allocates no memory, and does not broaden target or stage access. After session retirement, submissions fail closed while already accepted receipts remain inspectable until the final handle copy is destroyed.

Independent handle objects may be used concurrently. Concurrent mutation of the same handle object by copy or move assignment requires caller synchronization. The handle is a process-local opaque capability: its bytes and internal address are not stable identities and must never be serialized, transported, or persisted. Serialize an explicitly supported receipt or diagnostic record instead.

#include <holoscan/lifecycle_control.hpp>

Constructors

LifecycleControlHandle

holoscan::LifecycleControlHandle::LifecycleControlHandle() noexcept = default

Create an empty handle that grants no lifecycle-control authority.

Destructor

~LifecycleControlHandle

Release this wrapper’s retained lifecycle-control capability.

Destruction never waits for a transaction or RunSession worker.

Assignment operators

operator=

LifecycleControlHandle & holoscan::LifecycleControlHandle::operator=(
    const LifecycleControlHandle &other
) noexcept

Replace this wrapper with the same authority as another handle.

This operation is nonblocking and performs no dynamic allocation.

Returns: This handle.

Parameters

other
const LifecycleControlHandle &

Handle to copy; self-assignment has no effect.

Methods

restrict

expected<LifecycleControlHandle, Error> holoscan::LifecycleControlHandle::restrict(
    const LifecycleAccessPolicy &policy
) const noexcept

Return a handle whose target and stage authority is no broader.

The returned handle owns its normalized restriction copy. The input spans are borrowed only for this call and may be released when the call returns. Restriction is a cold control-path operation serialized with submissions, receipt inspection, and final session cleanup by the run control mutex.

Returns: Restricted handle, or a typed error without changing this handle.

Parameters

policy
const LifecycleAccessPolicy &

Additional copied restrictions.

request_restart

expected<LifecycleRestartReceipt, Error> holoscan::LifecycleControlHandle::request_restart(
    OperatorRef target,
    LifecycleRestartOptions options = {}
) const noexcept

Request restart of one generation-stamped same-session target.

The call is nonblocking and does not dynamically allocate after the handle and RunSession have been constructed. Acceptance only queues the request and installs its activation fence. A target already computing finishes that callback before restart execution; an idle target restarts at the control safe point before its next compute callback.

Do not call from compute, lifecycle callbacks, or Dispatcher code. Use ExecutionContext::request_restart from compute instead.

Returns: Stable receipt when accepted; rejection changes no state.

Parameters

target
OperatorRef

Current-run target admitted by plan and handle policy.

options
LifecycleRestartOptionsDefaults to {}

Requested forward stage and registered bounded reason.

inspect

expected<LifecycleRestartReceiptView, Error> holoscan::LifecycleControlHandle::inspect(
    LifecycleRestartReceipt receipt
) const noexcept

Inspect the current bounded state of one accepted receipt.

Inspection does not wait, cancel, publish, or advance the transaction. Accepted receipts remain inspectable after the originating session closes. Inspection briefly serializes on the run control mutex and is not a lock-free hot-path operation.

Returns: Current state and lineage, or a typed error without advancing the transaction.

Parameters

receipt
LifecycleRestartReceipt

Receipt minted by this run session.

await

expected<LifecycleRestartReceiptView, Error> holoscan::LifecycleControlHandle::await(
    LifecycleRestartReceipt receipt,
    std::chrono::nanoseconds timeout
) const

Wait for a receipt to enter a terminal state.

This is the only potentially blocking handle operation. Timeout is a caller-side observation bound; it never cancels or mutates the transaction.

Do not call from compute, lifecycle callbacks, or Dispatcher code.

Returns: Terminal state, or a typed error without cancelling the transaction.

Parameters

receipt
LifecycleRestartReceipt

Receipt minted by this run session.

timeout
std::chrono::nanoseconds

Finite nonnegative caller-side maximum wait.

operator bool

holoscan::LifecycleControlHandle::operator bool() const noexcept

Return whether this wrapper contains a control capability.

Returns: true when the wrapper retains a capability, otherwise false.

Member variables

NameTypeDescription
state_detail::LifecycleControlHandleState *