GXF App C++ APIs

Arg

struct nvidia::gxf::ArgInfo

Holds type information of an Arg.

gxf_parameter_type_t type: The type of the Arg.

std::string type_name: The name of the Arg’s type.

int32_t rank: The rank of the Arg.

std::array<int32_t, ParameterInfo<int32_t>::kMaxRank> shape: The shape of the Arg.

struct nvidia::gxf::ArgOverride

A template struct for overriding ArgInfo for various Arg types.

static Expected<void> apply(ArgInfo &info)

Applies the ArgOverride to the given ArgInfo.

Parameters

ArgInfo& info – The ArgInfo to apply the override to.

Returns

Expected<void> Success or error code on failure

static ExpectedYAML::Node wrap(const T &value)

Wraps the given arg value in a YAML node.

Parameters

const T& value – The value to wrap.

Returns

An Expected with a YAML node on success, or an Unexpected with an error code on failure.

The following template specializations have been implemented for the ArgOverride struct in arg.hpp:

ArgOverride<T>

ArgOverride<Handle<T>>

ArgOverride<std::vector<T>>

ArgOverride<std::array<T,N>>

ArgOverride<ProxyComponent>

These specializations cover a wide range of parameter types, including scalar types, handles, arrays, vectors, and proxy components.

class nvidia::gxf::Arg

Argument interface to enable configuring parameters in GXF Components from the application layer. All parameter types from :cpp:enum::gxf_parameter_type_t enum is supported.

Arg(const std::string &key): Constructor for an argument with a given key.

template<typename T> Arg(const std::string &key, const T &value): Constructor for an argument with a given key and value.

Arg(const std::string &key, const char *value): Constructor for an argument with a given key and string literal value.

template<typename T> Arg(const std::string &key, const Handle<T> &value): Constructor for an argument with a given key and handle to a component as value.

Arg(const std::string &key, const ProxyComponent &value): Constructor for an argument with a given key and a proxy component.

template<typename T, typename = std::enable_if_t<!std::is_lvalue_reference<T>::value>> Arg(const std::string &key, T &&value): Constructor for an argument with a given key and rvalue reference to a value.

template<typename T, typename = std::enable_if_t<!std::is_lvalue_reference<T>::value>> Arg(const std::string &key, Handle<T> &&value): Constructor for an argument with a given key and rvalue reference to a handle to a component as value.

Arg(const std::string &key, ProxyComponent &&value): Constructor for an argument with a given key and rvalue reference to a proxy component.

template<typename T, typename = std::enable_if_t<!std::is_same_v<Arg, std::decay_t<T>>>> Arg &operator=(const T &value): Assignment operator for an argument with a given value.

template<typename T, typename = std::enable_if_t<!std::is_same_v<Arg, std::decay_t<T>>>> Arg &operator=(const Handle<T> &value): Assignment operator for an argument with a given handle to a component as value.

Arg &operator=(ProxyComponent &value): Assignment operator for an argument with a given proxy component.

template<typename T, typename = std::enable_if_t<!std::is_same_v<Arg, std::decay_t<T>> && !std::is_lvalue_reference<T>::value>> Arg &&operator=(T &&value): Move assignment operator for an argument with a given rvalue reference to a value.

template<typename T, typename = std::enable_if_t<!std::is_same_v<Arg, std::decay_t<Handle<T>>> && !std::is_lvalue_reference<Handle<T>>::value>> Arg &&operator=(Handle<T> &&value): Move assignment operator for an argument with a given rvalue reference to a handle to a component as value.

Arg &&operator=(ProxyComponent &&value): Move assignment operator for an argument with a given rvalue reference to a proxy component.

template<typename T, typename = std::enable_if_t<IsDefaultConstructible_v<T>>> T as() const: Method to retrieve the value of the argument as a given type.

const gxf_uid_t handle_uid() const: Method to retrieve the handle UID of the argument.

const gxf_tid_t handle_tid() const: Method to retrieve the handle TID of the argument.

const char *key() const: Method to retrieve the key of the argument.

const std::string arg_type_name() const: Method to retrieve the type name of the argument.

const ArgInfo arg_info() const: Method to retrieve the argument info of the argument.

const YAML::Node yaml_node() const: Method to retrieve the YAML node of the argument.

const int32_t rank() const: Method to retrieve the rank of the argument.

const std::array<int32_t, ParameterInfo<int32_t>::kMaxRank> shape() const: Method to retrieve the shape of the argument.

const gxf_parameter_type_t parameter_type() const: Method to retrieve the parameter type of the argument.

bool has_value() const: Method to retrieve the argument has a value assigned

std::any value() const: Method to retrieve the value of the argument in a std::any object

Arg Parse

template<typename T, typename First, typename ...Rest> std::vector<T> parseArgsOfType(const First &first, const Rest&... rest)

Parses the incoming parameter pack of arguments for objects of type T

Parameters: T – Type of parameter to be filtered from the parameter pack
Returns: std::vector<T> List of objects of type T

Expected<void> applyArg(Handle<Component> component, const Arg &arg)

Parameters

component – Handle to a valid component
arg – Arg to be applied on the component

Returns

Expected<void> Success or error code on failure

Expected<Arg> findArg(const std::vector<Arg> &args, const std::string &key, const gxf_parameter_type_t type)

Parameters

args – Input Arg list
key – Arg key to search
type – parameter type of the Arg

Returns

Expected<Arg> Arg object if found, error code on failure

Application

class nvidia::gxf::Application

A class representing an application for GXF. This class provides a convenient way to create and manage GXF applications imperatively. Users implement a virtual compose() api where individual building blocks of an application is constructed, configured and connected with each other.

Application(): Constructor for an application. This constructor initializes an application with no segments or entities.

~Application(): Destructor for an application. This destructor cleans up any resources that were allocated by the application.

Application(const Application&) = delete: Copy constructor for an application. This constructor is deleted to prevent copying of applications.

Application &operator=(const Application&) = delete: Copy assignment operator for an application. This operator is deleted to prevent copying of applications.

Application(Application&&) = delete: Move constructor for an application. This constructor is deleted to prevent moving applications.

Application &operator=(Application&&) = delete: Move assignment operator for an application. This operator is deleted to prevent moving applications.

virtual void compose(): A virtual function that is called to compose the application. This function is where the segments and entities of the application are created and configured.

Expected<void> setConfig(const std::string &file_path)

Function to set the configuration of the application. This function sets the configuration of the application by loading it from a file.

Parameters: file_path – Absolute path to the yaml config file for segments distributed execution
Returns: Expected<void> Success or error code on failure

Expected<void> setConfig(int argc, char **argv)

Function to set the configuration of the application. This function sets the configuration of the application by parsing it from command line arguments.

Parameters

argc – CLI argument count
argv – CLI argument array, the second is config file path for segments distributed execution

Returns

Expected<void> Success or error code on failure

template<typename SegmentT, typename = std::enable_if_t<!std::is_same_v<Segment, std::decay_t<SegmentT>>>> std::shared_ptr<SegmentT> createSegment(const char *name)

Function to create a segment in the application. This function creates a new segment in the application with the specified name. The graph for the segment will be composed() after creation. SegmentT is a valid type segment type.

Parameters: name – Name of the segment
Returns: Expected<void> Success or error code on failure

Expected<void> loadExtensionManifest(const char *manifest)

Function to load an extension manifest.

Parameters: manifest – path to manifest file with list of extensions
Returns: Expected<void> Success or error code on failure

Expected<void> connect(SegmentPtr source, SegmentPtr target, std::vector<SegmentPortPair> port_maps)

This function connects two segments by mapping their ports. It adds a UCX connection between two entities with many : many tx and rx Ucx Transmitter and Ucx Receiver components are added to the source and target entities in both of the segments.

Parameters

source – Segment with the entity transmitting the message
target – Segment with the entity receiving entity. A message available term is added along with the Ucx Receiver
port_maps – Segment port map with entity and queue name to be used for connection.

Returns

Expected<void> Success or error code on failure

gxf_result_t nvidia::gxf::Application::setSegmentSeverity(const char *name, gxf_severity_t severity)

Sets the severity level of the logs (corresponding to GXF_LOG_* logging macros) for a specific segment

Parameters

name – The name of the segment.
severity – The severity level.

Returns

A gxf_result_t indicating success or failure.

Expected<void> run()

A blocking api to run the graph. If the application contains multiple segments, each segment is launched asynchronously and this thread is blocked until each one of the segments have finished execution. If the graph contains multiple entities, then this thread is blocked until the graph execution is complete.

Returns: Expected<void> Success or error code on failure

Expected<void> runAsync()

A non blocking api call to run an application. If the application contains multiple segments, each segment is launched asynchronously.

Returns: Expected<void> Success or error code on failure

Expected<void> interrupt()

A non blocking api to stop all running running segments or entities.

Returns: Expected<void> Success or error code on failure

Expected<void> wait()

A blocking API to waits until the graph execution has completed

Returns: Expected<void> Success or error code on failure

template<typename ...Args> Expected<void> setWorker(const std::string &name, Args... args)

In-place add a GraphWorker Component into Application’s root context, in which case Application’s context should only hold and run GraphWorker or GraphDriver

Parameters

name – The name of the GraphWorker.
args – The parameter pack of arguments to pass to the GraphWorker constructor.

Returns

Expected<void> Success or error code on failure

template<typename ...Args> Expected<void> setDriver(const std::string &name, Args... args)

In-place add a GraphDriver Component into Application’s root context, in which case Application’s context should only hold and run GraphWorker or GraphDriver

Parameters

name – The name of the GraphDriver.
args – The parameter pack of arguments to pass to the GraphDriver constructor.

Returns

Expected<void> Success or error code on failure

template<typename T, typename ...Args> std::shared_ptr<T> create_app<T, Args...>(Args&&... args)

Function to create an application. This function creates a new application with the specified arguments. T is valid application type.

Returns: shared_ptr of the newly created application object

Segment

struct nvidia::gxf::PortPair

A entity - entity connection specified using tx and rx component names tx - transmitter component name rx - receiver component name The queue names should match the parameter keys of the codelet in the corresponding GraphEntity for a successful connection between the two graph entities.

SegmentPort source: The source SegmentPort in the connection.

SegmentPort target: The target SegmentPort in the connection.

PortPair(const SegmentPort &source, const SegmentPort &target): Constructor for a PortPair with the given source and target SegmentPorts.

SegmentPort getSource() const: Returns the source SegmentPort in the connection.

SegmentPort getTarget() const: Returns the target SegmentPort in the connection.

struct nvidia::gxf::SegmentPort

An open port in an segment is specified using entity and queue component names. SegmentPort name is in the format “<Entity Name>.<Queue Name>”

Entity Name - name of a graph entity created in the segment Queue Name - tx or rx component name which should match the parameter keys of the codelet in the corresponding GraphEntity for a successful connection

std::string name: The name of the SegmentPort, which is a concatenation of the entity name and queue name.

std::string entity_name: The name of the entity associated with the SegmentPort.

std::string queue_name: The name of the queue (tx or rx) associated with the SegmentPort.

struct SegmentPortPair

A segment - segment connection specified using the segment port info SegmentPort name is in the format “<Entity Name>.<Queue Name>” where the queues are tx or rx components. tx - SegmentPort in the source segment rx - SegmentPort in the sink segment The queue names should match the parameter keys of the codelet in the corresponding GraphEntity for a successful connection between the two segments

SegmentPort source: The source SegmentPort in the connection.

SegmentPort target: The target SegmentPort in the connection.

SegmentPortPair(const SegmentPort &source, const SegmentPort &target): Constructor for a SegmentPortPair with the given source and target SegmentPorts.

SegmentPort getSource() const: Returns the source SegmentPort in the connection.

SegmentPort getTarget() const: Returns the target SegmentPort in the connection.

enum nvidia::gxf::SchedulerType

Enum representing the type of scheduler to be used in the application. This enum is primarily used as an input to setScheduler api.

enumerator SchedulerType::kGreedy: A single threaded scheduler that assigns resources to entities in a greedy manner, without considering fairness or priorities.

enumerator SchedulerType::kMultiThread: A scheduler that uses multiple threads to execute entities concurrently.

enumerator SchedulerType::KEventBased: A scheduler that uses an event-based model to schedule entities.

SchedulerType Enumeration Constants

constexpr const SchedulerType Greedy = SchedulerType::kGreedy

constexpr const SchedulerType MultiThread = SchedulerType::kMultiThread

constexpr const SchedulerType EventBased = SchedulerType::KEventBased

class nvidia::gxf::Segment

Segment is a group of graph entities created in a single GXF runtime context. A segment will have its own scheduler. Graph entities in a segment are connected with each other via double buffer transmitter and receiver components. A segment can also be connected other segments via ucx transmitters and receivers. Segments are created and managed by the :cpp:class::nvidia::gxf::Application class.

Segment(): Default constructor.

virtual ~Segment(): Default Destructor.

Segment(Segment&&) = default: Default move constructor.

Segment &operator=(Segment&&) = default: Default move assignment operator.

void compose(): A virtual function that is called to compose the segment. This function is where the entities are created, connected and configured.

template<typename CodeletT, typename ...Args> GraphEntityPtr makeEntity(const char *name, Args... args)

Creates a graph entity with a codelet of type CodeletT along with a parameter pack of Arg & ProxyComponent. The codelet component will be used to auto populate connection queues and their corresponding scheduling terms. Args can be used to specify a variable list of components to be created along with the codelet in the graph entity. Args can also be used to specify a variable list of Arg type to update any parameter values of the codelet

Parameters

const char* name – The name of the graph entity.
Args... args – A parameter pack of Arg or ProxyComponent objects.

Returns

A newly created graph entity object with the requested components.

template<typename ...Args> GraphEntityPtr makeEntity(const char *name, Args... args)

Creates a graph entity without a codelet and with a parameter pack of Arg & ProxyComponent. Args can be used to specify a variable list of components to be created along with the graph entity.

Parameters

const char* name – The name of the graph entity.
Args... args – A parameter pack of Arg or ProxyComponent objects.

Returns

A newly created graph entity object with the requested components.

template<typename T, typename ...Args> ProxyComponent makeTerm(const char *name, Args... args)

Creates a scheduling term of requested type T and applies parameter component values from a parameter pack of arguments. This api does not create the requested gxf native component. A Proxy component value is returned which has the type info and arg list needed to create this scheduling term. createFromProxy() api is used to create this component given any specific GraphEntity. Type T must be derived from nvidia::gxf::SchedulingTerm type. Args is a parameter pack of arguments / parameter values to be applied to the component.

Parameters: const char* name – The name of the component.
Returns: A ProxyComponent object.

template<typename T, typename ...Args> ProxyComponent makeResource(const char *name, Args... args)

Creates a resource of requested type and applies parameter component values from a parameter pack of arguments. This api does not create the requested gxf native component. A Proxy component value is returned which has the type info and arg list needed to create this resource. createFromProxy() api is used to create this component given any specific GraphEntity. Type T must be derived from nvidia::gxf::ResourceBase type. Args is a parameter pack of arguments / parameter values to be applied to the component.

Parameters: const char* name – The name of the component.
Returns: A ProxyComponent object.

template<typename ClockT, typename ...Args> Handle<Clock> setClock(const char *name, Args... args)

Adds a clock component to the segment and applies parameter component values from a parameter pack of arguments. Type T must be derived from nvidia::gxf::Clock type. Args is a parameter pack of arguments / parameter values to be applied to the component.

Parameters: const char* name – The name of the clock component.
Returns: Handle<Clock> Handle to newly created clock component. Null handle if component was not created.

template<SchedulerType schedulerType, typename ...Args> Handle<Scheduler> setScheduler(Args... args)

Adds a scheduler component to the segment and applies parameter component values from a parameter pack of arguments. Type T must be derived from nvidia::gxf::Scheduler type. Args is a parameter pack of arguments / parameter values to be applied to the component.

Returns: Handle<Scheduler> Handle to newly created scheduler component. Null handle if component was not created.

Handle<Scheduler> setScheduler(const SchedulerType &scheduler, std::vector<Arg> arg_list = {})

Add a scheduler to the segment based on the input SchedulerType enum. If the segment contains a clock component, the same component will be reused to configure the scheduler. If no clock components are found in the segment, a new RealTimeClock component will be added to the segment.

Parameters

const SchedulerType& scheduler – Type of the scheduler to be added. One of kGreedy, kMultithread or kEventBased.
std::vector<Arg> arg_list – A vector of Arg to apply to the component.

Returns

A Handle to the newly created scheduler component.

Expected<void> connect(GraphEntityPtr &source, GraphEntityPtr &target)

Adds a double buffer queue based connection between two entities with 1:1 tx and rx connectivity.

Parameters

GraphEntityPtr& source – The origin graph entity for the connection.
GraphEntityPtr& target – The destination graph entity for the connection.

Returns

Expected<void> Success or error code on failure

Expected<void> connect(GraphEntityPtr &source, GraphEntityPtr &target, PortPair port_pair)

Adds a single double buffer queue based connection between two entities with a port pair specified.

Parameters

GraphEntityPtr& source – The origin graph entity for the connection.
GraphEntityPtr& target – The destination graph entity for the connection.
PortPair port_pair – The port pair containing information of the connection to be created.

Returns

Expected<void> Success or error code on failure

Expected<void> nvidia::gxf::Segment::connect(GraphEntityPtr &source, GraphEntityPtr &target, std::vector<PortPair> port_pairs)

Adds multiple double buffer queue based connections between two entities with many : many tx and rx. Connections between two graph entities are created sequentially.

Parameters

GraphEntityPtr& source – The origin graph entity for the connection.
GraphEntityPtr& target – The destination graph entity for the connection.
std::vector<PortPair> port_pairs – The list of port pairs containing information of the connections to be created.

Returns

Expected<void> Success or error code on failure

const char *name() const

Fetch the name of the segment.

Returns: The name of the segment as a const char*.

gxf_context_t context()

Fetch the context of a segment.

Returns: The context of the segment as a gxf_context_t.

Expected<void> activate()

Activates all the graph entities in the segment.

Returns: Expected<void> Success or error code on failure

Expected<void> deactivate()

Deactivates all the graph entities in the segment.

Returns: Expected<void> Success or error code on failure

Expected<void> run()

A blocking api to run the segment. This thread is blocked (sleeping) until the segment execution is complete.

Returns: Expected<void> Success or error code on failure

Expected<void> runAsync()

A non blocking api to execute a segment. API returns immediately after starting the segment execution. wait() can be used to wait until execution has finished.

Returns: Expected<void> Success or error code on failure

Expected<void> interrupt()

A non blocking api to stop a previously running segment. Segment is not guaranteed to have stopped when this api returns. wait() can be used to wait until the execution has finished.

Returns: Expected<void> Success or error code on failure

Expected<void> wait()

A blocking API to wait until the segment execution has completed.

Returns: Expected<void> Success or error code on failure

gxf_result_t setSeverity(gxf_severity_t severity)

Sets the severity level of the logs (corresponding to GXF_LOG* logging macros) for a segment

Parameters: gxf_severity_t severity – A valid severity level as defined in gxf_severity_t. Logs corresponding to any level <= severity will be logged.
Returns: gxf_result_t On success the function returns GXF_SUCCESS.

Expected<void> saveToFile(const char *filepath)

Saves the segment information containing entities, components and their corresponding parameter values in a yaml representation.

Parameters: const char* filepath – path to save the resulting graph yaml file
Returns: Expected<void> Success or error code on failure

Expected<void> loadParameterFile(const char *filepath)

Loads parameters for graph entities composed in the segment / application. YAML file follows the GXF graph specification.

Parameters: const char* filepath – path to a valid parameters file
Returns: Expected<void> Success or error code on failure

Expected<void> createNetworkContext()

Creates a Network Context in the segment which can be used by UCX Connections added in the application. A new graph entity with the name “NetworkContext” will be added to the segment context with a UcxContext component and a corresponding entity and component serializers

Returns: Expected<void> Success or error code on failure

Handle<Component> createFromProxy(ProxyComponent &component, GraphEntityPtr &entity)

Creates a component in graph entity based on the type information from the ProxyComponent

Parameters

ProxyComponent& component – A proxy component object
GraphEntityPtr& entity – A pointer to graph entity to be used for creating the component

Returns

Handle<Component> Handle to newly created component or null handle on failure

Expected<void> setup(gxf_context_t segment_context, const char *name, std::shared_ptr<DefaultExtension> runtime_ext)

This function is expected to be called by the application layer to assign a context to the segment and a runtime extension for on: the fly registration of components

Parameters

gxf_context_t segment_context – A valid GXF context to be assigned to the segment
const char* name – A valid name for the segment
std::shared_ptr<DefaultExtension> runtime_ext – Pointer to a GXF extension which can be used to register any components at runtime

Returns

Expected<void> Success or error code on failure

Expected<void> setName(const char *name)

Sets the name of the segment

Parameters: const char* name – A valid name for the segment
Returns: Expected<void> Success or error code on failure

Graph Entity

class nvidia::gxf::GraphEntity

A wrapper over nvidia::gxf::Entity to manage a programmable graph entity.

Expected<void> nvidia::gxf::GraphEntity::setup(gxf_context_t context, const char *name)

Creates a programmable entity with the runtime context and sets its name.

Parameters

context – A valid GXF context

name – Name of the graph entity

Returns

Expected<void> Success or error code on failure

template<typename T, typename ...Args>
Handle<T> nvidia::gxf::GraphEntity::add(const char *name = nullptr, Args... args)

Creates a generic component of type T and sets the parameter values from Args pack of args. Transmitters, Receivers, Clocks and Scheduling Term component names have to be unique. Type T must be derived from nvidia::gxf::Component.

Parameters

name – Name of the component

args – Args must be of type Arg

Returns

Handle<T> Handle to newly created component. Null handle if component was not created.

template<typename T>
Handle<T> nvidia::gxf::GraphEntity::add(const char *name, std::vector<Arg> arg_list)

Creates a generic component of type T and sets the parameter values from arg_list. Transmitters, Receivers, Clocks and Scheduling Term component names have to be unique. Type T must be derived from nvidia::gxf::Component

Parameters

name – Name of the component

arg_list – vector of Arg used for initializing the component’s parameters.

Returns

Handle<T> Handle to newly created component. Null handle if component was not created.

template<typename T, size_t N = kMaxComponents>
FixedVector<Handle<T>, N> nvidia::gxf::GraphEntity::findAll() const

Finds all components of given type. Returns an empty vector if component is not found. Type T is a type of component to search for.

Parameters

N – Maximum number of components to return

Returns

FixedVector<Handle<T>, N> List of handles to components of the same type

template<typename T>
Handle<T> nvidia::gxf::GraphEntity::get(const char *name = nullptr) const

Gets a component by type and name. Returns null handle if no such component. Type T is a type of component to search for.

Parameters

name – Name of the component to look for

Returns

Handle<T> Handle to component, if component is found. Null handle if no such component.

template<typename T>
Expected<Handle<T>> nvidia::gxf::GraphEntity::try_get(const char *name = nullptr) const

Get a component by type and name. Returns an Unexpected in the case that the component is not found. Unlike get no error is logged if a component is not found. Type T is a type of component to search for.

Parameters

name – Name of the component to look for

Returns

Expected<Handle<Component>> Handle to the component, if component is found. Otherwise, an Unexpected is returned.

Handle<Component> nvidia::gxf::GraphEntity::get(const char *type_name, const char *name = nullptr) const

Gets a component by type and name. Returns null handle if no such component.

Parameters

type_name – Fully qualified C++ type name of the component to search for

name – Name of the component to look for

Returns

Handle<Component> Handle to component, if component is found. Null handle if no such component.

template<typename T>
Expected<Handle<T>> nvidia::gxf::GraphEntity::try_get(const char *type_name, const char *name = nullptr) const

Get a component by type and name. Returns an Unexpected in the case that the component is not found. Unlike get no error is logged if a component is not found. Type T is a type of component to search for.

Parameters

type_name – Fully qualified C++ type name of the component to search for

name – Name of the component to look for

Returns

Expected<Handle<Component>> Handle to the component, if component is found. Otherwise, an Unexpected is returned.

template<typename T, typename ...Args>
Handle<T> nvidia::gxf::GraphEntity::addCodelet(const char *name = nullptr, Args... args)

Adds a codelet of type T with given name and sets the parameter values from Args. T must be derived from nvidia::gxf::Codelet.

Parameters

name – Name of the codelet

args – Args must be of type Arg

Returns

Handle<T> Handle to newly created codelet. Null handle if component was not created.

Handle<Codelet> nvidia::gxf::GraphEntity::addCodelet(const char *type_name, const char *name = nullptr, const std::vector<Arg> &arg_list = {})

Adds a codelet with a given C++ type name.

Parameters

type_name – The fully qualified C++ type name of the codelet component

name – Name of the codelet

arg_list – Arguments for the codelet

Returns

Handle<Codelet> Handle to newly created codelet component. Null handle if component was not created.

Handle<Component> nvidia::gxf::GraphEntity::addComponent(const char *type_name, const char *name = nullptr, const std::vector<Arg> &arg_list = {})

Adds a component with a given C++ type name.

Parameters

type_name – The fully qualified C++ type name of the component

name – Name of the component

arg_list – Arguments for the component

Returns

Handle<Component> Handle to newly created component. Null handle if component was not created.

template<typename T, typename ...Args>
Handle<T> nvidia::gxf::GraphEntity::addClock(const char *name = nullptr, Args... args)

Adds a component of Clock type T and sets the parameter values from Args. T must be derived from nvidia::gxf::Clock

Parameters

name – Name of the clock

args – Args must be of type Arg

Returns

Handle<T> Handle to newly created clock component. Null handle if component was not created.

Handle<Clock> nvidia::gxf::GraphEntity::addClock(const char *type_name, const char *name = nullptr, const std::vector<Arg> &arg_list = {})

Adds a clock component with a given C++ type name.

Parameters

type_name – The fully qualified C++ type name of the clock

name – Name of the clock

arg_list – Arguments for the clock component

Returns

Handle<Clock> Handle to newly created clock

Handle<Clock> nvidia::gxf::GraphEntity::getClock(const char *name = nullptr)

Get the Clock object from a graph entity. Returns null handle if no clock component has been created yet. Returns the first clock if no component name is provided. If name is provided, exact instance of the clock is returned if found else a Null handle.

Parameters

name – Name of the clock component to lookup

Returns

Handle<Clock>

template<typename T, typename ...Args>
Handle<T> nvidia::gxf::GraphEntity::addSchedulingTerm(const char *name = nullptr, Args... args)

Adds a component of SchedulingTerm type T and sets the parameter values from Args. T must be derived from nvidia::gxf::SchedulingTerm.

Parameters

name – name of the scheduling term

args – Args must be of type Arg

Returns

Handle<T> Handle to newly created scheduling term component

Handle<SchedulingTerm> nvidia::gxf::GraphEntity::addSchedulingTerm(const char *type_name, const char *name = nullptr, const std::vector<Arg> &arg_list = {})

Adds a scheduling term component with a given C++ type name.

Parameters

type_name – The fully qualified C++ type name of the scheduling term

name – Name of the scheduling term

arg_list – Arguments for the scheduling term component

Returns

Handle<SchedulingTerm> Handle to newly created scheduling term

template<typename T, typename ...Args>
Handle<T> nvidia::gxf::GraphEntity::addTransmitter(const char *name, bool omit_term = false, Args... args)

Adds a component of Transmitter type T with name and sets the parameter values from Args.

Name of the transmitter should match the parameter name of the underlying codelet. The name of the transmitter component is updated based on the parameter rank info. A Downstream receptive scheduling term is also added to monitor the transmitter component.

If codelet parameter is a scalar, name of the transmitter is also same as the parameter key. Parameter<Handle<Transmitter>> | name - “key”

If codelet parameter is a vector/array, the name of the transmitter component is key_%d where ‘d’ is the index of this transmitter in the codelet parameter. Parameter<Vector<Handle<Transmitter>> | name - “key_0”, “key_1”, “key_2”

Type T must be derived from nvidia::gxf::Transmitter.

Parameters

name – Name of the transmitter component

omit_term – Boolean flag controlling whether or not a default downstream receptive scheduling term is added. If true, no scheduling term is added.

args – Args must be of type Arg

Returns

Handle<T> Handle to newly created transmitter component

Handle<Transmitter> nvidia::gxf::GraphEntity::addTransmitter(const char *type_name, const char *name = nullptr, const std::vector<Arg> &arg_list = {}, bool omit_term = false)

Adds a component of Transmitter of the corresponding type_name.

Name of the transmitter should match the parameter name of the underlying codelet. The name of the transmitter component is updated based on the parameter rank info. A Downstream receptive scheduling term is also added to monitor the transmitter component.

If codelet parameter is a scalar, name of the transmitter is also same as the parameter key. Parameter<Handle<Transmitter>> | name - “key”

If codelet parameter is a vector/array, the name of the transmitter component is key_%d where ‘d’ is the index of this transmitter in the codelet parameter. Parameter<Vector<Handle<Transmitter>> | name - “key_0”, “key_1”, “key_2”

Parameters

type_name – The fully qualified C++ type name of the transmitter component

name – Name of the transmitter component

arg_list – Arguments for the transmitter component

omit_term – Boolean flag controlling whether or not a default downstream receptive scheduling term is added. If true, no scheduling term is added.

Returns

Handle<Transmitter> Handle to newly created transmitter component

Handle<Transmitter> nvidia::gxf::GraphEntity::getTransmitter(const char *name)

Receiver component lookup using name

Parameters

name – name of a transmitter component which has been previously created

Returns

Handle<Transmitter> Handle to transmitter component if found, Null handle if no such component.

template<typename T, typename ...Args>
Handle<T> nvidia::gxf::GraphEntity::addReceiver(const char *name, bool omit_term = false, Args... args)

Adds a component of Receiver type T with name and sets the parameter values from Args.

Name of the receiver should match the parameter name of the underlying codelet. The name of the receiver component is updated based on the parameter rank info. A Message available scheduling term is also added to monitor the receiver component.

If codelet parameter is a scalar, name of the receiver is also same as the parameter key. Parameter<Handle<Receiver>> | name - “key”

If codelet parameter is a vector/array, the name of the receiver component is key_%d where ‘d’ is the index of this receiver in the codelet parameter. Parameter<Vector<Handle<Receiver>> | name - “

Type T must be derived from nvidia::gxf::Receiver.

Parameters

name – Name of the receiver component.

omit_term – Boolean flag controlling whether or not a default message available scheduling term is added. If true, no scheduling term is added.

args – Args must be of type Arg

Returns

Handle<T> Handle to newly created receiver component

Handle<Receiver> addReceiver(const char *type_name, const char *name = nullptr, const std::vector<Arg> &arg_list = {}, bool omit_term = false)

Adds a component of Receiver of the corresponding type_name.

Name of the receiver should match the parameter name of the underlying codelet. The name of the receiver component is updated based on the parameter rank info.

If codelet parameter is a scalar, name of the receiver is also same as the parameter key Parameter<Handle<Receiver>> | name - “key”

If codelet parameter is a vector/array, the name of the receiver component is key_%d where ‘d’ is the index of this receiver in the codelet parameter. Parameter<Vector<Handle<Receiver>> | name - “key_0”, “key_1”, “key_2”

Parameters

type_name – The fully qualified C++ type name of the receiver.

name – Name of the receiver. Default is nullptr.

arg_list – Arguments for the receiver component. Default is an empty vector.

omit_term – Boolean flag controlling whether or not a default message available scheduling term is added. If true, no scheduling term is added.

Returns

Handle<Receiver> Handle to newly created receiver component.

Handle<Receiver> getReceiver(const char *name)

Receiver component lookup using name

Parameters

name – name of a receiver component which has been previously created

Returns

Handle to the receiver component if found, Null handle if no such component.

Expected<void> configTransmitter(const char *name, uint64_t capacity, uint64_t policy, uint64_t min_size)

Update the capacity and min_size parameter of a transmitter and its corresponding downstream receptive scheduling term

Parameters

name – Name of the transmitter component

capacity – capacity of the transmitter to be set

policy – policy of the transmitter to be set

min_size – min size of the downstream receptive term to be set

Returns

Expected<void> Success or error code on failure

Expected<void> configReceiver(const char *name, uint64_t capacity, uint64_t policy, uint64_t min_size)

Update the capacity and min_size parameter of a receiver and its corresponding message available scheduling term

Parameters

name – Name of the receiver component

capacity – capacity of the receiver to be set

policy – policy of the receiver to be set

min_size – min size of the message available term to be set

Returns

Expected<void> Success or error code on failure

Expected<void> activate()

Activate the GraphEntity

Returns

Expected<void> Success or error code on failure

Expected<void> deactivate()

Deactivate the GraphEntity

Returns

Expected<void> Success or error code on failure

gxf_context_t context() const

Get the context of the GraphEntity

Returns

gxf_context_t The context of the GraphEntity

gxf_uid_t eid() const

Get the entity ID of the GraphEntity

Returns

gxf_uid_t The entity ID of the GraphEntity

bool is_null() const

Check if the GraphEntity is null

Returns

bool True if the GraphEntity is null, false otherwise

Handle<Codelet> get_codelet()

Get the Codelet associated with the GraphEntity

Returns

Handle<Codelet> The Codelet associated with the GraphEntity, or Null handle if none is set.

const char *name() const

Get the name of the entity or an empty string if no name has been given to the entity.

Returns

const char* A pointer to the name of the entity.

Expected<std::string> formatTxName(const char *tx_name)

Given a name for a transmitter to be connected to the codelet, return a formatted string back which can be used for a new transmitter component creation. If the codelet’s tx parameter is a scalar, the tx name is the same as the parameter key. If the codelet’s tx parameter is a vector, the tx name would be “key_0”, “key_1” …

Parameters

tx_name – name of transmitter component

Returns

Expected<std::string> formatted name of transmitter component

Expected<std::string> formatRxName(const char *rx_name)

Given a name for a receiver to be connected to the codelet, return a formatted string back which can be used for a new receiver component creation. If the codelet’s rx parameter is a scalar, the rx name is the same as the parameter key. If the codelet’s rx parameter is a vector, the rx name would be “key_0”, “key_1” …

Parameters

rx_name – name of receiver component

Returns

Expected<std::string> formatted name of receiver component

Expected<void> updatePort(const char *key, std::string value)

Update the port with the given key and value.

Parameters

key – The key of the port to update

value – The new value of the port

Returns

Expected<void> Success or error code on failure