holoscan::Condition

Beta

Base class for all conditions.

A condition is a predicate that can be evaluated at runtime to determine if an operator should execute. This matches the semantics of GXF’s Scheduling Term.

#include <holoscan/condition.hpp>

Inherits from: holoscan::Component (public)

Constructors

Condition

Default

Move

Move (with arg and args)

holoscan::Condition::Condition() = defaultholoscan::Condition::Condition() = default

Destructor

~Condition

holoscan::Condition::~Condition() override = defaultholoscan::Condition::~Condition() override = default

Methods

check

virtual void holoscan::Condition::check(
    int64_t timestamp,
    SchedulingStatusType *status_type,
    int64_t *target_timestamp
) const

Check the condition status before allowing execution.

If the condition is waiting for a time event ‘target_timestamp’ will contain the target timestamp.

Parameters

timestamp

int64_t

The current timestamp

status_type

SchedulingStatusType *

The status of the condition

target_timestamp

int64_t *

The target timestamp (used if the term is waiting for a time event).

on_execute

virtual void holoscan::Condition::on_execute(
    int64_t timestamp
)

Called each time after the entity of this term was executed.

Parameters

timestamp

int64_t

The current timestamp

update_state

virtual void holoscan::Condition::update_state(
    int64_t timestamp
)

Checks if the state of the condition can be updated and updates it.

Parameters

timestamp

int64_t

The current timestamp

condition_type

ConditionComponentType holoscan::Condition::condition_type() constConditionComponentType holoscan::Condition::condition_type() const

Get the condition type.

Returns: The condition type.

name

Set the name of the condition (1)

Set the name of the condition (2)

Const

Condition & holoscan::Condition::name(Condition & holoscan::Condition::name(
    const std::string &name
) &

Set the name of the condition.

Returns: The reference to the condition.

Parameters

name

const std::string &

The name of the condition.

fragment

Set the fragment of the condition

Get a pointer to Fragment object

Const

Condition & holoscan::Condition::fragment(Condition & holoscan::Condition::fragment(
    Fragment *fragment
)

Set the fragment of the condition.

Returns: The reference to the condition.

Parameters

fragment

Fragment *

The pointer to the fragment of the condition.

spec

Set the component specification to the condition

Get the component specification of the condition

Condition & holoscan::Condition::spec(Condition & holoscan::Condition::spec(
    const std::shared_ptr<ComponentSpec> &spec
)

Set the component specification to the condition.

Returns: The reference to the condition.

Parameters

spec

const std::shared_ptr<ComponentSpec> &

The component specification.

spec_shared

std::shared_ptr<ComponentSpec> holoscan::Condition::spec_shared()std::shared_ptr<ComponentSpec> holoscan::Condition::spec_shared()

Get the shared pointer to the component spec.

Returns: The shared pointer to the component spec.

add_arg

Add a resource to the condition (1)

Add a resource to the condition (2)

Add an argument to the component (1)

Add an argument to the component (2)

Add a list of arguments to the component (1)

Add a list of arguments to the component (2)

void holoscan::Condition::add_arg(
    const std::shared_ptr<Resource> &arg
)

Add a resource to the condition.

Parameters

arg

const std::shared_ptr<Resource> &

The resource to add.

resources

std::unordered_map<std::string, std::shared_ptr<Resource>> & holoscan::Condition::resources()std::unordered_map<std::string, std::shared_ptr<Resource>> & holoscan::Condition::resources()

Get the resources of the condition.

Returns: The resources of the condition.

setup

virtual void holoscan::Condition::setup(
    ComponentSpec &spec
)

Define the condition specification.

Parameters

spec

ComponentSpec &

The reference to the component specification.

initialize

void holoscan::Condition::initialize() override

Initialize the component.

This method is called only once when the component is created for the first time, and use of light-weight initialization.

to_yaml_node

YAML::Node holoscan::Condition::to_yaml_node() const override

Get a YAML representation of the condition.

Returns: YAML node including spec of the condition in addition to the base component properties.

receiver

std::optional<std::shared_ptr<Receiver>> holoscan::Condition::receiver(std::optional<std::shared_ptr<Receiver>> holoscan::Condition::receiver(
    const std::string &port_name
)

Return the Receiver corresponding to a specific input port of the Operator associated with this condition.

Returns: The Receiver corresponding to the input port, if it exists. Otherwise, return nullopt.

Parameters

port_name

const std::string &

The name of the input port.

transmitter

std::optional<std::shared_ptr<Transmitter>> holoscan::Condition::transmitter(std::optional<std::shared_ptr<Transmitter>> holoscan::Condition::transmitter(
    const std::string &port_name
)

Return the Transmitter corresponding to a specific output port of the Operator associated with this condition.

Returns: The Transmitter corresponding to the output port, if it exists. Otherwise, return nullopt.

Parameters

port_name

const std::string &

The name of the output port.

wrapper_cid

Mutable

Const

void holoscan::Condition::wrapper_cid(
    int64_t cid
)

Store the component ID for this condition in the underlying backend implementation.

This method may not be needed for all backends.

Parameters

cid

int64_t

Component id corresponding to the underlying framework

notify_scheduler

bool holoscan::Condition::notify_scheduler()

Notify the scheduler that an asynchronous event has completed.

This method is used by event-based conditions (those returning kWaitEvent from check()) to signal to the scheduler that the condition is now ready to be re-evaluated.

This method can be called from any thread (e.g., a CUDA host callback or a worker thread). It is thread-safe.

Example usage:

Returns: true if the notification was successful, false otherwise.

Example

// In a CUDA host callback or worker thread
void my_callback(void* user_data) {
    auto* condition = static_cast<MyCondition*>(user_data);
    condition->state_.store(State::EVENT_COMPLETE);
    condition->notify_scheduler();
}

See also: SchedulingStatusType::kWaitEvent

set_parameters

void holoscan::Condition::set_parameters() override

Set the parameters based on defaults (sets GXF parameters for GXF components).

id

int64_t holoscan::ComponentBase::id() const

Get the identifier of the component.

By default, the identifier is set to -1. It is set to a valid value when the component is initialized.

With the default executor (GXFExecutor), the identifier is set to the GXF component ID.

Returns: The identifier of the component.

args

std::vector<Arg> & holoscan::ComponentBase::args()std::vector<Arg> & holoscan::ComponentBase::args()

Get the list of arguments.

Returns: The vector of arguments.

description

std::string holoscan::ComponentBase::description() const

Get a description of the component.

Returns: YAML string.

See also: to_yaml_node()

service

template <typename ServiceT = DefaultFragmentService>
std::shared_ptr<ServiceT> holoscan::ComponentBase::service(
    std::string_view id = ""
) const

Retrieve a registered fragment service or resource.

Retrieves a previously registered fragment service or resource by its type and optional identifier. Returns nullptr if no service/resource is found with the specified type and identifier.

Note that any changes to the service retrieval logic in this method should be synchronized with the implementation in Fragment::service() method to maintain consistency.

Returns: The shared pointer to the service/resource, or nullptr if not found or if type casting fails.

Template parameters

ServiceT

typename

The type of the service/resource to retrieve. Must inherit from either Resource or FragmentService. Defaults to DefaultFragmentService if not specified.

Parameters

std::string_viewDefaults to ""

The identifier of the service/resource. If empty, retrieves by type only.

get_service_by_type_info

std::shared_ptr<FragmentService> holoscan::ComponentBase::get_service_by_type_info(std::shared_ptr<FragmentService> holoscan::ComponentBase::get_service_by_type_info(
    const std::type_info &service_type,
    std::string_view id = ""
) const

Retrieve a registered fragment service or resource for Python bindings.

This is a helper method for Python bindings to retrieve a service by its C++ type info.

Returns: The shared pointer to the base service, or nullptr if not found.

Parameters

service_type

const std::type_info &

The type info of the service/resource to retrieve.

std::string_viewDefaults to ""

The identifier of the service/resource. If empty, retrieves by type only.

reset_backend_objects

virtual void holoscan::ComponentBase::reset_backend_objects()

Reset any backend-specific objects (e.g. GXF GraphEntity).

set_operator

void holoscan::Condition::set_operator(
    Operator *op
)

Set the Operator this condition is associated with.

Parameters

Operator *

The pointer to the Operator object.

update_params_from_args

Update parameters based on the specified arguments

Update parameters based on the specified arguments (with params)

void holoscan::Condition::update_params_from_args()

Update parameters based on the specified arguments.

service_provider

void holoscan::ComponentBase::service_provider(
    FragmentServiceProvider *provider
)

Set the service provider that owns this component.

Static methods

register_converter

template <typename typeT>
static void holoscan::ComponentBase::register_converter()

If an operator or resource has an argument with a custom type, the argument setter must be registered using this method.

The argument setter is used to set the value of the argument from the YAML configuration.

This method can be called in the initialization phase of the operator/resource (e.g., initialize()). The example below shows how to register the argument setter for the custom type (Vec3):

It is assumed that YAML::convert<T>::encode and YAML::convert<T>::decode are implemented for the given type. You need to specialize the YAML::convert<> template class.

For example, suppose that you had a Vec3 class with the following members:

You can define the YAML::convert<Vec3> as follows in a ‘.cpp’ file:

Please refer to the yaml-cpp documentation for more details.

Template parameters

typeT

typename

The type of the argument to register.

Example

void MyOp::initialize() {
  register_converter<Vec3>();
}

Example

struct Vec3 {
  // make sure you have overloaded operator==() for the comparison
  double x, y, z;
};

Example

namespace YAML {
template<>
struct convert<Vec3> {
  static Node encode(const Vec3& rhs) {
    Node node;
    node.push_back(rhs.x);
    node.push_back(rhs.y);
    node.push_back(rhs.z);
    return node;
  }
  static bool decode(const Node& node, Vec3& rhs) {
    if(!node.IsSequence() || node.size() != 3) {
      return false;
    }
    rhs.x = node[0].as<double>();
    rhs.y = node[1].as<double>();
    rhs.z = node[2].as<double>();
    return true;
  }
};
}

register_argument_setter

template <typename typeT>
void holoscan::ComponentBase::register_argument_setter()

Please refer to the documentation of register_converter() for more details.

Template parameters

typeT

typename

The type of the argument to register.

Types

ConditionComponentType

Resource type used for the initialization of the resource.

Name	Value	Description
`kNative`		Native condition.
`kGXF`		GXF condition (scheduling term).

Member variables

Name	Type	Description
`is_initialized_`	`bool`	Whether the condition is initialized.
`resources_`	`std::unordered_map< std::string, std::shared_ptr< Resource > >`	The resources used by the condition.
`condition_type_`	`ConditionComponentType`	The type of the component.
`op_`	`Operator *`	The operator this condition is associated with.
`wrapper_cid_`	`int64_t`	Component ID of underlying GXFSchedulingTermWrapper.
`spec_`	`std::shared_ptr< ComponentSpec >`	The component specification.
`id_`	`int64_t`	The ID of the component.
`name_`	`std::string`	Name of the component.
`fragment_`	`Fragment *`	Pointer to the fragment that owns this component.
`args_`	`std::vector< Arg >`	List of arguments.
`service_provider_`	`FragmentServiceProvider *`	Pointer to the service provider.