holoscan::gxf::GXFExtensionManager

Beta

Class to manage GXF extensions.

This class is a helper class to manage GXF extensions.

Since GXF API doesn’t provide a way to ignore duplicate extensions, this class is used to manage the extensions, prevent duplicate extensions from being loaded, and unload the extension handlers when the class is destroyed.

Example:

#include <holoscan/gxf/gxf_extension_manager.hpp>

Example

#include <yaml-cpp/yaml.h>
#include <holoscan/core/gxf/gxf_extension_manager.hpp>
...
holoscan::gxf::GXFExtensionManager extension_manager(reinterpret_cast<gxf_context_t>(context));
// Load extensions from a file
for (const auto& extension_filename : extension_filenames) {
  extension_manager.load_extension(extension_filename);
}
// Load extensions from a yaml node (YAML::Node object)
for (const auto& manifest_filename : manifest_filenames) {
  auto node = YAML::LoadFile(manifest_filename);
  extension_manager.load_extensions_from_yaml(node);
}

Inherits from: holoscan::ExtensionManager (public)

Constructors

GXFExtensionManager

holoscan::gxf::GXFExtensionManager::GXFExtensionManager(holoscan::gxf::GXFExtensionManager::GXFExtensionManager(
    gxf_context_t context
)

Construct a new GXFExtensionManager object.

Parameters

context

gxf_context_t

The GXF context

Destructor

~GXFExtensionManager

holoscan::gxf::GXFExtensionManager::~GXFExtensionManager() overrideholoscan::gxf::GXFExtensionManager::~GXFExtensionManager() override

Destroy the GXFExtensionManager object.

This method closes all the extension handles that are loaded by this class. Note that the shared library is opened with RTLD_NODELETE flag, so the library is not unloaded when the handle is closed.

Methods

reset_context

Reset the extension manager with the context (1)

Reset the extension manager with the context (2)

void holoscan::gxf::GXFExtensionManager::reset_context(
    gxf_context_t context
) override

Reset the extension manager with the context.

Parameters

context

gxf_context_t

The GXF context.

refresh

void holoscan::gxf::GXFExtensionManager::refresh() override

Refresh the extension list.

Based on the current GXF context, it gets the list of extensions and stores the type IDs of the extensions so that duplicate extensions can be ignored.

Also loads extensions that were previously loaded & cached.

load_extension

Load an extension

Load an extension from a pointer

virtual

bool holoscan::gxf::GXFExtensionManager::load_extension(
    const std::string &file_name,
    bool no_error_message = false,
    const std::string &search_path_envs = "HOLOSCAN_LIB_PATH"
) override

Load an extension.

This method loads an extension and stores the extension handler so that it can be unloaded when the class is destroyed.

Returns: true if the extension is loaded successfully, false otherwise.

Parameters

file_name

const std::string &

The file name of the extension (e.g. libgxf_std.so).

no_error_message

boolDefaults to false

If true, no error message will be printed if the extension is not found.

search_path_envs

const std::string &Defaults to "HOLOSCAN_LIB_PATH"

The environment variable names that contains the search paths for the extension. The environment variable names are separated by a comma (,). (default: “HOLOSCAN_LIB_PATH”).

load_extensions_from_yaml

bool holoscan::gxf::GXFExtensionManager::load_extensions_from_yaml(
    const YAML::Node &node,
    bool no_error_message = false,
    const std::string &search_path_envs = "HOLOSCAN_LIB_PATH",
    const std::string &key = "extensions"
) override

Load extensions from a yaml file.

The yaml file should contain a list of extension file names under the key “extensions”.

For example:

Returns: true if the extension is loaded successfully, false otherwise.

Parameters

node

const YAML::Node &

The yaml node.

no_error_message

boolDefaults to false

If true, no error message will be printed if the extension is not found.

search_path_envs

const std::string &Defaults to "HOLOSCAN_LIB_PATH"

The environment variable names that contains the search paths for the extension. The environment variable names are separated by a comma (,). (default: “HOLOSCAN_LIB_PATH”).

key

const std::string &Defaults to "extensions"

The key in the yaml node that contains the extension file names (default: “extensions”).

Example

extensions:
- /path/to/extension1.so
- /path/to/extension2.so
- /path/to/extension3.so

is_extension_loaded

bool holoscan::gxf::GXFExtensionManager::is_extension_loaded(
    gxf_tid_t tid
)

Check if the extension is loaded.

Returns: true if the extension is loaded. false otherwise.

Parameters

tid

gxf_tid_t

The type ID of the extension.

open_extension_library

void * holoscan::gxf::GXFExtensionManager::open_extension_library(
    const std::string &file_path
)

Loads a dynamic library containing a GXF extension.

Uses dlopen() to load the specified extension library and returns its handle. If the extension has already been loaded, returns the existing handle from cache instead of loading it again.

Returns: Handle to the loaded dynamic library.

Parameters

file_path

const std::string &

Path to the extension library file (e.g., “libgxf_std.so”).

Static methods

tokenize

static std::vector<std::string> holoscan::gxf::GXFExtensionManager::tokenize(
    const std::string &str,
    const std::string &delimiters
)

Tokenize a string.

Returns: The vector of tokens.

Parameters

str

const std::string &

The string to tokenize.

delimiters

const std::string &

The delimiters.

Member variables

Name	Type	Description
`extension_tid_list_`	`gxf_tid_t`	Storage for the extension TIDs.
`runtime_info_`	`gxf_runtime_info`	request/response structure for the runtime info
`extension_tids_`	`std::set< gxf_tid_t >`	Set of unique extension type IDs that have been registered.
`loaded_extension_tids_map_`	`std::map< gxf_tid_t, nvidia::gxf::Extension * >`	Mapping from extension type IDs to their corresponding Extension pointers.
`loaded_extensions_`	`std::vector< std::pair< gxf_tid_t, nvidia::gxf::Extension * > >`	Sequential record of loaded extensions preserving the order they were loaded.
`extension_handles_map_`	`std::map< std::string, void * >`	Cache mapping extension file names to their dynamically loaded library handles.
`context_`	`void *`	The context.