GXF Core C APIs

Create context

gxf_result_t GxfContextCreate(gxf_context_t* context);

Creates a new GXF context

A GXF context is required for all almost all GXF operations. The context must be destroyed with ‘GxfContextDestroy’. Multiple contexts can be created in the same process, however they can not communicate with each other.

Create a context from a shared context

gxf_result_t GxfContextCreate1(gxf_context_t shared, gxf_context_t* context);

Creates a new runtime context from shared context.

A shared runtime context is used for sharing entities between graphs running within the same process.

Destroy context

gxf_result_t GxfContextDestroy(gxf_context_t context);

Destroys a GXF context

Every GXF context must be destroyed by calling this function. The context must have been previously created with ‘GxfContextCreate’. This will also destroy all entities and components which were created as part of the context.

Load Extensions from a file

gxf_result_t GxfLoadExtension(gxf_context_t context, const char* filename);

Loads extension in the given context from file.

This function will be deprecated.

Load Extension libraries

gxf_result_t GxfLoadExtensions(gxf_context_t context, const GxfLoadExtensionsInfo* info);

Loads GXF extension libraries

Loads one or more extensions either directly by their filename or indirectly by loading manifest files. Before a component can be added to a GXF entity the GXF extension shared library providing the component must be loaded. An extensions must only be loaded once.

To simplify loading multiple extensions at once the developer can create a manifest file which lists all extensions he needs. This function will then load all extensions listed in the manifest file. Multiple manifest may be loaded, however each extensions may still be loaded only a single time.

A manifest file is a YAML file with a single top-level entry ‘extensions’ followed by a list of filenames of GXF extension shared libraries.

Example: —– START OF FILE —– extensions: - gxf/std/libgxf_std.so - gxf/npp/libgxf_npp.so —– END OF FILE —–

gxf_result_t GxfLoadExtensionManifest(gxf_context_t context, const char* manifest_filename);

Loads extensions from manifest file.

This function will be deprecated.

Load Metadata files

gxf_result_t GxfLoadExtensionMetadataFiles(gxf_context_t context, const char* const* filenames, uint32_t count);

Loads an extension registration metadata file

Reads a metadata file of the contents of an extension used for registration. These metadata files can be used to resolve typename and TID’s of components for other extensions which depend on them. Metadata files do not contain the actual implementation of the extension and must be loaded only to run the extension query API’s on extension libraries which have the actual implementation and only depend on the metadata for type resolution.

If some components of extension B depend on some components in extension A: - Load metadata file for extension A - Load extension library for extension B using ‘GxfLoadExtensions’ - Run extension query api’s on extension B and it’s components.

Register component

gxf_result_t GxfRegisterComponent(gxf_context_t context, gxf_tid_t tid, const char* name, const char* base_name);

Registers a component with a GXF extension

A GXF extension need to register all of its components in the extension factory function. For convenience the helper macros in gxf/std/extension_factory_helper.hpp can be used.

The developer must choose a unique GXF tid with two random 64-bit integers. The developer must ensure that every GXF component has a unique tid. The name of the component must be the fully qualified C++ type name of the component. A component may only have a single base class and that base class must be specified with its fully qualified C++ type name as the parameter ‘base_name’.

ref: gxf/std/extension_factory_helper.hpp ref: core/type_name.hpp

Loads a list of entities from YAML file

gxf_result_t GxfGraphLoadFile(gxf_context_t context, const char* filename, const char* parameters_override[], const uint32_t num_overrides);

Set the root folder for searching YAML files during loading

gxf_result_t GxfGraphSetRootPath(gxf_context_t context, const char* path);

Loads a list of entities from YAML text

gxf_result_t GxfGraphParseString(gxf_context_t context, const char* tex, const char* parameters_override[], const uint32_t num_overrides);

Activate all system components

gxf_result_t GxfGraphActivate(gxf_context_t context);

Deactivate all System components

gxf_result_t GxfGraphDeactivate(gxf_context_t context);

Starts the execution of the graph asynchronously

gxf_result_t GxfGraphRunAsync(gxf_context_t context);

Interrupt the execution of the graph

gxf_result_t GxfGraphInterrupt(gxf_context_t context);

Waits for the graph to complete execution

gxf_result_t GxfGraphWait(gxf_context_t context);

Runs all System components and waits for their completion

gxf_result_t GxfGraphRun(gxf_context_t context);

Create an entity

gxf_result_t GxfEntityCreate(gxf_context_t context, gxf_uid_t* eid);

Creates a new entity and updates the eid to the unique identifier of the newly created entity.

This method will be deprecated.

gxf_result_t GxfCreateEntity((gxf_context_t context, const GxfEntityCreateInfo* info, gxf_uid_t* eid);

Create a new GXF entity.

Entities are light-weight containers to hold components and form the basic building blocks of a GXF application. Entities are created when a GXF file is loaded, or they can be created manually using this function. Entities created with this function must be destroyed using ‘GxfEntityDestroy’. After the entity was created components can be added to it with ‘GxfComponentAdd’. To start execution of codelets on an entity the entity needs to be activated first. This can happen automatically using ‘GXF_ENTITY_CREATE_PROGRAM_BIT’ or manually using ‘GxfEntityActivate’.

Activate an entity

gxf_result_t GxfEntityActivate(gxf_context_t context, gxf_uid_t eid);

Activates a previously created and inactive entity

Activating an entity generally marks the official start of its lifetime and has multiple implications: - If mandatory parameters, i.e. parameter which do not have the flag “optional”, are not set the operation will fail.

• All components on the entity are initialized.

• All codelets on the entity are scheduled for execution. The scheduler will start calling start, tick and stop functions as specified by scheduling terms.

• After activation trying to change a dynamic parameters will result in a failure.

• Adding or removing components of an entity after activation will result in a failure.

  parameter: context A valid GXF context

  parameter: eid UID of a valid entity

  returns: GXF error code

Deactivate an entity

gxf_result_t GxfEntityDeactivate(gxf_context_t context, gxf_uid_t eid);

Deactivates a previously activated entity

Deactivating an entity generally marks the official end of its lifetime and has multiple implications:

• All codelets are removed from the schedule. Already running entities are run to completion.

• All components on the entity are deinitialized.

• Components can be added or removed again once the entity was deactivated.

• Mandatory and non-dynamic parameters can be changed again.

Note: In case that the entity is currently executing this function will wait and block until

the current execution is finished.

parameter: context A valid GXF context

parameter: eid UID of a valid entity

returns: GXF error code

Destroy an entity

gxf_result_t GxfEntityDestroy(gxf_context_t context, gxf_uid_t eid);

Destroys a previously created entity

Destroys an entity immediately. The entity is destroyed even if the reference count has not yet reached 0. If the entity is active it is deactivated first.

Note: This function can block for the same reasons as ‘GxfEntityDeactivate’.

Find an entity

gxf_result_t GxfEntityFind(gxf_context_t context, const char* name, gxf_uid_t* eid);

Finds an entity by its name

Find all entities

gxf_result_t GxfEntityFindAll(gxf_context_t context, uint64_t* num_entities, gxf_uid_t* entities);

Finds all entities in the current application

Finds and returns all entity ids for the current application. If more than max_entities exist only max_entities will be returned. The order and selection of entities returned is arbitrary.

Increase reference count of an entity

gxf_result_t GxfEntityRefCountInc(gxf_context_t context, gxf_uid_t eid);

Increases the reference count for an entity by 1.

By default reference counting is disabled for an entity. This means that entities created with ‘GxfEntityCreate’ are not automatically destroyed. If this function is called for an entity with disabled reference count, reference counting is enabled and the reference count is set to 1. Once reference counting is enabled an entity will be automatically destroyed if the reference count reaches zero, or if ‘GxfEntityCreate’ is called explicitly.

Decrease reference count of an entity

gxf_result_t GxfEntityRefCountDec(gxf_context_t context, gxf_uid_t eid);

Decreases the reference count for an entity by 1.

See ‘GxfEntityRefCountInc’ for more details on reference counting.

Get status of an entity

gxf_result_t GxfEntityGetStatus(gxf_context_t context, gxf_uid_t eid, gxf_entity_status_t* entity_status);

Gets the status of the entity.

See ‘gxf_entity_status_t’ for the various status.

Get state of an entity

gxf_result_t GxfEntityGetState(gxf_context_t context, gxf_uid_t eid, entity_state_t* entity_state);

Gets the state of the entity.

See ‘gxf_entity_status_t’ for the various status.

Notify entity of an event

gxf_result_t GxfEntityEventNotify(gxf_context_t context, gxf_uid_t eid);

Notifies the occurrence of an event and inform the scheduler to check the status of the entity

The entity must have an ‘AsynchronousSchedulingTerm’ scheduling term component and it must be in “EVENT_WAITING” state for the notification to be acknowledged.

See ‘AsynchronousEventState’ for various states

Maximum number of components in an entity or an extension can be up to 1024.

Get component type identifier

gxf_result_t GxfComponentTypeId(gxf_context_t context, const char* name, gxf_tid_t* tid);

Gets the GXF unique type ID (TID) of a component

Get the unique type ID which was used to register the component with GXF. The function expects the fully qualified C++ type name of the component including namespaces.

Example of a valid component type name: “nvidia::gxf::test::PingTx”

Get component type name

gxf_result_t GxfComponentTypeName(gxf_context_t context, gxf_tid_t tid, const char** name);

Gets the fully qualified C++ type name GXF component typename

Get the unique typename of the component with which it was registered using one of the GXF_EXT_FACTORY_ADD*() macros

Get component name

gxf_result_t GxfComponentName(gxf_context_t context, gxf_uid_t cid, const char** name);

Gets the name of a component

Each component has a user-defined name which was used in the call to ‘GxfComponentAdd’. Usually the name is specified in the GXF application file.

Get unique identifier of the entity of given component

gxf_result_t GxfComponentEntity(gxf_context_t context, gxf_uid_t cid, gxf_uid_t* eid);

Gets the unique object ID of the entity of a component

Each component has a unique ID with respect to the context and is stored in one entity. This function can be used to retrieve the ID of the entity to which a given component belongs.

Add a new component

gxf_result_t GxfComponentAdd(gxf_context_t context, gxf_uid_t eid, gxf_tid_t tid, const char* name, gxf_uid_t* cid);

Adds a new component to an entity

An entity can contain multiple components and this function can be used to add a new component to an entity. A component must be added before an entity is activated, or after it was deactivated. Components must not be added to active entities. The order of components is stable and identical to the order in which components are added (see ‘GxfComponentFind’).

Add component to entity interface

gxf_result_t GxfComponentAddToInterface(gxf_context_t context, gxf_uid_t eid, gxf_uid_t cid, const char* name);

Adds an existing component to the interface of an entity

An entity can holds references to other components in its interface, so that when finding a component in an entity, both the component this entity holds and those it refers to will be returned. This supports the case when an entity contains a subgraph, then those components that has been declared in the subgraph interface will be put to the interface of the parent entity.

Find a component in an entity

gxf_result_t GxfComponentFind(gxf_context_t context, gxf_uid_t eid, gxf_tid_t tid, const char* name, int32_t* offset, gxf_uid_t* cid);

Finds a component in an entity

Searches components in an entity which satisfy certain criteria: component type, component name, and component min index. All three criteria are optional; in case no criteria is given the first component is returned. The main use case for “component min index” is a repeated search which continues at the index which was returned by a previous search.

In case no entity with the given criteria was found GXF_ENTITY_NOT_FOUND is returned.

Get type identifier for a component

gxf_result_t GxfComponentType(gxf_context_t context, gxf_uid_t cid, gxf_tid_t* tid);

Gets the component type ID (TID) of a component

Gets pointer to component

gxf_result_t GxfComponentPointer(gxf_context_t context, gxf_uid_t uid, gxf_tid_t tid, void** pointer);

Verifies that a component exists, has the given type, gets a pointer to it.

64-bit floating point

Set

gxf_result_t GxfParameterSetFloat64(gxf_context_t context, gxf_uid_t uid, const char* key, double value);

Get

gxf_result_t GxfParameterGetFloat64(gxf_context_t context, gxf_uid_t uid, const char* key, double* value);

64-bit signed integer

Set

gxf_result_t GxfParameterSetInt64(gxf_context_t context, gxf_uid_t uid, const char* key, int64_t value);

Get

gxf_result_t GxfParameterGetInt64(gxf_context_t context, gxf_uid_t uid, const char* key, int64_t* value);

64-bit unsigned integer

Set

gxf_result_t GxfParameterSetUInt64(gxf_context_t context, gxf_uid_t uid, const char* key, uint64_t value);

Get

gxf_result_t GxfParameterGetUInt64(gxf_context_t context, gxf_uid_t uid, const char* key, uint64_t* value);

32-bit signed integer

Set

gxf_result_t GxfParameterSetInt32(gxf_context_t context, gxf_uid_t uid, const char* key, int32_t value);

Get

gxf_result_t GxfParameterGetInt32(gxf_context_t context, gxf_uid_t uid, const char* key, int32_t* value);

String parameter

Set

gxf_result_t GxfParameterSetStr(gxf_context_t context, gxf_uid_t uid, const char* key, const char* value);

Get

gxf_result_t GxfParameterGetStr(gxf_context_t context, gxf_uid_t uid, const char* key, const char** value);

Boolean

Set

gxf_result_t GxfParameterSetBool(gxf_context_t context, gxf_uid_t uid, const char* key, bool value);

Get

gxf_result_t GxfParameterGetBool(gxf_context_t context, gxf_uid_t uid, const char* key, bool* value);

Handle

Set

gxf_result_t GxfParameterSetHandle(gxf_context_t context, gxf_uid_t uid, const char* key, gxf_uid_t cid);

Get

gxf_result_t GxfParameterGetHandle(gxf_context_t context, gxf_uid_t uid, const char* key, gxf_uid_t* cid);

To set or get the vector parameters of a component, users can use the following C-APIs for various data types:

Set 1-D Vector Parameters

Users can call gxf_result_t GxfParameterSet1D"DataType"Vector(gxf_context_t context, gxf_uid_t uid, const char* key, data_type* value, uint64_t length)

value should point to an array of the data to be set of the corresponding type. The size of the stored array should match the length argument passed.

See the table below for all the supported data types and their corresponding function signatures.

Table 1 Supported Data Types to Set 1D Vector Parameters

Function Name	data_type
GxfParameterSet1DFloat64Vector(...)	double
GxfParameterSet1DInt64Vector(...)	int64_t
GxfParameterSet1DUInt64Vector(...)	uint64_t
GxfParameterSet1DInt32Vector(...)	int32_t

Set 2-D Vector Parameters

Users can call gxf_result_t GxfParameterSet2D"DataType"Vector(gxf_context_t context, gxf_uid_t uid, const char* key, data_type** value, uint64_t height, uint64_t width)

value should point to an array of array (and not to the address of a contiguous array of data) of the data to be set of the corresponding type. The length of the first dimension of the array should match the height argument passed and similarly the length of the second dimension of the array should match the width passed.

See the table below for all the supported data types and their corresponding function signatures.

Table 2 Supported Data Types to Set 2D Vector Parameters

Function Name	data_type
GxfParameterSet2DFloat64Vector(...)	double
GxfParameterSet2DInt64Vector(...)	int64_t
GxfParameterSet2DUInt64Vector(...)	uint64_t
GxfParameterSet2DInt32Vector(...)	int32_t

Get 1-D Vector Parameters

Users can call gxf_result_t GxfParameterGet1D"DataType"Vector(gxf_context_t context, gxf_uid_t uid, const char* key, data_type** value, uint64_t* length) to get the value of a 1-D vector.

Before calling this method, users should call GxfParameterGet1D"DataType"VectorInfo(gxf_context_t context, gxf_uid_t uid, const char* key, uint64_t* length) to obtain the length of the vector parameter and then allocate at least that much memory to retrieve the value.

value should point to an array of size greater than or equal to length allocated by user of the corresponding type to retrieve the data. If the length doesn’t match the size of stored vector then it will be updated with the expected size.

See the table below for all the supported data types and their corresponding function signatures.

Table 3 Supported Data Types to Get the Value of 1D Vector Parameters

Function Name	data_type
GxfParameterGet1DFloat64Vector(...)	double
GxfParameterGet1DInt64Vector(...)	int64_t
GxfParameterGet1DUInt64Vector(...)	uint64_t
GxfParameterGet1DInt32Vector(...)	int32_t

Get 2-D Vector Parameters

Users can call gxf_result_t GxfParameterGet2D"DataType"Vector(gxf_context_t context, gxf_uid_t uid, const char* key, data_type** value, uint64_t* height, uint64_t* width) to get the value of a -2D vector.

Before calling this method, users should call GxfParameterGet1D"DataType"VectorInfo(gxf_context_t context, gxf_uid_t uid, const char* key, uint64_t* height, uint64_t* width) to obtain the height and width of the 2D-vector parameter and then allocate at least that much memory to retrieve the value.

value should point to an array of array of height (size of first dimension) greater than or equal to height and width (size of the second dimension) greater than or equal to width allocated by user of the corresponding type to get the data. If the height or width don’t match the height and width of the stored vector then they will be updated with the expected values.

See the table below for all the supported data types and their corresponding function signatures.

Table 4 Supported Data Types to Get the Value of 2D Vector Parameters

Function Name	data_type
GxfParameterGet2DFloat64Vector(...)	double
GxfParameterGet2DInt64Vector(...)	int64_t
GxfParameterGet2DUInt64Vector(...)	uint64_t
GxfParameterGet2DInt32Vector(...)	int32_t

Get Meta Data about the GXF Runtime

gxf_result_t GxfRuntimeInfo(gxf_context_t context, gxf_runtime_info* info);

Get description and list of components in loaded Extension

gxf_result_t GxfExtensionInfo(gxf_context_t context, gxf_tid_t tid, gxf_extension_info_t* info);

Get description and list of parameters of Component

gxf_result_t GxfComponentInfo(gxf_context_t context, gxf_tid_t tid, gxf_component_info_t* info);

Note: Parameters are only available after at least one instance is created for the Component.

Get parameter type description

Gets a string describing the parameter type

const char* GxfParameterTypeStr(gxf_parameter_type_t param_type);

Get flag type description

Gets a string describing the flag type

const char* GxfParameterFlagTypeStr(gxf_parameter_flags_t_ flag_type);

Get parameter description

Gets description of specific parameter. Fails if the component is not instantiated yet.

gxf_result_t GxfGetParameterInfo(gxf_context_t context, gxf_tid_t cid, const char* key, gxf_parameter_info_t* info);

Redirect logs to a file

Redirect console logs to the provided file.

gxf_result_t GxfGetParameterInfo(gxf_context_t context, FILE* fp);

Get string description of error

const char* GxfResultStr(gxf_result_t result);

Gets a string describing an GXF error code.

The caller does not get ownership of the return C string and must not delete it.