holoscan::Fragment | Holoscan SDK Documentation

The fragment of the application.

A fragment is a building block of the Application. It is a directed graph of operators. A fragment can be assigned to a physical node of a Holoscan cluster during execution. The run-time execution manages communication across fragments. In a Fragment, Operators (Graph Nodes) are connected to each other by flows (Graph Edges).

#include <holoscan/fragment.hpp>

Inherits from: holoscan::FragmentServiceProvider (public)

Constructors

Fragment

Default

Deleted overloads

holoscan::Fragment::Fragment() = defaultholoscan::Fragment::Fragment() = default

Destructor

~Fragment

holoscan::Fragment::~Fragment() overrideholoscan::Fragment::~Fragment() override

Assignment operators

operator=

Deleted overloads

The following overloads are deleted to prevent misuse:

Fragment & holoscan::Fragment::operator=(const Fragment &) = delete;Fragment & holoscan::Fragment::operator=(const Fragment &) = delete;Fragment & holoscan::Fragment::operator=(const Fragment &) = delete;
Fragment & holoscan::Fragment::operator=(Fragment &&) = delete;Fragment & holoscan::Fragment::operator=(Fragment &&) = delete;Fragment & holoscan::Fragment::operator=(Fragment &&) = delete;

Methods

name

Set the name of the operator (1)

Set the name of the operator (2)

Const

Fragment & holoscan::Fragment::name(Fragment & holoscan::Fragment::name(
    const std::string &name
) &

Set the name of the operator.

Returns: The reference to this fragment (for chaining).

Parameters

name

const std::string &

The name of the operator.

application

Mutable

Const

Fragment & holoscan::Fragment::application(Fragment & holoscan::Fragment::application(
    Application *app
)

Set the application of the fragment.

Returns: The reference to this fragment (for chaining).

Parameters

app

Application *

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

void holoscan::Fragment::config(
    const std::string &config_file,
    const std::string &prefix = ""
)

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.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.
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.so are 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

config_file

const std::string &

The path to the configuration file.

prefix

const std::string &Defaults to ""

The prefix string that is prepended to the key of the configuration. (not implemented yet)

Example

extensions:
  - libmy_recorder.so
replayer:
  directory: "../data/racerx"
  basename: "racerx"
  frame_rate: 0   # as specified in timestamps
  repeat: false   # default: false
  realtime: true  # default: true
  count: 0        # default: 0 (no frame count restriction)
recorder:
  out_directory: "/tmp"
  basename: "tensor_out"

config_shared

std::shared_ptr<Config> holoscan::Fragment::config_shared()std::shared_ptr<Config> holoscan::Fragment::config_shared()

Get the shared pointer to the configuration of the fragment.

Returns: The shared pointer to the configuration of the fragment.

graph

OperatorFlowGraph & holoscan::Fragment::graph()

Get the graph of the fragment.

Returns: The reference to the graph of the fragment (OperatorFlowGraph object.)

graph_shared

std::shared_ptr<OperatorFlowGraph> holoscan::Fragment::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

void holoscan::Fragment::executor(
    const std::shared_ptr<Executor> &executor
)

Set the executor of the fragment.

Parameters

executor

const std::shared_ptr<Executor> &

The executor to be added.

executor_shared

std::shared_ptr<Executor> holoscan::Fragment::executor_shared()std::shared_ptr<Executor> holoscan::Fragment::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

std::shared_ptr<Scheduler> holoscan::Fragment::scheduler()std::shared_ptr<Scheduler> holoscan::Fragment::scheduler()

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

std::shared_ptr<NetworkContext> holoscan::Fragment::network_context()std::shared_ptr<NetworkContext> holoscan::Fragment::network_context()

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

virtual std::shared_ptr<NetworkContext> holoscan::Fragment::create_pubsub_network_context()virtual std::shared_ptr<NetworkContext> holoscan::Fragment::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

std::shared_ptr<NetworkContext> create_pubsub_network_context() override {
  return make_network_context<MyCustomPubSubContext>("pubsub_context");
}

from_config

ArgList holoscan::Fragment::from_config(ArgList holoscan::Fragment::from_config(
    const std::string &key
)

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:

Arg("width") = 1920
Arg("height") = 1080
Arg("rdma") = true

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

key

const std::string &

The key of the configuration.

Example

source: "replayer"
do_record: false   # or 'true' if you want to record input video stream.
capture_card:
  width: 1920
  height: 1080
  rdma: true

Example

auto is_rdma = from_config("capture_card.rdma").as<bool>();

config_keys

std::unordered_set<std::string> holoscan::Fragment::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

template <typename OperatorT,
          typename StringT,
          typename... ArgsT,
          typename = std::enable_if_t<std::is_constructible_v<std::string, StringT>>>
std::shared_ptr<OperatorT> holoscan::Fragment::make_operator(
    StringT name,
    ArgsT &&... args
)

Create a new operator.

Returns: The shared pointer to the operator.

Template parameters

OperatorT

typename

The type of the operator.

Parameters

name

StringT

The name of the operator.

args

ArgsT &&...

The arguments for the operator.

make_resource

Create a new (operator) resource (with name)

Create a new (operator) resource

template <typename ResourceT,
          typename StringT,
          typename... ArgsT,
          typename = std::enable_if_t<std::is_constructible_v<std::string, StringT>>>
std::shared_ptr<ResourceT> holoscan::Fragment::make_resource(
    StringT name,
    ArgsT &&... args
)

Create a new (operator) resource.

Returns: The shared pointer to the resource.

Template parameters

ResourceT

typename

The type of the resource.

Parameters

name

StringT

The name of the resource.

args

ArgsT &&...

The arguments for the resource.

make_condition

Create a new condition (with name)

Create a new condition

template <typename ConditionT,
          typename StringT,
          typename... ArgsT,
          typename = std::enable_if_t<std::is_constructible_v<std::string, StringT>>>
std::shared_ptr<ConditionT> holoscan::Fragment::make_condition(
    StringT name,
    ArgsT &&... args
)

Create a new condition.

Returns: The shared pointer to the condition.

Template parameters

ConditionT

typename

The type of the condition.

Parameters

name

StringT

The name of the condition.

args

ArgsT &&...

The arguments for the condition.

make_scheduler

Create a new scheduler (with name)

Create a new scheduler

template <typename SchedulerT,
          typename StringT,
          typename... ArgsT,
          typename = std::enable_if_t<std::is_constructible_v<std::string, StringT>>>
std::shared_ptr<SchedulerT> holoscan::Fragment::make_scheduler(
    StringT name,
    ArgsT &&... args
)

Create a new scheduler.

Returns: The shared pointer to the scheduler.

Template parameters

SchedulerT

typename

The type of the scheduler.

Parameters

name

StringT

The name of the scheduler.

args

ArgsT &&...

The arguments for the scheduler.

make_network_context

Create a new network context (with name)

Create a new network context

template <typename NetworkContextT,
          typename StringT,
          typename... ArgsT,
          typename = std::enable_if_t<std::is_constructible_v<std::string, StringT>>>
std::shared_ptr<NetworkContextT> holoscan::Fragment::make_network_context(
    StringT name,
    ArgsT &&... args
)

Create a new network context.

Returns: The shared pointer to the network context.

Template parameters

NetworkContextT

typename

The type of the network context.

Parameters

name

StringT

The name of the network context.

args

ArgsT &&...

The arguments for the network context.

make_thread_pool

std::shared_ptr<ThreadPool> holoscan::Fragment::make_thread_pool(std::shared_ptr<ThreadPool> holoscan::Fragment::make_thread_pool(
    const std::string &name,
    int64_t initial_size = 1
)

Create a new thread pool resource.

Returns: The shared pointer to the thread pool resource.

Parameters

name

const std::string &

The name of the thread pool.

initial_size

int64_tDefaults to 1

The initial number of threads in the thread pool.

add_default_green_context_pool

std::shared_ptr<CudaGreenContextPool> holoscan::Fragment::add_default_green_context_pool(std::shared_ptr<CudaGreenContextPool> holoscan::Fragment::add_default_green_context_pool(
    int32_t dev_id,
    std::vector<uint32_t> sms_per_partition = {},
    int32_t default_context_index = -1,
    uint32_t min_sm_size = 2
)

Add default green context pool.

Returns: The shared pointer to the green context pool resource.

Parameters

dev_id

int32_t

The device id.

sms_per_partition

std::vector<uint32_t>Defaults to {}

The number of SMs per partition.

default_context_index

int32_tDefaults to -1

The index of the default green context.

min_sm_size

uint32_tDefaults to 2

The minimum number of SMs per partition.

get_default_green_context_pool

std::shared_ptr<CudaGreenContextPool> holoscan::Fragment::get_default_green_context_pool()std::shared_ptr<CudaGreenContextPool> holoscan::Fragment::get_default_green_context_pool()

Get the default green context pool.

Returns: The shared pointer to the default green context pool.

get_service_erased

std::shared_ptr<FragmentService> holoscan::Fragment::get_service_erased(std::shared_ptr<FragmentService> holoscan::Fragment::get_service_erased(
    const std::type_info &service_type,
    std::string_view id
) const override

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

service_type

const std::type_info &

The type information of the service to retrieve.

std::string_view

The identifier of the service. If empty, retrieves by type only.

get_service_resource_by_name

std::shared_ptr<Resource> holoscan::Fragment::get_service_resource_by_name(std::shared_ptr<Resource> holoscan::Fragment::get_service_resource_by_name(
    std::string_view id
) const override

Retrieve a resource registered as a fragment service by name.

Returns: The shared pointer to the service resource, or nullptr if not found.

Parameters

std::string_view

The service id (name) used during service registration.

get_services_by_id

std::vector<std::shared_ptr<FragmentService>> holoscan::Fragment::get_services_by_id(std::vector<std::shared_ptr<FragmentService>> holoscan::Fragment::get_services_by_id(
    std::string_view id
) const override

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

std::string_view

The service id (name) used during service registration.

register_service

template <typename ServiceT>
bool holoscan::Fragment::register_service(
    const std::shared_ptr<ServiceT> &svc,
    std::string_view id = ""
)

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

ServiceT

typename

The type of the fragment service.

Parameters

svc

const std::shared_ptr<ServiceT> &

The shared pointer to the fragment service instance to register.

std::string_viewDefaults to ""

The identifier for the fragment service registration. If empty, uses the fragment service type as identifier.

register_service_from

virtual bool holoscan::Fragment::register_service_from(
    Fragment *fragment,
    std::string_view id
)

service

template <typename ServiceT = DefaultFragmentService>
std::shared_ptr<ServiceT> holoscan::Fragment::service(
    std::string_view id = ""
) const

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

ServiceT

typename

The type of the service/resource to retrieve. Must inherit from either Resource or FragmentService. Defaults to DefaultFragmentService if not specified.

Parameters

std::string_viewDefaults to ""

The identifier of the service/resource. If empty, retrieves by type only.

get_service_by_type_info

std::shared_ptr<FragmentService> holoscan::Fragment::get_service_by_type_info(std::shared_ptr<FragmentService> holoscan::Fragment::get_service_by_type_info(
    const std::type_info &service_type,
    std::string_view id = ""
) const

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

service_type

const std::type_info &

The type info of the service/resource to retrieve.

std::string_viewDefaults to ""

The identifier of the service/resource. If empty, retrieves by type only.

fragment_services_by_key

const std::unordered_map<ServiceKey, std::shared_ptr<FragmentService>, ServiceKeyHash> & holoscan::Fragment::fragment_services_by_key() constconst std::unordered_map<ServiceKey, std::shared_ptr<FragmentService>, ServiceKeyHash> & holoscan::Fragment::fragment_services_by_key() constconst std::unordered_map<ServiceKey, std::shared_ptr<FragmentService>, ServiceKeyHash> & holoscan::Fragment::fragment_services_by_key() constconst std::unordered_map<ServiceKey, std::shared_ptr<FragmentService>, ServiceKeyHash> & holoscan::Fragment::fragment_services_by_key() const

Get the fragment services by key.

Returns: The fragment services by key.

start_op

virtual const std::shared_ptr<Operator> & holoscan::Fragment::start_op()virtual const std::shared_ptr<Operator> & holoscan::Fragment::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

virtual void holoscan::Fragment::add_operator(
    const std::shared_ptr<Operator> &op
)

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

const std::shared_ptr<Operator> &

The operator to be added.

add_subgraph

virtual void holoscan::Fragment::add_subgraph(
    const std::shared_ptr<Subgraph> &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

subgraph

const std::shared_ptr<Subgraph> &

The subgraph to be added.

add_flow

Add a flow between two operators

Add a flow between two operators (with port pairs)

Overload 3

Overload 4

Overload 5

Overload 6

Overload 7

Overload 8

Overload 9

Overload 10

Overload 11

Overload 12

Overload 13

virtual void holoscan::Fragment::add_flow(
    const std::shared_ptr<Operator> &upstream_op,
    const std::shared_ptr<Operator> &downstream_op
)

Add a flow between two operators.

An output port of the upstream operator is connected to an input port of the downstream operator. The information about the flow (edge) is stored in the OperatorFlowGraph object.

If the upstream operator or the downstream operator is not in the graph, it will be added to the graph.

If there are multiple output ports in the upstream operator or multiple input ports in the downstream operator, it shows an error message.

Parameters

upstream_op

const std::shared_ptr<Operator> &

The upstream operator.

downstream_op

const std::shared_ptr<Operator> &

The downstream operator.

set_dynamic_flows

virtual void holoscan::Fragment::set_dynamic_flows(
    const std::shared_ptr<Operator> &op,
    const std::function<void(const std::shared_ptr<Operator> &)> &dynamic_flow_func
)

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

const std::shared_ptr<Operator> &

The operator to set dynamic flows for

dynamic_flow_func

const std::function<void(const std::shared_ptr<Operator> &)> &

The callback function that defines the dynamic flows. Takes a shared pointer to the operator as input and returns void.

make_subgraph

template <typename SubgraphT, typename... ArgsT>
std::shared_ptr<SubgraphT> holoscan::Fragment::make_subgraph(
    const std::string &name,
    ArgsT &&... args
)

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

SubgraphT

typename

The subgraph class type (must inherit from Subgraph)

Parameters

name

const std::string &

Unique name for this instance (used for operator qualification)

args

ArgsT &&...

Additional arguments to pass to the subgraph constructor

compose

virtual void holoscan::Fragment::compose()

Compose a graph.

The graph is composed by adding operators and flows in this method.

run

virtual void holoscan::Fragment::run()

Initialize the graph and run the graph.

This method calls compose() to compose the graph, and runs the graph.

run_async

virtual std::future<void> holoscan::Fragment::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

DataFlowTracker & holoscan::Fragment::track(DataFlowTracker & holoscan::Fragment::track(
    uint64_t num_start_messages_to_skip = kDefaultNumStartMessagesToSkip,
    uint64_t num_last_messages_to_discard = kDefaultNumLastMessagesToDiscard,
    int latency_threshold = kDefaultLatencyThreshold,
    bool is_limited_tracking = false
)

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

num_start_messages_to_skip

uint64_tDefaults to kDefaultNumStartMessagesToSkip

The number of messages to skip at the beginning.

num_last_messages_to_discard

uint64_tDefaults to kDefaultNumLastMessagesToDiscard

The number of messages to discard at the end.

latency_threshold

intDefaults to kDefaultLatencyThreshold

The minimum end-to-end latency in milliseconds to account for in the end-to-end latency metric calculations.

is_limited_tracking

boolDefaults to false

If true, the tracking is limited to root and leaf nodes, minimizing the timestamps by avoiding intermediate operators.

data_flow_tracker

DataFlowTracker * holoscan::Fragment::data_flow_tracker()DataFlowTracker * holoscan::Fragment::data_flow_tracker()

Get the DataFlowTracker object for this fragment.

Returns: The pointer to the DataFlowTracker object.

compose_graph

virtual void holoscan::Fragment::compose_graph()

Calls compose() if the graph is not composed yet.

port_info

FragmentPortMap holoscan::Fragment::port_info() constFragmentPortMap holoscan::Fragment::port_info() const

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*>).

is_metadata_enabled

Mutable

Const

virtual void holoscan::Fragment::is_metadata_enabled(
    bool enabled
)

Deprecated method for controlling whether metadata is enabled for the fragment.

Please use enable_metadata instead.

Parameters

enabled

bool

Boolean indicating whether metadata should be enabled.

enable_metadata

virtual void holoscan::Fragment::enable_metadata(
    bool enable
)

Enable or disable metadata for the fragment.

Controls whether metadata is enabled or disabled by default for operators within this fragment. If this method is not called, and this fragment is part of a distributed application, then the the parent application’s metadata policy will be used. Otherwise metadata is enabled by default. Individual operators can override this setting using the Operator::enable_metadata() method.

Parameters

enable

bool

Boolean indicating whether metadata should be enabled.

metadata_policy

Mutable

Const

virtual void holoscan::Fragment::metadata_policy(
    MetadataPolicy policy
)

Set the default metadata update policy to be used for operators within this fragment.

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).

Parameters

policy

MetadataPolicy

The metadata update policy to be used by this operator.

stop_execution

virtual void holoscan::Fragment::stop_execution(
    const std::string &op_name = ""
)

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

op_name

const std::string &Defaults to ""

The name of the operator to stop. If empty, all operators will be stopped.

add_data_logger

void holoscan::Fragment::add_data_logger(
    const std::shared_ptr<DataLogger> &logger
)

Add a data logger to the fragment.

Parameters

logger

const std::shared_ptr<DataLogger> &

The shared pointer to the data logger to add.

data_loggers

const std::vector<std::shared_ptr<DataLogger>> & holoscan::Fragment::data_loggers() constconst std::vector<std::shared_ptr<DataLogger>> & holoscan::Fragment::data_loggers() const

Get the data loggers associated with this fragment.

Returns: A const reference to the vector of data loggers.

subgraphs

const std::vector<std::shared_ptr<Subgraph>> & holoscan::Fragment::subgraphs() constconst std::vector<std::shared_ptr<Subgraph>> & holoscan::Fragment::subgraphs() const

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

bool holoscan::Fragment::is_gpu_resident() const

Check if the fragment has GPU-resident operators.

Returns: True if the fragment has GPU-resident operators, false otherwise.

gpu_resident

GPUResidentAccessor holoscan::Fragment::gpu_resident()GPUResidentAccessor holoscan::Fragment::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

fragment->gpu_resident().timeout_ms(1000);
fragment->gpu_resident().sync_with_host();
fragment->gpu_resident().data_ready();
fragment->gpu_resident().result_ready();
fragment->gpu_resident().is_launched();
fragment->gpu_resident().tear_down();

setup_component_internals

void holoscan::Fragment::setup_component_internals(
    ComponentBase *component
)

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

component

ComponentBase *

Pointer to the ComponentBase instance to configure. Must not be nullptr.

make_config

template <typename ConfigT, typename... ArgsT>
std::shared_ptr<Config> holoscan::Fragment::make_config(std::shared_ptr<Config> holoscan::Fragment::make_config(
    ArgsT &&... args
)

make_graph

template <typename GraphT>
std::shared_ptr<GraphT> holoscan::Fragment::make_graph()

make_executor

template <typename ExecutorT, typename... ArgsT>
std::shared_ptr<Executor> holoscan::Fragment::make_executor(std::shared_ptr<Executor> holoscan::Fragment::make_executor(
    ArgsT &&... args
)

Create and assign an Executor to the fragment.

reset_backend_objects

void holoscan::Fragment::reset_backend_objects()

Cleanup helper that will be called by the executor prior to destroying any backend context.

shutdown_data_loggers

void holoscan::Fragment::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.

reset_state

virtual void holoscan::Fragment::reset_state()

Reset internal fragment 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.

load_extensions_from_config

void holoscan::Fragment::load_extensions_from_config()

Load the GXF extensions specified in the configuration.

thread_pools

std::vector<std::shared_ptr<ThreadPool>> & holoscan::Fragment::thread_pools()std::vector<std::shared_ptr<ThreadPool>> & holoscan::Fragment::thread_pools()

resolve_subgraph_port

std::pair<std::shared_ptr<Operator>, std::string> holoscan::Fragment::resolve_subgraph_port(std::pair<std::shared_ptr<Operator>, std::string> holoscan::Fragment::resolve_subgraph_port(
    const std::shared_ptr<Subgraph> &subgraph,
    const std::string &interface_port
)

Resolve Subgraph interface port to actual operator and port.

Returns: Pair of (operator, actual_port_name) or (nullptr, "") if not found

Parameters

subgraph

const std::shared_ptr<Subgraph> &

The Subgraph to resolve the port in

interface_port

const std::string &

The interface port name

get_operator_output_ports

std::vector<std::string> holoscan::Fragment::get_operator_output_ports(
    const std::shared_ptr<Operator> &op
)

Get output port names from an operator.

get_operator_input_ports

std::vector<std::string> holoscan::Fragment::get_operator_input_ports(
    const std::shared_ptr<Operator> &op
)

Get input port names from an operator.

get_subgraph_output_ports

std::vector<std::string> holoscan::Fragment::get_subgraph_output_ports(
    const std::shared_ptr<Subgraph> &subgraph
)

Get output interface port names from a subgraph.

get_subgraph_input_ports

std::vector<std::string> holoscan::Fragment::get_subgraph_input_ports(
    const std::shared_ptr<Subgraph> &subgraph
)

Get input interface port names from a subgraph.

try_auto_resolve_ports

void holoscan::Fragment::try_auto_resolve_ports(
    const std::vector<std::string> &upstream_ports,
    const std::vector<std::string> &downstream_ports,
    const std::string &upstream_name,
    const std::string &downstream_name,
    std::set<std::pair<std::string, std::string>> &port_pairs
)

Attempt auto-resolution of port pairs between two entities.

Throws: std::runtime_error if auto-resolution fails

Parameters

upstream_ports

const std::vector<std::string> &

Output ports from upstream entity

downstream_ports

const std::vector<std::string> &

Input ports from downstream entity

upstream_name

const std::string &

Name of upstream entity (for error messages)

downstream_name

const std::string &

Name of downstream entity (for error messages)

port_pairs

std::set<std::pair<std::string, std::string>> &

Output parameter: will contain the resolved port pair if successful

resolve_and_create_op_to_subgraph_flows

void holoscan::Fragment::resolve_and_create_op_to_subgraph_flows(
    const std::shared_ptr<Operator> &upstream_op,
    const std::shared_ptr<Subgraph> &downstream_subgraph,
    const std::set<std::pair<std::string, std::string>> &port_pairs,
    const IOSpec::ConnectorType connector_type
)

Resolve and create flows for operator-to-subgraph connections.

resolve_and_create_subgraph_to_op_flows

void holoscan::Fragment::resolve_and_create_subgraph_to_op_flows(
    const std::shared_ptr<Subgraph> &upstream_subgraph,
    const std::shared_ptr<Operator> &downstream_op,
    const std::set<std::pair<std::string, std::string>> &port_pairs,
    const IOSpec::ConnectorType connector_type
)

Resolve and create flows for subgraph-to-operator connections.

resolve_and_create_subgraph_to_subgraph_flows

void holoscan::Fragment::resolve_and_create_subgraph_to_subgraph_flows(
    const std::shared_ptr<Subgraph> &upstream_subgraph,
    const std::shared_ptr<Subgraph> &downstream_subgraph,
    const std::set<std::pair<std::string, std::string>> &port_pairs,
    const IOSpec::ConnectorType connector_type
)

Resolve and create flows for subgraph-to-subgraph connections.

validate_control_flow_prerequisites

bool holoscan::Fragment::validate_control_flow_prerequisites(
    const std::shared_ptr<Operator> &upstream_op,
    const std::shared_ptr<Operator> &downstream_op,
    const IOSpec::ConnectorType connector_type
)

Validate prerequisites for establishing a control flow connection.

Returns: true if validation passes, false otherwise (error message will be logged)

Parameters

upstream_op

const std::shared_ptr<Operator> &

The upstream operator

downstream_op

const std::shared_ptr<Operator> &

The downstream operator

connector_type

const IOSpec::ConnectorType

The connector type (cannot be kAsyncBuffer for control flow)

create_control_flow_connection

void holoscan::Fragment::create_control_flow_connection(
    const std::shared_ptr<Operator> &upstream_op,
    const std::shared_ptr<Operator> &downstream_op
)

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

upstream_op

const std::shared_ptr<Operator> &

The upstream operator

downstream_op

const std::shared_ptr<Operator> &

The downstream operator

verify_gpu_resident_connections

bool holoscan::Fragment::verify_gpu_resident_connections(
    const std::shared_ptr<Operator> &upstream_op,
    const std::shared_ptr<Operator> &downstream_op,
    const std::shared_ptr<OperatorEdgeDataElementType> port_map
)

get_gpu_resident_executor

std::shared_ptr<GPUResidentExecutor> holoscan::Fragment::get_gpu_resident_executor(std::shared_ptr<GPUResidentExecutor> holoscan::Fragment::get_gpu_resident_executor(
    const char *func_name
)

Helper function to get GPU resident executor with error handling.

Returns: std::shared_ptr<GPUResidentExecutor> The GPU resident executor

Throws: RuntimeError if casting fails

Parameters

func_name

const char *

The name of the calling function (typically func)

Member variables

Name	Type	Description
`name_`	`std::string`	The name of the fragment.
`app_`	`Application *`	The application that this fragment belongs to.
`config_`	`std::shared_ptr< Config >`	The configuration of the fragment.
`executor_`	`std::shared_ptr< Executor >`	The executor for the fragment.
`graph_`	`std::shared_ptr< OperatorFlowGraph >`	The graph of the fragment.
`scheduler_`	`std::shared_ptr< Scheduler >`	Lazily initialized scheduler (mutable for const access).
`network_context_`	`std::shared_ptr< NetworkContext >`	The network_context used by the executor.
`data_flow_tracker_`	`std::shared_ptr< DataFlowTracker >`	The DataFlowTracker for the fragment.
`thread_pools_`	`std::vector< std::shared_ptr< ThreadPool > >`	Any thread pools used by the fragment.
`is_composed_`	`bool`	Whether the graph is composed or not.
`is_run_called_`	`bool`	Whether run() or run_async() has been called.
`is_metadata_enabled_`	`std::optional< bool >`	Whether metadata is enabled or not.
`metadata_policy_`	`std::optional< MetadataPolicy >`
`start_op_`	`std::shared_ptr< Operator >`	The start operator of the fragment (optional).
`data_loggers_`	`std::vector< std::shared_ptr< DataLogger > >`	Data loggers (optional).
`data_loggers_shutdown_mutex_`	`std::mutex`	Mutex to serialize shutdown_data_loggers() calls.
`data_loggers_shutdown_complete_`	`bool`	Flag to track if shutdown has completed.
`fragment_service_registry_mutex_`	`std::shared_mutex`	Mutex for thread-safe service registry access.
`fragment_services_by_key_`	`std::unordered_map< ServiceKey, std::shared_ptr< FragmentService >, ServiceKeyHash >`	service registry map
`fragment_resource_services_by_name_`	`std::unordered_map< std::string, std::shared_ptr< Resource > >`	service resource registry map
`fragment_resource_to_service_key_map_`	`std::unordered_map< std::shared_ptr< Resource >, ServiceKey >`	service resource registry map
`green_context_pools_`	`std::vector< std::shared_ptr< CudaGreenContextPool > >`
`subgraph_names_`	`std::unordered_set< std::string >`
`subgraphs_`	`std::vector< std::shared_ptr< Subgraph > >`
`is_gpu_resident_`	`bool`	Whether the fragment is a GPU resident fragment.

Inner classes

GPUResidentAccessor

class holoscan::Fragment::GPUResidentAccessor

Accessor class for GPU-resident specific functions of a Fragment.

This class provides a convenient interface for accessing GPU-resident specific functionality of a Fragment. It acts as a mediator to expose GPU-resident operations through a cleaner API pattern: fragment->``gpu_resident()``.function().

This is a lightweight accessor class that maintains a reference to the parent Fragment.

Name	Type	Description
`fragment_`	`Fragment *`	Pointer to the parent `Fragment`.