Graph Runtime Python APIs

Context

Create context

context_create()

Creates a new Graph Runtime context

A Graph Runtime context is required for all almost all Graph Runtime 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.

returns: A unique integer representing context.

Destroy context

context_destroy(context)

Destroys a Graph Runtime context

Every Graph Runtime 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.

parameter: context A unique integer representing context

returns: None. Throws one of the Graph Runtime errors in not successful

Extensions

Maximum number of extensions in a context can be 1024.

Load Extensions from a file

load_extensions(context, extension_filenames, manifest_filenames, base_directory)

Loads extension in the given context from file.

parameter: context A valid Graph Runtime context

parameter: extension_filenames A list of valid filename.

parameter: manifest_filenames A list of valid filename.

parameter: base_directory Valid directory.

returns: None. Throws one of the Graph Runtime errors in not successful.

Graph

Loads a list of entities from YAML file

graph_load_file(context, filename)

parameter: context A valid Graph Runtime context

parameter: filename A valid YAML filename.

returns: None. Throws one of the Graph Runtime errors in not successful.

Activate all system components

graph_activate(context)

parameter: context A valid Graph Runtime context

returns: None. Throws one of the Graph Runtime errors in not successful.

Deactivate all System components

graph_deactivate(context)

parameter: context A valid Graph Runtime context

returns: None. Throws one of the Graph Runtime errors in not successful.

Starts the execution of the graph asynchronously

graph_run_async(context)

parameter: context A valid Graph Runtime context

returns: None. Throws one of the Graph Runtime errors in not successful.

Waits for the graph to complete execution

graph_wait(context)

parameter: context A valid Graph Runtime context

returns: None. Throws one of the Graph Runtime errors in not successful.

Runs all System components and waits for their completion

graph_run(context)

parameter: context A valid Graph Runtime context

returns: None. Throws one of the Graph Runtime errors in not successful.

Entities

Find an entity

entity_find(context, entity_name)

Finds an entity by its name

parameter: context A valid Graph Runtime context

parameter: entitiy_name A C string with the name of the entity. Ownership is not transferred.

returns: A unique entity identifier if successful else throws one of the Graph Runtime errors in not successful.

Get status of an entity

entity_get_status(context, eid)

Gets the status of the entity.

parameter: context A valid Graph Runtime context

parameter: eid The UID of a valid entity

returns: Returns entity status integer if successful else throws one of the Graph Runtime errors in not successful.

Components

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

Find a component in an entity

component_find(context, eid, tid, component_name)

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

parameter: context A valid Graph Runtime context

parameter: eid The unique object ID (UID) of the entity which is searched.

parameter: tid The component type ID (TID) of the component to find (optional)

parameter: component_name The component name of the component to find (optional). Ownership not transferred.

returns: List of cids if successful else throws one of the Graph Runtime errors in not successful.

Primitive Parameters

64-bit floating point

Set

parameter_set_float64(context, eid, key, value)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value a double value

returns: None. Throws one of the Graph Runtime errors in not successful.

Get

parameter_get_float64(context, eid, key)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the Graph Runtime errors in not successful.

64-bit signed integer

Set

parameter_set_int64(context, eid, key, value)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value 64-bit integer value to set.

returns: None. Throws one of the Graph Runtime errors in not successful.

Get

parameter_get_int64(context, eid, key)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the Graph Runtime errors in not successful.

64-bit unsigned integer

Set

parameter_set_uint64(context, eid, key, value)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value unsigned 64-bit integer value to set.

returns: None. Throws one of the Graph Runtime errors in not successful.

Get

parameter_get_uint64(context, eid, key)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the Graph Runtime errors in not successful.

32-bit signed integer

Set

parameter_set_int32(context, eid, key, value)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value 32-bit integer value to set.

returns: None. Throws one of the Graph Runtime errors in not successful.

Get

parameter_get_int32(context, eid, key)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the Graph Runtime errors in not successful.

String parameter

Set

parameter_set_str(context, eid, key, value)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value A char array containing value to set.

returns: None. Throws one of the Graph Runtime errors in not successful.

Get

parameter_get_str(context, eid, key)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the Graph Runtime errors in not successful.

Boolean

Set

parameter_set_bool(context, eid, key, value)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value A boolean value to set.

returns: None. Throws one of the Graph Runtime errors in not successful.

Get

parameter_get_bool(context, eid, key)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the Graph Runtime errors in not successful.

Handle

Set

parameter_set_handle(context, eid, key, value)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

parameter: value Unique identifier to set.

returns: None. Throws one of the Graph Runtime errors in not successful.

Get

parameter_get_handle(context, eid, key)

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key A valid name of a component to set.

returns: value of parameter if present. Throws one of the Graph Runtime errors in not successful.

Vector Parameters

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

Set 1-D Vector Parameters

Users can call parameter_set_1d_'data_type'_vector(context, eid, key, value, length)

value should be a list of the data to be set. 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.

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key The name of the parameter

parameter: value The value to set of the parameter

parameter: length The length of the vector parameter

returns: None. Throws one of the Graph Runtime errors in not successful.

Supported Data Types to Set 1D Vector Parameters

Function Name

data_type

parameter_set_1d_float64_vector(...)

double

parameter_set_1d_int64_vector(...)

int64_t

parameter_set_1d_uint64_vector(...)

uint64_t

parameter_set_1d_int32_vector(...)

int32_t

Set 2-D Vector Parameters

Users can call parameter_set_2d_'data_type'_vector(context, eid, key, value, height, width)

value should point to a list of list of the data to be set. The length of the first dimension of the list should match the height argument passed and similarly the length of the second dimension of the list should match the width passed.

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

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key The name of the parameter

parameter: value The value to set of the parameter

parameter: height The height of the 2-D vector parameter

parameter: width The width of the 2-D vector parameter

returns: None. Throws one of the Graph Runtime errors in not successful.

Supported Data Types to Set 2D Vector Parameters

Function Name

data_type

parameter_set_2d_float64_vector(...)

double

parameter_set_2d_int64_vector(...)

int64_t

parameter_set_2d_uint64_vector(...)

uint64_t

parameter_set_2d_int32_vector(...)

int32_t

Get 1-D Vector Parameters

Users can call parameter_get_1d_'data_type'_vector(context, eid, key, length) to get the value of a 1-D vector.

If the length should match the length of the parameter. If it is less than the parameter length then error is thrown. If it is greater than the length a larger list with the values set is returned.

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

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key The name of the parameter

parameter: length The length of the stored 1-D vector parameter.

returns: A list containing the values.

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

Function Name

data_type

parameter_get_1d_float64_vector(...)

double

parameter_get_1d_int64_vector(...)

int64_t

parameter_get_1d_uint64_vector(...)

uint64_t

parameter_get_1d_int32_vector(...)

int32_t

Get 2-D Vector Parameters

Users can call parameter_get_2d_'data_type'_vector(context, eid, key, height, width) to get the value of a 2D vector.

The height or width should match the height and width of the stored vector. If they are smaller than the stored values then error is thrown. If greater than the stored values then larger lists will be returned with values set.

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

parameter: context A valid Graph Runtime context.

parameter: eid A valid component identifier.

parameter: key The name of the parameter

parameter: height The height of the stored 2-D vector parameter.

parameter: width The width of the stored 2-D vector parameter.

returns: A list of list containing the values.

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

Function Name

data_type

parameter_get_2d_float64_vector(...)

double

parameter_get_2d_int64_vector(...)

int64_t

parameter_get_2d_uint64_vector(...)

uint64_t

parameter_get_2d_int32_vector(...)

int32_t