holoscan::Application
holoscan::Application
Application class.
An application acquires and processes streaming data. An application is a collection of fragments where each fragment can be allocated to execute on a physical node of a Holoscan cluster.
Inherits from: holoscan::Fragment (public)
Constructors
Application
Construct a new Application object.
This constructor parses the command line for flags that are recognized by App Driver/Worker, and removes all recognized flags so users can use the remaining flags for their own purposes.
The command line arguments are retrieved from /proc/self/cmdline so that the single-fragment application works as expected without any command line arguments.
The arguments after processing arguments are stored in the argv_ member variable and the reference to the vector of arguments can be accessed through the argv() method.
Example:
Parameters
The command line arguments.
Example
Destructor
~Application
Methods
make_fragment
Create a new fragment (with name)
Create a new fragment
Create a new fragment.
Returns: The shared pointer to the created fragment.
Template parameters
The type of the fragment to create.
Parameters
The name of the fragment.
The arguments to pass to the fragment constructor.
description
Get the application description
Set the application description (1)
Set the application description (2)
Get the application description.
Returns: The application description.
version
Get the application version
Set the application version (1)
Set the application version (2)
Get the application version.
Returns: The application version.
argv
Get the reference to the command line arguments after processing flags.
The returned vector includes the executable name as the first element.
Returns: The reference to the command line arguments after processing flags.
options
Get the reference to the CLI options.
Returns: The reference to the CLI options.
fragment_graph
Get the fragment connection graph.
When two operators are connected through add_flow(Fragment, Fragment), the fragment connection graph is automatically updated. The fragment connection graph is used to assign transmitters and receivers to the corresponding Operator instances in the fragment so that the application can be executed in a distributed manner.
Returns: The reference to the fragment connection graph (FragmentFlowGraph object.)
add_fragment
Add a fragment to the graph.
The information of the fragment is stored in the FragmentFlowGraph object. If the fragment is already added, this method does nothing.
Parameters
The fragment to be added.
add_flow
Add a flow between two fragments
Add a flow between two operators
Add a flow between two operators (with port pairs)
Overload 4
Overload 5
Overload 6
Overload 7
Overload 8
Overload 9
Overload 10
Overload 11
Overload 12
Overload 13
Overload 14
Add a flow between two fragments.
It takes two fragments and a vector of string pairs as arguments. The vector of string pairs is used to connect the output ports of the first fragment to the input ports of the second fragment. The input and output ports of the operators are specified as a string in the format of <operator name>.<port name>. If the operator has only one input or output port, the port name can be omitted.
In the above example, the output port of the blur_image operator in fragment1 is connected to the input port of the sharpen_image operator in fragment2. Since blur_image and sharpen_image operators have only one output/input port, the port names are omitted.
The information about the flow (edge) is stored in the FragmentFlowGraph object and can be accessed through the fragment_graph() method.
If the upstream fragment or the downstream fragment is not in the graph, it will be added to the graph.
Parameters
The upstream fragment.
The downstream fragment.
The port pairs. The first element of the pair is the output port of the operator in the upstream fragment and the second element is the input port of the operator in the downstream fragment.
Example
compose_graph
Calls compose() if the fragment graph is not composed yet.
run
Initialize the graph and run the graph.
This method calls compose() to compose the graph, and runs the graph.
run_async
Initialize the graph and run the graph asynchronously.
This method calls compose() to compose the graph, and runs the graph asynchronously.
Returns: The future object.
track_distributed
Returns a map of fragment names to DataFlowTracker* corresponding to respective fragments.
The trackers will store cumulatively progressive timestamps, meaning a fragment tracker will store the timestamps of operators in the previous fragments as well.
Returns: std::unordered_map<std::string, DataFlowTracker*> Fragment name to DataFlowTracker* mapping.
Parameters
The number of start messages to skip.
The number of last messages to discard.
The latency threshold.
Whether to enable limited tracking for performance.
is_metadata_enabled
Mutable
Const
Deprecated method to enable or disable metadata for the application.
Please use enable_metadata instead.
Parameters
Boolean indicating whether metadata should be enabled.
enable_metadata
Enable or disable metadata for the application.
Controls whether metadata is enabled or disabled by default for fragments in this application. Individual fragments of a distributed application can override this setting using the Fragment::enable_metadata() method. Similarly, individual operators can override the default for their fragment by using the Operator::enable_metadata() method.
Parameters
Boolean indicating whether metadata should be enabled.
metadata_policy
Mutable
Const
Set the default metadata update policy to be used for fragments within this application.
The metadata policy determines how metadata is merged across multiple receive calls:
MetadataPolicy::kUpdate: Update the existing value when a key already exists.MetadataPolicy::kInplaceUpdate: Update the existing MetadataObject’s value in-place when a key already exists.MetadataPolicy::kReject: Do not modify the existing value if a key already exists.MetadataPolicy::kRaise: Raise an exception if a key already exists (default).
For distributed applications, individual fragments can override the application-level default via Fragment::metadata_policy.
Parameters
The metadata update policy to be used by this operator.
app_driver_client
Get the AppDriverClient for the application.
Returns: The shared pointer to the AppDriverClient.
initiate_distributed_app_shutdown
Initiate shutdown of the distributed application.
This method initiates a shutdown of the distributed application by calling the initiate_shutdown method on the AppDriverClient.
Parameters
The name of the fragment initiating the shutdown.
add_data_logger
Add a data logger to the application.
This method adds a data logger to the application. For distributed applications, the data logger is added to each fragment in the fragment graph.
Parameters
The data logger to add.
name
Set the name of the operator (1)
Set the name of the operator (2)
Const
Set the name of the operator.
Returns: The reference to this fragment (for chaining).
Parameters
The name of the operator.
application
Mutable
Const
Set the application of the fragment.
Returns: The reference to this fragment (for chaining).
Parameters
The pointer to the application of the fragment.
config
Set the configuration of the fragment (with config file and prefix)
Set the configuration of the fragment (with config)
Get the configuration of the fragment
Set the configuration of the fragment.
The configuration file is a YAML file that has the information of GXF extension paths and some parameter values for operators.
The extensions field in the YAML configuration file is a list of GXF extension paths. The paths can be absolute or relative to the current working directory, considering paths in LD_LIBRARY_PATH environment variable.
The paths can consist of the following parts:
- GXF core extensions
built-in extensions such as libgxf_std.so and libgxf_cuda.so.
libgxf_std.so, libgxf_cuda.so, libgxf_multimedia.so, libgxf_serialization.so are always loaded by default.
GXF core extensions are copied to the lib directory of the build/installation directory.
- built-in extensions such as
libgxf_std.soandlibgxf_cuda.so. libgxf_std.so,libgxf_cuda.so,libgxf_multimedia.so,libgxf_serialization.soare always loaded by default.- GXF core extensions are copied to the
libdirectory of the build/installation directory.
- built-in extensions such as
- Other GXF extensions
GXF extensions that are required for operators that this fragment uses.
some core GXF extensions such as libgxf_stream_playback.so are always loaded by default.
these paths are usually relative to the build/installation directory.
- GXF extensions that are required for operators that this fragment uses.
- some core GXF extensions such as
libgxf_stream_playback.soare always loaded by default. - these paths are usually relative to the build/installation directory.
The extension paths are used to load dependent GXF extensions at runtime when ::run() method is called.
For other fields in the YAML file, you can freely define the parameter values for operators/fragments.
For example:
You can get the value of this configuration file by calling ::from_config() method.
If the application is executed with --config option or HOLOSCAN_CONFIG_PATH environment, the configuration file is overridden by the configuration file specified by the option or environment variable.
Throws: RuntimeError if the config_file is non-empty and the file doesn’t exist.
Parameters
The path to the configuration file.
The prefix string that is prepended to the key of the configuration. (not implemented yet)
Example
config_shared
Get the shared pointer to the configuration of the fragment.
Returns: The shared pointer to the configuration of the fragment.
graph
Get the graph of the fragment.
Returns: The reference to the graph of the fragment (OperatorFlowGraph object.)
graph_shared
Get the shared pointer to the graph of the fragment.
Returns: The shared pointer to the graph of the fragment.
executor
Set the executor of the fragment
Get the executor of the fragment
Set the executor of the fragment.
Parameters
The executor to be added.
executor_shared
Get the shared pointer to the executor of the fragment.
Returns: The shared pointer to the executor of the fragment.
scheduler
Get the scheduler used by the executor
Const
Set the scheduler used by the executor
Get the scheduler used by the executor.
Returns: The reference to the scheduler of the fragment’s executor (Scheduler object.)
network_context
Get the network context used by the executor
Set the network context used by the executor
Get the network context used by the executor.
Returns: The reference to the network context of the fragment’s executor (NetworkContext object.)
create_pubsub_network_context
Create the NetworkContext for PubSub connectors.
Called by the executor when PubSub connectors are detected and no NetworkContext has been explicitly set via network_context().
Override in your Application subclass to return a custom PubSubContext subclass with a concrete backend:
Returns: A new NetworkContext to use for PubSub connectors.
Example
from_config
Get the Argument(s) from the configuration file.
For the given key, this method returns the value of the configuration file.
For example:
from_config("capture_card") returns an ArgList (vector-like) object that contains the following items:
You can use ’.’ (dot) to access nested fields.
from_config("capture_card.rdma") returns an ArgList object that contains only one item and it can be converted to bool through ArgList::as() method:
Returns: The argument list of the configuration for the key.
Parameters
The key of the configuration.
Example
Example
config_keys
Determine the set of keys present in a Fragment’s config.
Returns: The set of valid keys.
make_operator
Create a new operator (with name)
Create a new operator
Create a new operator.
Returns: The shared pointer to the operator.
Template parameters
The type of the operator.
Parameters
The name of the operator.
The arguments for the operator.
make_resource
Create a new (operator) resource (with name)
Create a new (operator) resource
Create a new (operator) resource.
Returns: The shared pointer to the resource.
Template parameters
The type of the resource.
Parameters
The name of the resource.
The arguments for the resource.
make_condition
Create a new condition (with name)
Create a new condition
Create a new condition.
Returns: The shared pointer to the condition.
Template parameters
The type of the condition.
Parameters
The name of the condition.
The arguments for the condition.
make_scheduler
Create a new scheduler (with name)
Create a new scheduler
Create a new scheduler.
Returns: The shared pointer to the scheduler.
Template parameters
The type of the scheduler.
Parameters
The name of the scheduler.
The arguments for the scheduler.
make_network_context
Create a new network context (with name)
Create a new network context
Create a new network context.
Returns: The shared pointer to the network context.
Template parameters
The type of the network context.
Parameters
The name of the network context.
The arguments for the network context.
make_thread_pool
Create a new thread pool resource.
Returns: The shared pointer to the thread pool resource.
Parameters
The name of the thread pool.
The initial number of threads in the thread pool.
add_default_green_context_pool
Add default green context pool.
Returns: The shared pointer to the green context pool resource.
Parameters
The device id.
The number of SMs per partition.
The index of the default green context.
The minimum number of SMs per partition.
get_default_green_context_pool
Get the default green context pool.
Returns: The shared pointer to the default green context pool.
get_service_erased
Get a fragment service by type information and identifier.
Implementation of the FragmentServiceProvider interface method for retrieving registered fragment services using runtime type information. This method provides type-erased access to services and is thread-safe.
Returns: The shared pointer to the fragment service, or nullptr if not found.
Parameters
The type information of the service to retrieve.
The identifier of the service. If empty, retrieves by type only.
get_service_resource_by_name
Retrieve a resource registered as a fragment service by name.
Returns: The shared pointer to the service resource, or nullptr if not found.
Parameters
The service id (name) used during service registration.
get_services_by_id
Retrieve all fragment services with a matching id, regardless of registered type.
This method is used as a fallback when exact type lookup fails, enabling retrieval of services registered with a derived type when looking up by a base type.
Returns: A vector of shared_ptrs to matching FragmentServices. Empty if none found.
Parameters
The service id (name) used during service registration.
register_service
Register an existing fragment service instance.
Registers an already created fragment service instance with the specified identifier. This allows the fragment service to be retrieved later using the service() method.
Returns: true if the service was successfully registered, false otherwise.
Template parameters
The type of the fragment service.
Parameters
The shared pointer to the fragment service instance to register.
The identifier for the fragment service registration. If empty, uses the fragment service type as identifier.
register_service_from
service
Retrieve a registered fragment service or resource.
Retrieves a previously registered fragment service or resource by its type and optional identifier. Returns nullptr if no service/resource is found with the specified type and identifier.
Note that any changes to the service retrieval logic in this method should be synchronized with the implementation in ComponentBase::service() method to maintain consistency.
Returns: The shared pointer to the service/resource, or nullptr if not found or if type casting fails.
Template parameters
The type of the service/resource to retrieve. Must inherit from either Resource or FragmentService. Defaults to DefaultFragmentService if not specified.
Parameters
The identifier of the service/resource. If empty, retrieves by type only.
get_service_by_type_info
Retrieve a registered fragment service or resource for Python bindings.
This is a helper method for Python bindings to retrieve a service by its C++ type info.
Returns: The shared pointer to the base service, or nullptr if not found.
Parameters
The type info of the service/resource to retrieve.
The identifier of the service/resource. If empty, retrieves by type only.
fragment_services_by_key
Get the fragment services by key.
Returns: The fragment services by key.
start_op
Get or create the start operator for this fragment.
This operator is nothing but the first operator that was added to the fragment. It has the name of <|start|> and has a condition of CountCondition(1). This Operator is used to start the execution of the fragment. Entry operators who want to start the execution of the fragment should connect to this operator.
If this method is not called, no start operator is created. Otherwise, the start operator is created if it does not exist, and the shared pointer to the start operator is returned.
Returns: The shared pointer to the start operator.
add_operator
Add an operator to the graph.
The information of the operator is stored in the OperatorFlowGraph object. If the operator is already added, this method does nothing.
Parameters
The operator to be added.
add_subgraph
Add a subgraph to the fragment, taking ownership.
This method takes ownership of the subgraph by storing the shared pointer, registers the subgraph name for duplicate detection, and ensures the subgraph is composed.
This is the recommended way to add a pre-constructed subgraph (e.g. from a factory method) to a Fragment. The Fragment will keep the subgraph alive for the duration of its lifetime.
This method is also called automatically by add_flow() overloads that take Subgraph arguments, so explicit calls are only needed when a subgraph has no flows (self-contained).
Calling this on a subgraph that is already owned (e.g. after make_subgraph) is a safe no-op.
Throws: std::runtime_error if a subgraph with the same name has already been added.
Parameters
The subgraph to be added.
set_dynamic_flows
Set a callback function to define dynamic flows for an operator at runtime.
This method allows operators to modify their connections with other operators during execution. The callback function is called after the operator executes and can add dynamic flows using the operator’s add_dynamic_flow() methods.
Parameters
The operator to set dynamic flows for
The callback function that defines the dynamic flows. Takes a shared pointer to the operator as input and returns void.
make_subgraph
Create and compose a Subgraph.
Creates a Subgraph that directly populates this Fragment’s operator graph. The Subgraph is composed immediately and its operators are added with qualified names to the Fragment’s main graph.
Returns: Shared pointer to the composed Subgraph
Template parameters
The subgraph class type (must inherit from Subgraph)
Parameters
Unique name for this instance (used for operator qualification)
Additional arguments to pass to the subgraph constructor
compose
Compose a graph.
The graph is composed by adding operators and flows in this method.
track
Turn on data frame flow tracking.
A reference to a DataFlowTracker object is returned rather than a pointer so that the developers can use it as an object without unnecessary pointer dereferencing.
Returns: A reference to the DataFlowTracker object in which results will be stored.
Parameters
The number of messages to skip at the beginning.
The number of messages to discard at the end.
The minimum end-to-end latency in milliseconds to account for in the end-to-end latency metric calculations.
If true, the tracking is limited to root and leaf nodes, minimizing the timestamps by avoiding intermediate operators.
data_flow_tracker
Get the DataFlowTracker object for this fragment.
Returns: The pointer to the DataFlowTracker object.
port_info
Get an easily serializable summary of port information.
The FragmentPortMap class is used by distributed applications to send port information between application workers and the driver.
Returns: An unordered_map of the fragment’s port information where the keys are operator names and the values are a 3-tuple. The first two elements of the tuple are the set of input and output port names, respectively. The third element of the tuple is the set of “receiver” parameters (those with type std::vector<IOSpec*>).
stop_execution
Stop the execution of all operators in the fragment.
This method is used to stop the execution of all operators in the fragment by setting the internal async condition of each operator to EVENT_NEVER state, which sets the scheduling condition to NEVER. Once stopped, the operators will not be scheduled for execution (the compute() method will not be called), which may lead to application termination depending on the application’s design.
Note that executing this method does not trigger the operators’ stop() method. The stop() method is called only when the scheduler deactivates all operators together.
Parameters
The name of the operator to stop. If empty, all operators will be stopped.
data_loggers
Get the data loggers associated with this fragment.
Returns: A const reference to the vector of data loggers.
subgraphs
Get the top-level subgraphs owned by this fragment.
Returns subgraphs added via make_subgraph() or add_subgraph(). Nested subgraphs within these are accessible via Subgraph::nested_subgraphs().
Returns: A const reference to the vector of owned subgraphs.
is_gpu_resident
Check if the fragment has GPU-resident operators.
Returns: True if the fragment has GPU-resident operators, false otherwise.
gpu_resident
Get an accessor for GPU-resident specific functions.
This method returns a GPUResidentAccessor object that provides convenient access to GPU-resident specific functionality. For example:
Returns: A GPUResidentAccessor object for accessing GPU-resident functions.
Throws: RuntimeError if the fragment does not have GPU-resident operators.
Example
setup_component_internals
Set up internal state for a component.
Configures the component’s internal references to this fragment and its service provider. This method is called internally when creating operators, resources, conditions, and other components to ensure they have proper access to fragment services.
Parameters
Pointer to the ComponentBase instance to configure. Must not be nullptr.
driver
Get the application driver.
Returns: The reference to the application driver.
worker
Get the application worker.
Returns: The reference to the application worker.
process_arguments
reset_state
Reset internal application state to allow for multiple run calls.
This method resets the necessary internal state to allow multiple consecutive calls to run() or run_async() without requiring manual cleanup.
attach_services_to_fragment
Attach application services to a specified fragment.
Parameters
The fragment to which services will be attached.
make_config
make_graph
make_executor
Create and assign an Executor to the fragment.
reset_backend_objects
Cleanup helper that will be called by the executor prior to destroying any backend context.
shutdown_data_loggers
Shutdown data loggers to ensure async loggers complete before GXF context destruction.
This method is thread-safe and idempotent - multiple calls will block until the first completes, then return immediately. This ensures proper synchronization between signal handlers and normal shutdown paths.
load_extensions_from_config
Load the GXF extensions specified in the configuration.
thread_pools
resolve_subgraph_port
Resolve Subgraph interface port to actual operator and port.
Returns: Pair of (operator, actual_port_name) or (nullptr, "") if not found
Parameters
The Subgraph to resolve the port in
The interface port name
get_operator_output_ports
Get output port names from an operator.
get_operator_input_ports
Get input port names from an operator.
get_subgraph_output_ports
Get output interface port names from a subgraph.
get_subgraph_input_ports
Get input interface port names from a subgraph.
try_auto_resolve_ports
Attempt auto-resolution of port pairs between two entities.
Throws: std::runtime_error if auto-resolution fails
Parameters
Output ports from upstream entity
Input ports from downstream entity
Name of upstream entity (for error messages)
Name of downstream entity (for error messages)
Output parameter: will contain the resolved port pair if successful
resolve_and_create_op_to_subgraph_flows
Resolve and create flows for operator-to-subgraph connections.
resolve_and_create_subgraph_to_op_flows
Resolve and create flows for subgraph-to-operator connections.
resolve_and_create_subgraph_to_subgraph_flows
Resolve and create flows for subgraph-to-subgraph connections.
validate_control_flow_prerequisites
Validate prerequisites for establishing a control flow connection.
Returns: true if validation passes, false otherwise (error message will be logged)
Parameters
The upstream operator
The downstream operator
The connector type (cannot be kAsyncBuffer for control flow)
create_control_flow_connection
Create and register a control flow connection between two operators.
This helper creates the port map, sets self_shared on both operators, adds the flow to the graph, and registers it with the executor.
Parameters
The upstream operator
The downstream operator
initiate_local_app_shutdown
Initiate shutdown of a local multi-fragment application.
This method initiates an orderly shutdown of fragments running in local mode (multiple fragments in one process). Fragments are terminated in topological order (root/upstream fragments first) to avoid connection errors.
Parameters
The name of the fragment initiating the shutdown (currently unused but kept for API consistency).
is_any_fragment_gpu_resident
Check if any fragment in the application’s fragment graph is GPU-resident.
Returns: true if any fragment in the application’s fragment graph is GPU-resident, false otherwise.
set_ucx_env
Configure UCX environment variables.
set_v4l2_env
check_stack_size
Check stack size and warn if below recommended minimum.
Static methods
get_distributed_app_scheduler_env
get_stop_on_deadlock_env
get_stop_on_deadlock_timeout_env
get_ucx_network_connection_timeout_env
get_max_duration_ms_env
get_check_recession_period_ms_env
set_scheduler_for_fragments
Set the scheduler for fragments object.
Set scheduler for each fragment to use multi-thread scheduler by default because UcxTransmitter/UcxReceiver doesn’t work with GreedyScheduler with the following graph.
- Fragment (fragment1) Operator (op1) Output port: out
Operator (op2) Output port: out
- Operator (op1)
Output port: out
- Output port: out
- Operator (op2)
Output port: out
- Output port: out
- Fragment (fragment2)
Operator (op3)
Input ports
in1
in2
- Operator (op3)
Input ports
in1
in2
- Input ports
in1
in2
- in1
- in2
- Input ports
in1
in2
- Operator (op3)
Input ports
in1
in2
With the following graph connections, due to how UcxTransmitter/UcxReceiver works, UCX connections between op1 and op3 and between op2 and op3 are not established (resulting in a deadlock).
- op1.out -> op3.in1
- op2.out -> op3.in2
Parameters
The fragments to set the scheduler.
Optional scheduler set on the Application. If provided and a fragment doesn’t have its own scheduler set, this scheduler will be used for that fragment.