Class OperatorSpec

• Defined in File operator_spec.hpp

Base Type

• public holoscan::ComponentSpec (Class ComponentSpec)

class OperatorSpec : public holoscan::ComponentSpec

Class to define the specification of an operator.

Public Functions

virtual ~OperatorSpec() = default

inline explicit OperatorSpec(Fragment *fragment = nullptr)

Construct a new OperatorSpec object.

Parameters

fragment – The pointer to the fragment that contains this operator.

inline std::unordered_map<std::string, std::shared_ptr<IOSpec>> &inputs()

Get input specifications of this operator.

Returns

The reference to the input specifications of this operator.

template<typename DataT>
inline IOSpec &input()

Define an input specification for this operator.

Template Parameters

DataT – The type of the input data.

Returns

The reference to the input specification.

inline void multi_port_condition(ConditionType kind, const std::vector<std::string> &port_names, ArgList args)

Add a Condition that depends on the status of multiple input ports.

Parameters

• kind – The type of multi-message condition (currently only kMultiMessageAvailable)

• port_names – The names of the input ports the condition will apply to

• args – ArgList of arguments to pass to the MultiMessageAvailableCondition

inline std::vector<MultiMessageConditionInfo> &multi_port_conditions()

inline void or_combine_port_conditions(const std::vector<std::string> &port_names)

Assign the conditions on the specified input ports to be combined with an OR operation.

This is intended to allow using OR instead of AND combination of single-port conditions like MessageAvailableCondition for the specified input ports.

Parameters

port_names – The names of the input ports whose conditions will be OR combined.

inline std::vector<std::vector<std::string>> &or_combiner_port_names()

vector of the names of ports for each OrConditionCombiner

template<typename DataT>
inline IOSpec &input(std::string name, IOSpec::IOSize size = IOSpec::kSizeOne, std::optional<IOSpec::QueuePolicy> policy = std::nullopt)

Define an input specification for this operator.

Note: The ‘size’ parameter is used for initializing the queue size of the input port. The queue size can be set by this method or by the ‘IOSpec::queue_size(int64_t)’ method. If the queue size is set to ‘any size’ (IOSpec::kAnySize in C++ or IOSpec.ANY_SIZE in Python), the connector/condition settings will be ignored. If the queue size is set to other values, the default connector (DoubleBufferReceiver/UcxReceiver) and condition (MessageAvailableCondition) will use the queue size for initialization (‘capacity’ for the connector and ‘min_size’ for the condition) if they are not set.

Note: For input ports, a queue size greater than 1 will also set the default MessageAvailableCondition min_size to the same value unless you override the port condition. This enables batched execution. Holoscan emits a warning in the default-condition case. If you only want buffering without batching, explicitly set min_size=1. Holoscan plans to introduce an explicit batch_size configuration and change size to control queue capacity only; setting min_size explicitly now will make future migration straightforward. Please refer to the Holoscan SDK User Guide to see how to receive any number of inputs in C++.

Note: The ‘policy’ parameter controls the queue’s behavior if a message arrives when the queue is already full. By default, a DownstreamAffordableCondition is added to output ports to prevent an upstream operator from sending a message if there is no available queue space. However, if such a condition is not present (e.g., by calling condition(ConditionType::kNone) on IOSpec object), a message may still arrive when the queue is already full. In that case, the possible policies are:

• IOSpec::QueuePolicy::kPop - Replace the oldest message in the queue with the new one.

• IOSpec::QueuePolicy::kReject - Reject (discard) the new message.

• IOSpec::QueuePolicy::kFault - Log a warning and reject the new item.

Template Parameters

DataT – The type of the input data.

Parameters

• name – The name of the input specification.

• size – The size of the queue for the input port.

• policy – The queue policy used for the input port.

Returns

The reference to the input specification.

template<typename DataT>
inline IOSpec &input(std::string name, std::optional<IOSpec::QueuePolicy> policy)

Define an input specification for this operator.

Template Parameters

DataT – The type of the input data.

Parameters

• name – The name of the input specification.

• policy – The queue policy used for the input port.

Returns

The reference to the input specification.

inline IOSpec &device_input(std::string name, size_t memory_block_size)

Define an input specification for this operator with a memory block size. It is only applicable for GPU-resident operators.

The executor will allocate a shared device memory buffer of the specified size for this port and the connected output port. Both ports will map to the same device memory address. Integer literals (e.g. 0, 1024) and size_t values resolve to this overload.

Parameters

• name – The name of the input specification.

• memory_block_size – The device memory block size in bytes.

Returns

The reference to the input specification.

template<typename T>
inline std::enable_if_t<std::is_same_v<std::decay_t<T>, CUdeviceptr> || std::is_same_v<std::decay_t<T>, void*>, IOSpec&> device_input(std::string name, T device_ptr)

Define an input specification for this operator with an externally managed device memory pointer. It is only applicable for GPU-resident operators.

Use this overload when the operator allocates and manages its own device memory (e.g. via cudaMalloc). The executor will use this pointer directly instead of allocating a buffer. Both this port and the connected output port will map to the supplied device pointer.

This overload is applied in overload resolution when the second argument is of type CUdeviceptr or void*.

Template Parameters

T – The device pointer type (CUdeviceptr or void*).

Parameters

• name – The name of the input specification.

• device_ptr – The device pointer for the input specification (must be non-null).

Returns

The reference to the input specification.

inline std::unordered_map<std::string, std::shared_ptr<IOSpec>> &outputs()

Get output specifications of this operator.

Returns

The reference to the output specifications of this operator.

const std::string &input_output_unique_id(const std::string &name) const

Return the unique_id for a port name by checking inputs first, then outputs.

If a port with the same name exists in both inputs and outputs, an exception is thrown. If the port does not exist in either, an exception is thrown.

Parameters

name – The port name to look up.

Returns

const std::string& The unique_id corresponding to the found port.

template<typename DataT>
inline IOSpec &output()

Define an output specification for this operator.

Template Parameters

DataT – The type of the output data.

Returns

The reference to the output specification.

template<typename DataT>
inline IOSpec &output(std::string name, IOSpec::IOSize size = IOSpec::kSizeOne, std::optional<IOSpec::QueuePolicy> policy = std::nullopt)

Define an output specification for this operator.

Note: The ‘policy’ parameter controls the queue’s behavior if a message is emitted when the output queue is already full. The possible policies are:

• IOSpec::QueuePolicy::kPop - Replace the oldest message in the queue with the new one.

• IOSpec::QueuePolicy::kReject - Reject (discard) the new message.

• IOSpec::QueuePolicy::kFault - Log a warning and reject the new item.

Template Parameters

DataT – The type of the output data.

Parameters

• name – The name of the output specification.

• size – The size of the queue for the output port.

• policy – The queue policy used for the output port.

Returns

The reference to the output specification.

template<typename DataT>
inline IOSpec &output(std::string name, std::optional<IOSpec::QueuePolicy> policy)

Define an output specification for this operator.

Template Parameters

DataT – The type of the output data.

Parameters

• name – The name of the output specification.

• policy – The queue policy used for the output port.

Returns

The reference to the output specification.

inline IOSpec &device_output(std::string name, size_t memory_block_size)

Define an output specification for this operator with a memory block size. It is only applicable for GPU-resident operators.

The executor will allocate a shared device memory buffer of the specified size for this port and the connected input port. Both ports will map to the same device memory address. Integer literals (e.g. 0, 1024) and size_t values resolve to this overload.

Parameters

• name – The name of the output specification.

• memory_block_size – The device memory block size in bytes.

Returns

The reference to the output specification.

template<typename T>
inline std::enable_if_t<std::is_same_v<std::decay_t<T>, CUdeviceptr> || std::is_same_v<std::decay_t<T>, void*>, IOSpec&> device_output(std::string name, T device_ptr)

Define an output specification for this operator with an externally managed device pointer. It is only applicable for GPU-resident operators.

Use this overload when the operator allocates and manages its own device memory (e.g. via cudaMalloc). The executor will use this pointer directly instead of allocating a buffer. Both this port and the connected input port will map to the supplied device pointer.

This overload is applied in overload resolution when the second argument is of type CUdeviceptr or void*.

Template Parameters

T – The device pointer type (CUdeviceptr or void*).

Parameters

• name – The name of the output specification.

• device_ptr – The device pointer for the output specification (must be non-null).

Returns

The reference to the output specification.

inline void param(Parameter<holoscan::IOSpec*> &parameter, const char *key, const char *headline, const char *description, ParameterFlag flag = ParameterFlag::kNone)

Define an IOSpec* parameter for this operator.

Parameters

• parameter – The parameter to define.

• key – The key (name) of the parameter.

• headline – The headline of the parameter.

• description – The description of the parameter.

• flag – The flag of the parameter (default: ParameterFlag::kNone).

inline void param(Parameter<holoscan::IOSpec*> &parameter, const char *key, const char *headline, const char *description, std::initializer_list<void*> init_list)

Define an IOSpec* parameter for this operator.

This method is to catch the following case:

Copy

Copied!

            

            
...
    spec.param(iospec1_, "iospec1", "IO Spec", "Example IO Spec.", {});
...
private:
 Parameter<holoscan::IOSpec*> iospec1_;
        

Otherwise, {} will be treated as ParameterFlag::kNone instead of std::initializer_list.

Parameters

• parameter – The parameter to define.

• key – The key (name) of the parameter.

• headline – The headline of the parameter.

• description – The description of the parameter.

• init_list – The initializer list of the parameter.

inline void param(Parameter<holoscan::IOSpec*> &parameter, const char *key, const char *headline, const char *description, holoscan::IOSpec *default_value, ParameterFlag flag = ParameterFlag::kNone)

Define an IOSpec* parameter with a default value for this operator.

Parameters

• parameter – The parameter to define.

• key – The key (name) of the parameter.

• headline – The headline of the parameter.

• description – The description of the parameter.

• default_value – The default value of the parameter.

• flag – The flag of the parameter (default: ParameterFlag::kNone).

inline void param(Parameter<std::vector<holoscan::IOSpec*>> &parameter, const char *key, const char *headline, const char *description, ParameterFlag flag = ParameterFlag::kNone)

Define a IOSpec* vector parameter for this operator.

Parameters

• parameter – The parameter to define.

• key – The key (name) of the parameter.

• headline – The headline of the parameter.

• description – The description of the parameter.

• flag – The flag of the parameter (default: ParameterFlag::kNone).

inline void param(Parameter<std::vector<holoscan::IOSpec*>> &parameter, const char *key, const char *headline, const char *description, std::initializer_list<holoscan::IOSpec*> init_list)

Define a IOSpec* vector parameter for this operator.

This method is to catch the following case:

Copy

Copied!

            

            
...
    spec.param(iospec1_, "iospec1", "IO Spec", "Example IO Spec.", {});
...
private:
 Parameter<std::vector<holoscan::IOSpec*>> iospec1_;
        

Otherwise, {} will be treated as ParameterFlag::kNone instead of std::initializer_list.

Parameters

• parameter – The parameter to define.

• key – The key (name) of the parameter.

• headline – The headline of the parameter.

• description – The description of the parameter.

• init_list – The initializer list of the parameter.

inline void param(Parameter<std::vector<holoscan::IOSpec*>> &parameter, const char *key, const char *headline, const char *description, const std::vector<holoscan::IOSpec*> &default_value, ParameterFlag flag = ParameterFlag::kNone)

Define an IOSpec* parameter with a default value for this operator.

Parameters

• parameter – The parameter to define.

• key – The key (name) of the parameter.

• headline – The headline of the parameter.

• description – The description of the parameter.

• default_value – The default value of the parameter.

• flag – The flag of the parameter (default: ParameterFlag::kNone).

virtual YAML::Node to_yaml_node() const override

Get a YAML representation of the operator spec.

Returns

YAML node including the inputs, outputs, and parameters of this operator.

template<typename typeT>
inline void param(Parameter<typeT> &parameter, const char *key, ParameterFlag flag = ParameterFlag::kNone)

Define a parameter for this component.

Template Parameters

typeT – The type of the parameter.

Parameters

• parameter – The parameter to define.

• key – The key (name) of the parameter.

• flag – The flag of the parameter (default: ParameterFlag::kNone).

template<typename typeT>
inline void param(Parameter<typeT> &parameter, const char *key, const char *headline, ParameterFlag flag = ParameterFlag::kNone)

Define a parameter for this component.

Template Parameters

typeT – The type of the parameter.

Parameters

• parameter – The parameter to define.

• key – The key (name) of the parameter.

• headline – The headline of the parameter.

• flag – The flag of the parameter (default: ParameterFlag::kNone).

template<typename typeT>
void param(Parameter<typeT> &parameter, const char *key, const char *headline, const char *description, ParameterFlag flag = ParameterFlag::kNone)

Define a parameter for this component.

Template Parameters

typeT – The type of the parameter.

Parameters

• parameter – The parameter to define.

• key – The key (name) of the parameter.

• headline – The headline of the parameter.

• description – The description of the parameter.

• flag – The flag of the parameter (default: ParameterFlag::kNone).

template<typename typeT>
void param(Parameter<typeT> &parameter, const char *key, const char *headline, const char *description, std::initializer_list<void*> init_list)

Define a parameter for this component.

This method is to catch the following case:

Copy

Copied!

            

            
...
    spec.param(int64_value_, "int64_param", "int64_t param", "Example int64_t parameter.", {});
...
private:
 Parameter<int64_t> int64_param_;
        

Otherwise, {} will be treated as ParameterFlag::kNone instead of std::initializer_list.

Template Parameters

typeT – The type of the parameter.

Parameters

• parameter – The parameter to define.

• key – The key (name) of the parameter.

• headline – The headline of the parameter.

• description – The description of the parameter.

• init_list – The initializer list of the parameter.

template<typename typeT>
void param(Parameter<typeT> &parameter, const char *key, const char *headline, const char *description, const typeT &default_value, ParameterFlag flag = ParameterFlag::kNone)

Define a parameter that has a default value.

Template Parameters

typeT – The type of the parameter.

Parameters

• parameter – The parameter to get.

• key – The key (name) of the parameter.

• headline – The headline of the parameter.

• description – The description of the parameter.

• default_value – The default value of the parameter.

• flag – The flag of the parameter (default: ParameterFlag::kNone).

template<typename typeT>
void param(Parameter<typeT> &parameter, const char *key, const char *headline, const char *description, typeT &&default_value, ParameterFlag flag = ParameterFlag::kNone)

Define a parameter that has a default value.

Template Parameters

typeT – The type of the parameter.

Parameters

• parameter – The parameter to get.

• key – The key (name) of the parameter.

• headline – The headline of the parameter.

• description – The description of the parameter.

• default_value – The default value of the parameter.

• flag – The flag of the parameter (default: ParameterFlag::kNone).

Protected Attributes

std::unordered_map<std::string, std::shared_ptr<IOSpec>> inputs_

Input specs.

std::unordered_map<std::string, std::shared_ptr<IOSpec>> outputs_

Outputs specs.

std::vector<MultiMessageConditionInfo> multi_port_conditions_

std::vector<std::vector<std::string>> or_combiner_port_names_

std::list<Parameter<std::vector<IOSpec*>>> receivers_params_

Container for receivers parameters.