holoscan::AppDriver

Beta

#include <holoscan/app_driver.hpp>

Constructors

AppDriver

holoscan::AppDriver::AppDriver(
    Application *app
)

Destructor

~AppDriver

virtual holoscan::AppDriver::~AppDriver()

Methods

run

void holoscan::AppDriver::run()

run_async

std::future<void> holoscan::AppDriver::run_async()

options

CLIOptions * holoscan::AppDriver::options()

status

AppStatus holoscan::AppDriver::status()

Note that the application status is not updated when the application is running locally.

fragment_scheduler

FragmentScheduler * holoscan::AppDriver::fragment_scheduler()

all_fragment_port_map

MultipleFragmentsPortMap * holoscan::AppDriver::all_fragment_port_map()

submit_message

void holoscan::AppDriver::submit_message(
    DriverMessage &&message,
    bool log_error_on_failure = true
)

process_message_queue

void holoscan::AppDriver::process_message_queue()

schedule

std::unordered_map<std::string, std::string> holoscan::AppDriver::schedule() const

Get the schedule of the application.

The schedule is a map of fragment names to worker IDs.

This will be empty until after check_fragment_schedule has been called.

Returns: The schedule of the application.

terminate_all_workers

void holoscan::AppDriver::terminate_all_workers(
    AppWorkerTerminationCode error_code
)

Terminate all workers and close all worker connections.

set_status

void holoscan::AppDriver::set_status(
    AppStatus status
)

Allow AppDriverServiceImpl to set the app status.

handle_driver_start

bool holoscan::AppDriver::handle_driver_start(
    const std::string_view &server_ip
)

Start the fragment services.

handle_driver_shutdown

bool holoscan::AppDriver::handle_driver_shutdown() noexcept

Handle driver shutdown for fragment services.

Returns: true if all services shut down successfully, false if any failures occurred

setup_signal_handlers

void holoscan::AppDriver::setup_signal_handlers()

need_to_update_port_names

bool holoscan::AppDriver::need_to_update_port_names(
    std::shared_ptr<holoscan::FragmentEdgeDataElementType> &port_map
)

Check if update_port_names needs to be called.

update_port_names

bool holoscan::AppDriver::update_port_names(
    std::string src_frag_name,
    std::string target_frag_name,
    std::shared_ptr<holoscan::FragmentEdgeDataElementType> &port_map
)

Correct the port names of the given fragment graph edge.

This takes cases where a source operator has only one port and only the operator name was specified during add_flow. This function will append the ”.<port_name>” to the operator name. The same sort of appending of the port name is also done for any target operators having only a single input port.

collect_connections

bool holoscan::AppDriver::collect_connections(
    holoscan::FragmentFlowGraph &fragment_graph
)

Collect fragment connections.

Port names of the fragment graph edges are corrected during this process (via update_port_names).

correct_connection_map

void holoscan::AppDriver::correct_connection_map()

Correct connection map.

connection_map_ is initialized with the default IP (0.0.0.0) and port (zero-based index). This function corrects the connection map by replacing the default IP and port with the real IP and port (using index_to_ip_map_ and index_to_port_map_).

connect_fragments

void holoscan::AppDriver::connect_fragments(
    holoscan::FragmentFlowGraph &fragment_graph,
    std::vector<holoscan::FragmentNodeType> &target_fragments
)

Connect target fragments with UCX connector.

check_configuration

bool holoscan::AppDriver::check_configuration()

Check the configuration of the application.

This function checks if the application is running locally or remotely and sets the corresponding flags. This also calls the application’s compose() function to compose the application.

collect_resource_requirements

void holoscan::AppDriver::collect_resource_requirements(
    const Config &app_config,
    holoscan::FragmentFlowGraph &fragment_graph
)

Get the system resource requirement of the fragment.

parse_resource_requirement

Overload 1

Overload 2

Overload 3

SystemResourceRequirement holoscan::AppDriver::parse_resource_requirement(
    const YAML::Node &node
)

Parse the system resource requirement from the given YAML node.

check_fragment_schedule

void holoscan::AppDriver::check_fragment_schedule(
    const std::string &worker_address = ""
)

Check the fragment schedule to ensure that all fragments are scheduled to run.

check_worker_execution

void holoscan::AppDriver::check_worker_execution(
    const AppWorkerTerminationStatus &termination_status
)

Check if the all workers have finished execution.

launch_app_driver

void holoscan::AppDriver::launch_app_driver()

Run the application in driver mode.

Even if the application is running locally, we launch the driver to provide the health check service if need_health_check_ is true.

launch_app_worker

void holoscan::AppDriver::launch_app_worker()

Run the application in worker mode.

launch_fragments_async

std::future<void> holoscan::AppDriver::launch_fragments_async(
    std::vector<FragmentNodeType> &target_fragments
)

Launch fragments asynchronously.

update_root_fragments

void holoscan::AppDriver::update_root_fragments(
    const FragmentFlowGraph &graph,
    const std::unordered_set<std::string> &terminated_fragments
)

Helper method to update root fragments after a fragment is terminated.

Static methods

get_bool_env_var

static bool holoscan::AppDriver::get_bool_env_var(
    const char *name,
    bool default_value = false
)

Retrieves a boolean value from an environment variable.

This function fetches the value of a named environment variable and converts it to a boolean. The conversion is case-insensitive and accepts “true”, “1”, or “on” as true, any other values are considered false. If the environment variable is not set or its value is not recognized as ‘true’, the function returns a default value.

This function uses std::getenv() to access environment variables. The environment variable to look up is specified by the ‘name’ parameter. The value of the environment variable is converted to a lower-case string, and compared to the known ‘true’ strings.

The function does not throw an exception if the environment variable is not found or if the value does not match any of the expected ‘true’ strings.

Returns: true if the environment variable is set and its value is recognized as ‘true’, and false otherwise. If the environment variable is not set, the function returns ‘default_value’.

Parameters

name

const char *

The name of the environment variable to look up.

default_value

boolDefaults to false

The value to return if the environment variable is not set or its value does not match any of the known ‘true’ strings. The default is ‘false’.

get_int_env_var

static int64_t holoscan::AppDriver::get_int_env_var(
    const char *name,
    int64_t default_value = 0
)

Retrieves an integer value from an environment variable.

Returns: The value of the environment variable, converted to an integer. If the environment variable is not set or its value is not a valid integer, the function returns ‘default_value’.

Parameters

name

const char *

The name of the environment variable to look up.

default_value

int64_tDefaults to 0

The value to return if the environment variable is not set or its value is not a valid integer. The default is 0.

parse_memory_size

static uint64_t holoscan::AppDriver::parse_memory_size(
    const std::string &size_str
)

Parses a string representing a memory size and returns its value in bytes.

This method takes a string in the format of “XGi” or “XMi”, where X is a numerical value, and Mi/Gi represents Mebibytes/Gibibytes. The method converts this string into an equivalent memory size in bytes.

The string is case-insensitive, meaning that “1gi” is considered equivalent to “1Gi”.

The string is expected to represent a positive integer followed by either “M” or “G”, signifying mebibytes or gibibytes, respectively. If the string does not follow this format, the behavior is undefined.

Returns: The memory size represented by size_str, converted into bytes. For example, if size_str is “1Gi”, the return value will be 1,073,741,824 (1024 * 1024 * 1024). If size_str is “500Mi”, the return value will be 524,288,000 (500 * 1024 * 1024).

Parameters

size_str

const std::string &

A string representing a memory size in mebibytes or gibibytes. For example, “1Gi” represents one gibibyte and “500Mi” represents 500 mebibytes.

set_ucx_to_exclude_cuda_ipc

static void holoscan::AppDriver::set_ucx_to_exclude_cuda_ipc()

Set UCX_TLS to disable cuda_ipc transport.

Will check the UCX_TLS environment variable. If it is not already set, it sets UCX_TLS=^cuda_ipc to exclude this transport method. If it is already set and cuda_ipc is not excluded, a warning will be logged.

exclude_cuda_ipc_transport_on_igpu

static void holoscan::AppDriver::exclude_cuda_ipc_transport_on_igpu()

Disable CUDA interprocess communication (IPC) if the fragment is running on an iGPU.

Tegra devices do not support CUDA IPC.

Calls set_ucx_tls_to_exclude_cuda_ipc if we are running on iGPU.

Types

AppStatus

Name	Value	Description
`kNotInitialized`
`kNotStarted`
`kRunning`
`kFinished`
`kError`

DriverMessageCode

Name	Value	Description
`kCheckFragmentSchedule`
`kWorkerExecutionFinished`
`kTerminateServer`

Member variables

Name	Type	Description
`app_`	`Application *`	The application to run.
`options_`	`CLIOptions *`	The command line options.
`need_health_check_`	`bool`	Whether to check the health of the application.
`need_driver_`	`bool`	Whether to run the application in driver mode.
`need_worker_`	`bool`	Whether to run the application in worker mode.
`is_local_`	`bool`	Whether the application is running locally without a server.
`app_status_`	`AppStatus`	The status of the application.
`connection_map_`	`std::unordered_map< std::shared_ptr< Fragment >, std::vector< std::shared_ptr< ConnectionItem > > >`	The map that associates a fragment with a list of connection items.
`receiver_port_map_`	`std::unordered_map< std::string, std::vector< std::pair< int32_t, uint32_t > > >`	The map that associates a fragment name with a list of pairs.
`index_to_ip_map_`	`std::unordered_map< int32_t, std::string >`	Maps port indices to their IP addresses (initially set to the fragment name).
`index_to_port_map_`	`std::unordered_map< int32_t, uint32_t >`	Maps port indices to real port numbers (initially set to 0).
`driver_server_`	`std::unique_ptr< distributed::AppDriverServer >`
`fragment_scheduler_`	`std::unique_ptr< FragmentScheduler >`
`schedule_`	`std::unordered_map< std::string, std::string >`
`message_mutex_`	`std::mutex`	Mutex for the message queue.
`message_queue_`	`std::queue< DriverMessage >`	Queue of messages to be processed.
`shutdown_complete_`	`std::shared_ptr< std::atomic< bool > >`	Flag to cancel watchdog on clean exit.
`all_fragment_port_map_`	`std::unique_ptr< MultipleFragmentsPortMap >`	Data structure for collecting fragment port information from all workers of a distributed application.
`current_root_workers_`	`std::set< std::string >`	ids of workers that are currently running root fragments
`scheduling_started_`	`bool`	Flag to prevent rescheduling.
`scheduling_mutex_`	`std::mutex`	Mutex for fragment scheduling.

Inner classes

DriverMessage

struct holoscan::AppDriver::DriverMessage

Name	Type	Description
`code`	`DriverMessageCode`
`data`	`std::any`