API referenceC++ APIClasses

holoscan::IOSpec

Beta
View as Markdown

Class to define the specification of an input/output port of an Operator.

An interaction point between two operators. Operators ingest data at Input ports and publish data at Output ports. Receiver, Transmitter, and MessageRouter in GXF would be replaced with the concept of Input/Output Port of the Operator and the Flow (Edge) of the Application Workflow in the Framework.

#include <holoscan/io_spec.hpp>

Constructors

IOSpec

holoscan::IOSpec::IOSpec(
    OperatorSpec *op_spec,
    const std::string &name,
    IOType io_type,
    const std::type_info *typeinfo = &typeid(void *),
    IOSpec::IOSize size = IOSpec::kSizeOne,
    std::optional<IOSpec::QueuePolicy> policy = std::nullopt
)

Construct a new IOSpec object.

Parameters

op_spec
OperatorSpec *

The pointer to the operator specification that contains this input/output.

name
const std::string &

The name of this input/output.

io_type
IOType

The type of this input/output.

typeinfo
const std::type_info *Defaults to &typeid(void *)

The type info of the data of this input/output.

size
IOSpec::IOSizeDefaults to IOSpec::kSizeOne

The size of the input/output queue.

policy
std::optional<IOSpec::QueuePolicy>Defaults to std::nullopt

The queue policy (optional).

Destructor

~IOSpec

virtual holoscan::IOSpec::~IOSpec() = default

Methods

op_spec

OperatorSpec * holoscan::IOSpec::op_spec() const

Get the operator specification that contains this input/output.

Returns: The pointer to the operator specification that contains this input/output.

name

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

Get the name of this input/output.

Returns: The name of this input/output.

io_type

IOType holoscan::IOSpec::io_type() const

Get the input/output type.

Returns: The input/output type.

connector_type

ConnectorType holoscan::IOSpec::connector_type() const

Get the receiver/transmitter type.

Returns: The receiver type (for inputs) or transmitter type (for outputs)

typeinfo

const std::type_info * holoscan::IOSpec::typeinfo() const

Get the type info of the data of this input/output.

Returns: The type info of the data of this input/output.

memory_block_size

size_t holoscan::IOSpec::memory_block_size() const

Get the memory block size of this input/output.

Returns: The memory block size of this input/output.

device_ptr

void * holoscan::IOSpec::device_ptr() const

Get the device pointer of this input/output.

Returns: The device pointer of this input/output.

conditions

std::vector<std::pair<ConditionType, std::shared_ptr<Condition>>> & holoscan::IOSpec::conditions()

Get the conditions of this input/output.

Returns: The reference to the conditions of this input/output.

condition

template <typename... ArgsT>
IOSpec & holoscan::IOSpec::condition(
    ConditionType type,
    ArgsT &&... args
)

Add a condition to this input/output.

The following ConditionTypes are supported:

  • ConditionType::kMessageAvailable
  • ConditionType::kExpiringMessageAvailable
  • ConditionType::kDownstreamAffordable
  • ConditionType::kMultiMessageAvailableTimeout
  • ConditionType::kNone

Returns: The reference to this IOSpec.

Parameters

type
ConditionType

The type of the condition.

args
ArgsT &&...

The arguments of the condition.

connector

const
std::shared_ptr<Resource> holoscan::IOSpec::connector() const

Get the connector (transmitter or receiver) of this input/output.

Returns: The connector (transmitter or receiver) of this input/output.

topic

IOSpec & holoscan::IOSpec::topic(
    const std::string &name,
    bool replace_connector = false
)

Set a topic name for this port (Publish/Subscribe connectors only).

If the connector type is kDefault, it is automatically changed to kPubSub and the topic is applied. If the connector type is already kPubSub, the topic is set on the existing connector. For any other connector type (e.g. kUCX, kDoubleBuffer), a warning is logged and the topic is ignored unless replace_connector is true, in which case the existing connector is replaced with a Pub/Sub connector.

When both publisher and subscriber use the same topic, add_flow() is optional; add_operator() for each is sufficient — Pub/Sub backend discovery matches by topic.

Returns: Reference to this IOSpec.

Parameters

name
const std::string &

Topic name (must match between publisher and subscriber ports).

replace_connector
boolDefaults to false

If true, explicitly non-PubSub connectors are replaced with a Pub/Sub connector for this port.

qos

IOSpec & holoscan::IOSpec::qos(
    const nvidia::gxf::QoSProfile &profile
)

Set a QoS profile for this port (Publish/Subscribe connectors only).

Uses the backend-independent nvidia::gxf::QoSProfile struct. Named presets (e.g. QoSProfile::SensorData(), QoSProfile::Reliable()) and the fluent builder API are both supported.

If the connector type is kDefault, it is automatically changed to kPubSub and the QoS is applied. If the connector type is already kPubSub, the QoS is set on the existing connector. For any other connector type, a warning is logged and the QoS is ignored.

Example:

The DDS backend maps QoSProfile through dds_qos_profiles.hpp. Other backends (e.g. Zenoh, UCX) would map the same struct to their own QoS mechanisms.

Returns: Reference to this IOSpec.

Parameters

profile
const nvidia::gxf::QoSProfile &

The QoS profile to apply.

Example

void setup(OperatorSpec& spec) override {
  spec.output<MyType>("out")
      .topic("sensor_data")
      .qos(nvidia::gxf::QoSProfile::SensorData());
  spec.input<MyType>("in")
      .topic("sensor_data")
      .qos(nvidia::gxf::QoSProfile::SensorData());
}

queue_size

IOSpec & holoscan::IOSpec::queue_size(
    int64_t size
)

Set the queue size of the input/output port.

Note: This value is only used for initializing input ports. ‘queue_size_’ is set by the ‘OperatorSpec::input()’ method or this 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 queue_size/size to control queue capacity only; setting min_size explicitly now will make future migration straightforward.

Returns: The reference to this IOSpec.

Parameters

size
int64_t

The queue size of the input/output port.

queue_policy

IOSpec & holoscan::IOSpec::queue_policy(
    IOSpec::QueuePolicy policy
)

Set the queue policy of the input/output port.

Note: This value is only used for initializing input and output ports. ‘queue_policy_’ is set by the ‘OperatorSpec::input()’, ‘OperatorSpec::output()’ or ‘IOSpec::queue_policy’ method.

The following IOSpec::QueuePolicy values are supported:

  • QueuePolicy::kPop - If the queue is full, pop the oldest item, then add the new one.
  • QueuePolicy::kReject - If the queue is full, reject (discard) the new item.
  • QueuePolicy::kFault - If the queue is full, log a warning and reject the new item.

Returns: The reference to this IOSpec.

Parameters

policy
IOSpec::QueuePolicy

The queue policy of the input/output port.

to_yaml_node

virtual YAML::Node holoscan::IOSpec::to_yaml_node() const

Get a YAML representation of the IOSpec.

Returns: YAML node including the parameters of this component.

description

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

Get a description of the IOSpec.

Returns: YAML string.

See also: to_yaml_node()

unique_id

const std::string & holoscan::IOSpec::unique_id() const

Get the unique identifier for this IOSpec.

The unique identifier follows the pattern: “{operator.qualified_name()}.{port_name}” This is used for data logging and identification purposes. The unique_id is set during operator initialization.

Returns: The unique identifier string.

set_unique_id

void holoscan::IOSpec::set_unique_id(
    const std::string &unique_id
)

Set the unique identifier for this IOSpec.

This method is called during operator initialization to set the unique identifier.

Parameters

unique_id
const std::string &

The unique identifier string to set.

Types

IOType

Input/Output type.

NameValueDescription
kInput
kOutput

ConnectorType

Connector type.

NameValueDescription
kDefault
kDoubleBuffer
kAsyncBuffer
kUCX
kPubSub

QueuePolicy

Enum class representing the policy for handling queue operations.

NameValueDescription
kPop= 0Policy to pop the oldest item in the queue so the new item can be added.
kReject= 1Policy to reject the incoming item.
kFault= 2Policy to log a warning and reject the new item if the queue is full.

Member variables

NameTypeDescription
kAnySize staticconst IOSizeAny size.
kPrecedingCount staticconst IOSize
kSizeOne staticconst IOSizeSize one.
op_spec_OperatorSpec *
name_std::string
io_type_IOType
typeinfo_const std::type_info *
connector_std::shared_ptr< Resource >
conditions_std::vector< std::pair< ConditionType, std::shared_ptr< Condition > > >
connector_type_ConnectorType
queue_size_IOSize
queue_policy_std::optional< QueuePolicy >
memory_block_size_size_t
device_ptr_void *
unique_id_std::string

Inner classes

IOSize

class holoscan::IOSpec::IOSize

Input/Output size.

NameTypeDescription
size_int64_t