Dynamic Graph Behavior

Many applications need to change behavior while they run: a threshold may change, a device may need to be prepared again, or another process may connect to a declared data boundary. Holoscan supports these changes when they fit the execution plan that was compiled for the graph.

Start by identifying what changes. A setting can use a parameter update, preparation can use a lifecycle restart, and a new operator or edge needs a replacement graph. Automatic Partitioning and Plan Inspection explains what the accepted plan contains.

Choose the smallest change

Application need	Use this mechanism	What it can change
Set initial values before the run	Configure the operator handle before compiling.	The baseline used to create the plan.
Tune a supported scalar while running	Mark the field `runtime_mutable()` and submit a parameter update.	An admitted value such as a threshold, gain, or mode.
Repeat device or resource preparation	Request an authorized lifecycle restart.	The preparation stages admitted by the plan.
Connect another process	Attach to a declared external topic and compatible endpoint.	Data at the authored process boundary.
Add operators, edges, or larger resource bounds	Build and compile a replacement graph.	The new topology and its compiled requirements.

Configure the baseline before compiling

Values that determine graph structure or resource bounds belong in the authoring phase. Apply them before compile():

DetectorParams params{
    .threshold = 0.8F,
    .stride = 4U,
};

detector.set_params(params);
const auto plan = holoscan::compile(graph);

OperatorHandle::set_params() sets the initial aggregate for the operator handle. It validates the candidate before the run and does not modify a session that is already running. Typed Parameters and Configuration introduces the parameter type and validation flow.

Keep image dimensions, maximum batch sizes, and other values that define storage requirements in this phase. A running session keeps the plan it accepted at compilation.

Update a supported parameter

Use a runtime update for a bounded scalar that the operator has explicitly admitted:

field<&DetectorParams::threshold>("threshold").runtime_mutable();

The compile options must also admit runtime updates. Application control code submits the new value through the running session's parameter control handle. The update becomes visible at a supported boundary, so one callback reads one coherent parameter snapshot.

The complete control flow includes permissions, submission, and publication status. Follow Runtime Parameter Updates for the control-handle example and the supported scalar types. A parameter update cannot add a port, enlarge a Tensor bound, or change a graph edge.

Repeat preparation with a lifecycle restart

Use a lifecycle restart when the operator must run an admitted preparation stage again, for example after selecting a new device configuration. A restart pauses the affected work, runs the permitted teardown and preparation callbacks, and returns the operator to the running state.

The graph must grant the required restart authority and compile the lifecycle transaction support. A restart does not reconnect the graph or create a new partition. Keep the resource requirements inside the limits recorded by the plan.

Lifecycle Callbacks and Restart Control explains callback order, restart scope, and the control APIs. Operator Lifecycle introduces the stages before that detailed guide.

Attach an external peer

An external topic lets another process participate at a declared graph boundary. The peer must satisfy the endpoint catalog and payload contract created for that boundary. Connecting or disconnecting a peer does not add an internal operator or change the graph's queue and Tensor requirements.

Follow External Endpoints and Endpoint Catalogs for graph-side declarations and Standalone ChannelRuntime Clients for a client that owns its connection and shutdown.

Replace the graph when structure changes

Build a replacement graph when the change affects topology, placement, or compiled capacity:

Request stop on the current session and wait for its work to retire.
Author the replacement graph with its initial parameters, ports, connections, and external boundaries.
Compile the new graph and check plan.ok() before starting it.
Distribute the matching endpoint information and start the replacement session.

This is a controlled replacement. If the application needs overlap, state transfer, or a continuous handoff, design that behavior in the application and keep the two plan identities separate.

Related Examples

Typed parameters source shows authoring-time parameter configuration and validation.
Restart control source shows an authorized lifecycle restart and session observation.
Descriptor-tensor external topic source shows a process boundary with a declared payload.
Managed Run Control Example shows how to retire a session before starting another one.

Continue the flow

Automatic Partitioning and Plan Inspection explains the plan that limits dynamic changes.
Runtime Parameter Updates covers the full parameter control path.
External Endpoints and Endpoint Catalogs covers the process boundary.

Further Reading

Parameter mutability definitions declare which fields can change after compilation.
Lifecycle control definitions declare restart requests and observation.
Endpoint catalog definitions describe external boundaries.
NVIDIA Holoscan SDK User Guide provides the official configuration and runtime reference.

❯