GXF Core C++ APIs
Expected
-
template<typename T>
using nvidia::gxf::Expected = nvidia::Expected<T, gxf_result_t> The Expected type is a template that represents a value that either contains a result of type
T
or an error code of typegxf_result_t
. It is used throughout the GXF framework to represent the result of functions that can either succeed and return a value or fail and return an error code.-
template<typename T>
nvidia::gxf::Expected<T> nvidia::gxf::Expected(T value) Constructs an expected object with a value of type T.
- Parameters
value – The value to be stored in the Expected object.
-
template<typename T>
nvidia::gxf::Expected<T> nvidia::gxf::Expected(T &&value) Constructs an expected object with a value of type T using move construct.
- Parameters
value – The value to be stored in the Expected object.
-
template<typename T>
bool nvidia::gxf::Expected::has_value() Returns true if the Expected object contains a value, false otherwise.
- Returns
True if the Expected object contains a value, false otherwise.
-
template<typename T>
T nvidia::gxf::Expected::value() Returns the value of the expected object if it has a valid value, otherwise an assert will be raised if it was constructed using an Unexpected.
- Returns
The value stored in the Expected object.
-
template<typename T>
gxf_result_t nvidia::gxf::Expected::error() Returns the error code of the expected object if it was constructed using an Unexpected, otherwise an assert will be raised.
- Returns
The error code stored in the Expected object.
-
template<typename T>
nvidia::gxf::Unexpected<gxf_result_t> nvidia::gxf::ForwardError(const nvidia::gxf::Expected<T> &expected) Extracts the error code as an unexpected.
- Parameters
expected – The Expected object from which to extract the error code.
- Returns
The error code stored in the Expected object as an unexpected.
-
template<typename T>
nvidia::gxf::Unexpected<gxf_result_t> nvidia::gxf::ForwardError(nvidia::gxf::Expected<T> &&expected) Extracts the error code as an unexpected.
- Parameters
expected – The Expected object from which to extract the error code.
- Returns
The error code stored in the Expected object as an unexpected.
-
template<typename T>
gxf_result_t nvidia::gxf::ToResultCode(const nvidia::gxf::Expected<T> &result) Interprets an expected as a result code. Returns GXF_SUCCESS if the result has a value and the result’s error code otherwise.
- Parameters
result – The Expected object to interpret as a result code.
- Returns
GXF_SUCCESS if the Expected object contains a value, the result’s error code otherwise.
-
nvidia::gxf::Expected<void> nvidia::gxf::ExpectedOrCode(gxf_result_t code)
If the result code is GXF_SUCCESS the function returns nvidia::gxf::Success, otherwise it returns an unexpected with the given error code.
- Parameters
code – The result code to interpret.
- Returns
An Expected object
-
template<typename T>
nvidia::gxf::Expected<std::remove_cv_t<std::remove_reference_t<T>>> nvidia::gxf::ExpectedOrCode(gxf_result_t code, T &&value) If the result code is GXF_SUCCESS the function returns the value, otherwise it returns an unexpected with the given error code.
- Parameters
code – The result code to interpret.
value – Value to be returned when code is GXF_SUCCESS
- Returns
An Expected object
-
template<typename S, typename T>
nvidia::gxf::Expected<std::remove_cv_t<std::remove_reference_t<T>>> nvidia::gxf::ExpectedOrError(const nvidia::gxf::Expected<S> &code, T &&value) If the expected code is a valid expected object, the function returns the given value, otherwise it returns the error as an Unexpected.
- Parameters
code – The expected object to interpret.
value – Value to be returned when code has a valid object
- Returns
An Expected object
-
template<typename S, typename T>
gxf_result_t nvidia::gxf::AccumulateError(gxf_result_t previous, gxf_result_t current) Accumulates the error codes of two nvidia::gxf::gxf_result_t objects. Returns the first code if it is not a GXF_SUCCESS, else returns the previous code
-
nvidia::gxf::Expected<void> nvidia::gxf::AccumulateError(Expected<void> previous, Expected<void> current)
Accumulates the error codes of two expected objects. Returns the current object if it has an error, otherwise it returns the previous object.
Creating an Expected
An Expected can be created in two ways:
By constructing it with a value of type T
Expected<int> result{42};
By constructing it with an error code of type
gxf_result_t
Expected<int> result = Unexpected{GXF_OUT_OF_MEMORY};
Accessing the Value or Error Code
The value or error code of an Expected can be accessed using the
value()
anderror()
member functions, respectively. If the Expected contains a value,value()
returns that value anderror()
returns an error code of typegxf_result_t
with the value GXF_SUCCESS. If the Expected contains an error code,value()
returns an error code of typegxf_result_t
with the value GXF_FAILURE anderror()
returns the error code.Expected<int> result {42}; int value = result.value(); // value == 42 gxf_result_t error = result.error(); // GXF_ASSERT raised Expected<int> result = Unexpected{GXF_OUT_OF_MEMORY}; error = result.error(); // error == GXF_OUT_OF_MEMORY value = result.value(); // GXF_ASSERT raised
Checking if an Expected Contains a Value
The presence of a value in an Expected can be checked using the
has_value()
member function.Expected<int> result {42}; if (result.has_value()) { // The expected contains a value } else { // The expected contains an error code }
Converting an Expected to a Result Code
An Expected can be converted to a result code using the
ToResultCode()
function. If the Expected contains a value, the function returns GXF_SUCCESS. If the Expected contains an error code, the function returns that error code.Expected<int> result {42}; gxf_result_t code = ToResultCode(result); // code == GXF_SUCCESS Expected<int> result = Unexpected{GXF_OUT_OF_MEMORY}; code = ToResultCode(result); // code == GXF_OUT_OF_MEMORY
Creating an Expected from a Result Code
An Expected can be created from a result code using the
ExpectedOrCode()
function. If the result code is GXF_SUCCESS, the function returns an Expected with a value of typeT
. If the result code is not GXF_SUCCESS, the function returns an Expected with the corresponding error code of typegxf_result_t
.`gxf_result_t code = GXF_SUCCESS; int value = 42; Expected<int> result = ExpectedOrCode(code, 42); // result contains a value of type int with the value 42
Using Expected with Functions that Return Values
The Expected type can be used with functions that return values to simplify error handling. For example, consider the following function that divides two integers:
Expected<int> Divide(int dividend, int divisor) { if (divisor == 0) { return Unexpected{GXF_INVALID_ARGUMENT}; } return dividend / divisor; }
This function returns an Expected with a value of type int if the division is successful, or an error code of type
gxf_result_t
if the division is not possible (i.e., if the divisor is zero). The nvidia::gxf::Unexpected type is a template specialization that is used in conjunction with the nvidia::gxf::Expected template to represent an error state in a result type.To use this function, the caller can check if the Expected contains a value or an error code:
Expected<int> result = Divide(42, 0); if (result.has_value()) { // The division was successful int value = result.value(); } else { // The division was not successful gxf_result_t error = result.error(); }
-
template<typename T>
Component
-
class nvidia::gxf::Component
Components are parts of an entity and provide their functionality. The Component class is the base class of all GXF components. It provides a common interface for creating and managing components in a GXF entity.
-
virtual gxf_result_t initialize() = 0;
Use to start the lifetime of a component and should be used instead of the constructor. Called after all components of an entity are created. The order in which components within the same entity are initialized is undefined.
-
virtual gxf_result_t deinitialize() = 0;
Use to end the lifetime of a component and should be used instead of the deconstructor. The order in which components within the same entity are deinitialized is undefined.
-
virtual gxf_result_t registerInterface(Registrar *registrar) = 0;
Used to register all parameters of the components. Do not use this function for other purposes as it might be called at anytime by the runtime.
- Example
class Foo : public Component { public: gxf_result_t registerInterface(Registrar* registrar) override { registrar->parameter(count_, "count", 1); } Parameter<int> count_; };
The
registerInterface()
function is used to register the parameters of a component. It takes a pointer to aRegistrar
object as an argument and registers all the parameters of the component using one of the overloaded parameter api’s. The api supports multiple arguments which include the name of the parameter, unique key identifier, strings for headline and description of the parameter and also its default value.
-
gxf_context_t context() const noexcept;
Get the context of the component.
-
gxf_uid_t eid() const noexcept;
Get the entity ID of the component.
-
gxf_uid_t cid() const noexcept;
Get the component ID of the component.
-
gxf_tid_t tid() const noexcept;
Get the type ID of the component.
-
const char *type_name() const noexcept;
Get the type name of the component.
-
const char *name() const noexcept;
Get the name of the component.
-
void internalSetup(gxf_context_t context, gxf_uid_t eid, gxf_uid_t cid, Registrar *registrar);
This function shall only be called by GXF and is used to setup the component.
-
template<typename T>
Expected<T> getParameter(const char *key); Query the value of a component parameter with the given “key” where T is a valid parameter type.
- Parameters
key – A unique string value used during component registration
- Returns
A value of type T for valid key or error code on failure
-
Expected<YAML::Node> wrapParameter(const char *key);
Wrap the current value of the parameter “key” in a yaml node.
- Parameters
key – A unique string value used during component registration
- Returns
A yaml node with the parameter value
-
template<typename T>
Expected<void> setParameter(const char *key, T value); Set the parameter “key” with “value” where T is a valid parameter type.
- Parameters
key – A unique string value used during component registration
value – An object of type T
- Returns
Expected<void> Success or error code on failure
-
template<typename T>
Expected<void> setParameter(const char *key, Handle<T> &value); Set a parameter “key” of handle type with “value” where T is a valid parameter type.
- Parameters
key – A unique string value used during component registration
value – Handle to a component object of type T
- Returns
Success or error code on failure
-
Expected<void> parseParameter(const char *key, const YAML::Node &node, std::string prefix = "");
Set the parameter “key” with the value in yaml node.
- Parameters
key – A unique string value used during component registration
node – A yaml node with parameter value
prefix – entity prefix string
- Returns
Success or error code on failure
-
template<typename T>
Expected<std::vector<ParameterRegistrar::ComponentParameterInfo>> getParametersOfType(); Query all parameters in the component of type T and return their ComponentParameterInfo struct.
- Returns
A vector of ComponentParameterInfo of parameters of given type
-
Expected<ParameterRegistrar::ComponentParameterInfo> getParameterInfo(const char *key);
Query ComponentParameterInfo of parameter “key”.
-
virtual ~Component() = default;
Destructor.
-
Component(const Component &component) = delete;
Delete copy constructor. This constructor is deleted to prevent copying of Components.
-
Component(Component &&component) = delete;
Delete move constructor. This constructor is deleted to prevent moving Components.
-
virtual gxf_result_t initialize() = 0;
Entity
-
class nvidia::gxf::Entity
An entity owns multiple components which define the functionality of the entity. Entities themselves are nothing more than a unique identifier. Entities created using the C++ type is ref counted. The ref count is automatically decreased when the entity object is destructed or goes out of scope.
-
static Expected<Entity> New(gxf_context_t context, const char *name = nullptr)
Creates a new entity using the given context and optionally set the given name. The caller of this api own’s the object. The reference count is set to 1 and it is automatically reduced when this object is destroyed or goes out of scope.
- Parameters
context – The GXF context.
name – The name of the entity.
- Returns
A new entity or an error.
-
static Expected<Entity> Own(gxf_context_t context, gxf_uid_t eid)
Creates an entity handle based on an existing ID and takes ownership. Reference count is not increased.
- Parameters
context – The GXF context.
eid – The entity ID.
- Returns
A new entity handle or an error.
Creates an entity handle based on an existing ID and shares ownership. Reference count is increased by one.
- Parameters
context – The GXF context.
eid – The entity ID.
- Returns
A new entity handle or an error.
-
Entity()
Construct a new entity object using default constructor. This is a null entity without a valid context of entity ID.
-
Entity(Entity &&other)
Construct a new entity object by moving the contents from an existing entity object.
-
~Entity()
Destroy the Entity object. Reduces the reference count by 1.
-
gxf_context_t context() const
Returns the GXF context of the entity.
-
gxf_uid_t eid() const
Returns the unique object ID (UID) of the entity
-
bool is_null() const
Checks if an entity object is null (empty)
-
const char *name() const
The name of the entity or empty string if no name has been given to the entity.
-
Expected<Entity> clone() const
Clone an entity from an existing entity object. The returned entity shares the ownership with the entity being cloned from. Reference count is increased by one.
-
Expected<UntypedHandle> add(gxf_tid_t tid, const char *name = nullptr)
Adds a component with given type ID
- Parameters
tid – A valid type ID of a registered component
name – Name to be given to the newly created component instance
- Returns
An untyped handle to component or error code on failure
-
template<typename T>
Expected<Handle<T>> add(const char *name = nullptr) Adds a component of type T, where T is a registered component type.
- Parameters
name – Name to be given to the newly created component instance
- Returns
A new component handle or an error.
-
Expected<UntypedHandle> get(gxf_tid_t tid, const char *name = nullptr) const
Gets a component by type ID. Asserts if no such component.
- Parameters
tid – A valid type ID of a registered component
name – Name of the component to lookup
- Returns
An untyped handle to component or error code on failure
-
template<typename T>
Expected<Handle<T>> get(const char *name = nullptr) const Gets a component of type T with given name. Asserts if no such component.
- Parameters
name – Name of the component to lookup
- Returns
Typed Handle to the component instance or error on failure
-
template<size_t N = kMaxComponents>
Expected<FixedVector<UntypedHandle, N>> findAll() const Finds all components in an entity. A list of untyped handles of all the components are returned. N is the capacity of the FixedVector.
- Returns
A fixed-size vector of untyped component handles or an error.
-
static Expected<Entity> New(gxf_context_t context, const char *name = nullptr)
Handle
UntypedHandle Class
-
class nvidia::gxf::UntypedHandle
The UntypedHandle class is a base class for Handle and provides common functionality for accessing components without specifying their type.
-
static UntypedHandle Null()
- Returns
A null UntypedHandle object.
-
static Expected<UntypedHandle> Create(gxf_context_t context, gxf_uid_t cid)
Creates a new untyped handle
- Parameters
context – The context to which the component belongs.
cid – The ID of the component.
- Returns
A new UntypedHandle object for the given context and component ID.
-
gxf_context_t context() const
- Returns
The context to which the component belongs.
-
gxf_uid_t cid() const
- Returns
The ID of the component.
-
gxf_tid_t tid() const
- Returns
The type ID describing the component type.
-
bool is_null() const
- Returns
True if the handle is equivalent to a nullptr.
-
explicit operator bool() const
- Returns
True if the handle is not null.
-
const char *name() const
- Returns
The name of the component.
-
UntypedHandle(const UntypedHandle &component) = default
- Parameters
component – The UntypedHandle object to copy.
-
UntypedHandle(UntypedHandle &&component) = default
- Parameters
component – The UntypedHandle object to move.
-
UntypedHandle &operator=(const UntypedHandle &component) = default
- Parameters
component – The UntypedHandle object to copy.
-
UntypedHandle &operator=(UntypedHandle &&component) = default
- Parameters
component – The UntypedHandle object to move.
-
static UntypedHandle Null()
Handle Class
-
class nvidia::gxf::Handle
The Handle class is a template class that derives from UntypedHandle and provides access to components with a specific type.
-
static Handle Unspecified()
An unspecified handle is a unique handle used to denote a component which will be created in the future. A parameter of Handle to a type does not consider “Unspecified” as a valid parameter value and hence this handle must only be used when defining a graph application across different files and the parameters are set in a delayed fashion (sub-graphs and parameter yaml files for example) Entity activation will fail if any of the mandatory parameters are “Unspecified”
- Returns
An unspecified Handle object.
-
static Expected<Handle> Create(gxf_context_t context, gxf_uid_t cid)
Creates a new handle using the component id
- Parameters
context – The context to which the component belongs.
cid – The ID of the component.
- Returns
A new Handle object for the given context and component ID.
-
static Expected<Handle> Create(const UntypedHandle &untyped_handle)
Creates a new handle from an untyped handle
- Parameters
untyped_handle – The UntypedHandle object to create a Handle object from.
- Returns
A new Handle object for the given UntypedHandle object.
-
bool operator==(const Handle &lhs, const Handle &rhs);
Compare if two handle objects are equal
- Returns
True if the handle objects are pointing to the same component
-
bool operator!=(const Handle &lhs, const Handle &rhs);
Compare if two handle objects are not equal
- Returns
True if the handle objects are not pointing to the same component
-
bool operator<(const Handle &lhs, const Handle &rhs);
Compare if an handle object is less than the other
- Parameters
lhs – typed handle a component
rhs – typed handle a component
- Returns
True if the component id of lhs is less than rhs
-
template<typename Derived>
Handle(gxf_context_t context = kNullContext, gxf_uid_t uid = kNullUid) Constructor equivalent to :cpp:func::Handle::Create function
-
operator T*() const
- Returns
A pointer to the component of the specific type.
-
T *operator->() const
- Returns
A pointer to the component of the specific type.
-
T *get() const
- Returns
A pointer to the component of the specific type.
-
Expected<T*> try_get() const
- Returns
A pointer to the component of the specific type or an error if the handle is invalid.
-
static Handle Unspecified()
Parameters
-
template<typename T>
class Parameter A parameter is a value that can be configured and accessed by a component. It provides a type-safe and convenient way to manage component attributes.
-
Parameter()
Default constructor. Creates an uninitialized parameter.
- Returns
An uninitialized parameter.
-
Parameter(const Parameter &other)
Copy constructor.
- Parameters
other – The parameter to copy.
- Returns
A copy of the other parameter.
-
const T &get() const
Gets the current parameter value. Only valid if the parameter is marked as ‘mandatory’ in the parameter interface. Otherwise an assert will be raised.
- Returns
A const reference to the current value of the parameter.
-
operator const T&() const
Convenience function for accessing a mandatory parameter as a const reference.
- Returns
A const reference to the current value of the parameter.
-
Expected<T> try_get() const
Tries to get the current value of the parameter. If the parameter is not set or has an error value, returns an Unexpected with an error code.
- Returns
The current value of the parameter, or an Unexpected with an error code.
-
Expected<void> set(T value)
- Sets the current value of the parameter. If the value is invalid, returns an Unexpected
with an error code.
- Parameters
value – The new value of the parameter.
- Returns
Expected<void> Success or error code on failure
-
void connect(ParameterBackend<T> *backend)
Connects the parameter to a backend. The backend is responsible for managing the parameter value and providing access to it.
- Parameters
backend – The backend to connect to.
-
const char *key() const
Returns the key of the parameter. The key is a string that identifies the parameter and is used to look it up in the parameter storage.
- Returns
The key of the parameter.
-
Expected<void> set_without_propagate(T value)
Sets the current value of the parameter without propagating the change to the backend. This function should only be used by the ParameterBackend class.
- Parameters
value – The new value of the parameter.
- Returns
Expected<void> Success or error code on failure
-
Parameter()
Parameter Types
GXF supports multiple parameter types natively as described in :c:enum::gxf_parameter_type_t. All standard C++ data types are supported including POD types, string, bool, handles to components and complex numbers. ParameterWrapper and ParameterParser interfaces can be used to support any custom Parameter type.
- struct ParameterParser
- template<typename T, typename V = void>
static Expected<T> Parse(gxf_context_t context, gxf_uid_t component_uid, const char *key, const YAML::Node &node, const std::string &prefix)Parses a parameter of type T from a YAML node.
- Parameters
context – The GXF context.
component_uid – The unique identifier of the component.
key – The key of the parameter.
node – The YAML node to parse.
prefix – The prefix to use when looking up entities.
- Returns
An Expected containing the parsed parameter or an error code.
- struct ParameterWrapper
Here is an example to adapt ParameterParser and ParameterWrapper to create an enum parameter
- Example
// Mode switch enum struct MyEnum { kValue0 = 0, kValue1 = 1, }; // Custom parameter parser for MyEnum template <> struct ParameterParser<MyEnum> { static Expected<MyEnum> Parse(gxf_context_t context, gxf_uid_t component_uid, const char* key, const YAML::Node& node, const std::string& prefix) { const std::string value = node.as<std::string>(); if (strcmp(value.c_str(), "Value0") == 0) { return MyEnum::kValue0; } if (strcmp(value.c_str(), "Value1") == 0) { return MyEnum::kValue1; } return Unexpected{GXF_ARGUMENT_OUT_OF_RANGE}; } }; // Custom parameter wrapper for MyEnum template<> struct ParameterWrapper<MyEnum> { static Expected<YAML::Node> Wrap(gxf_context_t context, const MyEnum& value) { YAML::Node node(YAML::NodeType::Scalar); switch (value) { case MyEnum::kValue0: { node = std::string("Value0"); break; } case MyEnum::kValue1: { node = std::string("Value1"); break; } default: return Unexpected{GXF_PARAMETER_OUT_OF_RANGE}; } return node; } };
Parameter Registration
-
class nvidia::gxf::Registrar
The Registrar class is used to register parameters and resources of a component. The following api’s must be used within the
registerInterface()
function only.-
template<typename T>
Expected<void> parameter(Parameter<T> ¶meter, const char *key) Registers a parameter with the given key, where T is a valid parameter type.
- Parameters
parameter – The parameter to register
key – A unique string value used during component registration
- Returns
Expected<void> Success or error code on failure
-
template<typename T>
Expected<void> parameter(Parameter<T> ¶meter, const char *key, const char *headline) Registers a parameter with the given key and headline, where T is a valid parameter type.
- Parameters
parameter – The parameter to register
key – A unique string value used during component registration
headline – A brief description of the parameter
- Returns
Expected<void> Success or error code on failure
-
template<typename T>
Expected<void> parameter(Parameter<T> ¶meter, const char *key, const char *headline, const char *description) Registers a parameter with the given key, headline and description, where T is a valid parameter type.
- Parameters
parameter – The parameter to register
key – A unique string value used during component registration
headline – A brief description of the parameter
description – A detailed description of the parameter
- Returns
Expected<void> Success or error code on failure
-
template<typename T>
Expected<void> parameter(Parameter<T> ¶meter, const char *key, const char *headline, const char *description, const T &default_value) Registers a parameter with the given key, headline, description, and default value, where T is a valid parameter type.
- Parameters
parameter – The parameter to register
key – A unique string value used during component registration
headline – A brief description of the parameter
description – A detailed description of the parameter
default_value – The default value of the parameter
- Returns
Expected<void> Success or error code on failure
-
template<typename T>
Expected<void> parameter(Parameter<T> ¶meter, const char *key, const char *headline, const char *description, const T &default_value, gxf_parameter_flags_t flags) Registers a parameter with the given key, headline, description, default value, and flags, where T is a valid parameter type.
- Parameters
parameter – The parameter to register
key – A unique string value used during component registration
headline – A brief description of the parameter
description – A detailed description of the parameter
default_value – The default value of the parameter
flags – Flags to specify parameter properties
- Returns
Expected<void> Success or error code on failure
-
template<typename T>
Expected<void> parameter(Parameter<T> ¶meter, const char *key, const char *headline, const char *description, Unexpected, gxf_parameter_flags_t flags) Registers a parameter with the given key, headline, description, and flags, where T is a valid parameter type. The default value is set to an nvidia::gxf::Unexpected.
- Parameters
parameter – The parameter to register
key – A unique string value used during component registration
headline – A brief description of the parameter
description – A detailed description of the parameter
flags – Flags to specify parameter properties
- Returns
Expected<void> Success or error code on failure
-
template<typename T>
Expected<void> parameter(nvidia::gxf::Parameter<T> ¶meter, const ParameterInfo<T> ¶meter_info) Registers a parameter with
ParameterInfo
containing all the parameter metadata, where T is a valid parameter type.- Parameters
parameter – The parameter to register
parameter_info – A struct containing all the parameter metadata
- Returns
Expected<void> Success or error code on failure
-
template<typename T>
Expected<void> registerParameterlessComponent() Registers a component with no parameters. This is called internally by GXF if
registerInterface()
is not overridden.- Returns
Expected<void> Success or error code on failure
-
static constexpr Unexpected NoDefaultParameter()
Returns a constant for registering an optional parameter with no default value.
- Returns
Unexpected with code GXF_PARAMETER_NOT_INITIALIZED
-
template<typename T>