Concept Map

A migration starts with the behavior that the application must keep: what produces data, what consumes it, when work starts, how missing data is handled, and how the application finishes. Once those decisions are clear, the old names can be matched to the current graph, operator, payload, and run-control model.

Use this map to decide what needs to change before editing individual calls. Continue with Applications, Fragments, and Graphs, then Conditions and Temporal Contracts, and finally Code-Level API Evolution.

Migration support

RidgeRun can review your current application, plan the changes for Holoscan 5, and help keep the data flow and timing your application needs. Contact RidgeRun for help with your migration.

Start with the behavior that must survive

Write down the answers to these questions for the existing application:

Which operator produces the first value, and which operator consumes the final result?
Does each input value start work, or must several inputs be selected together?
What should happen when an input is late, absent, or outside its valid age?
Is the payload a scalar value, a structured schema, or a Tensor with a specific memory placement?
Does the application finish naturally, wait for a request, or stop after a bounded amount of work?

These answers describe the application contract. They are more useful during migration than a direct search and replace of class or method names.

Map the main responsibilities

Historical responsibility	Current place	What to confirm
The application and its reusable groups	An owning `Graph` containing typed operators and connections.	The graph still has the same data flow, and reusable groups expose only the inputs and outputs that their parent needs.
Conditions and scheduler choices	A `Contract` that declares when an operator may run, which values it receives, and how missing values are handled.	The selected trigger and input policy produce the same observable behavior as the original application.
Payload and storage decisions	Typed ports plus the Tensor, schema, queue, and pool choices described in the graph and operator contracts.	The payload type, shape, layout, memory placement, and capacity still match the next operator.
Start, stop, and cleanup behavior	Operator lifecycle callbacks and the checked run or session result.	Resources are acquired and released at the same application boundaries, including natural completion and requested stop.
Communication with another process	An explicit external endpoint or channel boundary.	The peer's payload contract, catalog, role, and shutdown behavior are compatible.

Plan the migration in small steps

1. Rebuild the graph structure and confirm that the operators and connections match the original data flow. 2. Choose the trigger and input selection for each operator. The runtime uses those declarations to decide when compute() is eligible and which values are ready for it. 3. Preserve the payload contract. Add Tensor memory and capacity choices after the scalar or schema path is understood. 4. Port the operator code. Declare ports in setup(), declare timing in contract(), and process the selected data in compute(). 5. Compile the graph, inspect the result, run it, and test the missing-data and completion cases that matter to the application.

The smallest useful structural check looks like this:

holoscan::Graph graph{"pipeline"};
auto source = graph.op<SourceOp>("source");
auto sink = graph.op<SinkOp>("sink");
graph.add_flow(source-&gt;output, sink-&gt;input);

const auto plan = holoscan::compile(graph);
if (!plan.ok()) {
  std::cerr &lt;&lt; plan.json() &lt;&lt; '\n';
  return 1;
}
return holoscan::run(plan);

The Graph::op() and Graph::add_flow() calls establish the graph. compile() checks whether the declarations can form an executable plan, and run() starts the accepted plan. A successful compilation does not replace checks for devices, permissions, model files, transport peers, or application errors during execution.

Keep boundaries explicit

An embedded graph is a reusable part of one application. It does not automatically become a separate operating-system process. A separately deployed peer needs an explicit endpoint or channel boundary, with matching payload and shutdown rules. Follow External Endpoints and Endpoint Catalogs when that boundary is part of the migration.

The migration should also preserve the difference between a trigger and a data value. A trigger tells the runtime when the operator becomes eligible; the input selection tells it which values to prepare. The operator's compute() method can then focus on processing the data that the contract selected.

Related examples and concepts

Examples

First Pipeline provides a small typed graph and checked run path.
Automatic Partitioning Example shows how graph structure affects placement.
Managed Run Control Example demonstrates run outcomes and cleanup.

Concepts

Ports, Samples, and Payload Types introduces the data carried between operators.
Temporal Contracts and Input Selection explains trigger and selector choices.
Application, Graph, and Operator Anatomy follows the application authoring flow.

Official documentation

NVIDIA Holoscan SDK official documentation provides the current application and API reference.

❯