> This page is for version 4.3.
> For other versions, use one of these documentation indexes:
> - 4.6 (Latest) (default): https://docs.nvidia.com/holoscan/sdk-user-guide/4-6-latest/llms.txt
> - ltsb-2.0: https://docs.nvidia.com/holoscan/sdk-user-guide/ltsb-2-0/llms.txt
> - 4.5: https://docs.nvidia.com/holoscan/sdk-user-guide/4-5/llms.txt
> - 4.4: https://docs.nvidia.com/holoscan/sdk-user-guide/4-4/llms.txt
> - 4.3: https://docs.nvidia.com/holoscan/sdk-user-guide/4-3/llms.txt
> - Archives: https://docs.nvidia.com/holoscan/sdk-user-guide/archives/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/holoscan/sdk-user-guide/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/holoscan/sdk-user-guide/_mcp/server.

# holoscan::IOSpec

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

Class to define the specification of an input/output port of an [Operator](operator).

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

```cpp showLineNumbers={false}
#include <holoscan/io_spec.hpp>
```

---

## Constructors

### IOSpec \[#iospec]

#### Construct a new \`IOSpec\` object

```cpp showLineNumbers={false}
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 *` — default: \&typeid(void \*)

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

---

**`size`** `IOSpec::IOSize` — default: IOSpec::kSizeOne

The size of the input/output queue.

---

**`policy`** `std::optional<IOSpec::QueuePolicy>` — default: std::nullopt

The queue policy (optional).

---

#### Overload 2

```cpp showLineNumbers={false}
holoscan::IOSpec::IOSpec(
    OperatorSpec *op_spec,
    const std::string &name,
    size_t memory_block_size,
    IOType io_type
)
```

Construct a new `IOSpec` object with memory block size.

This type of `IOSpec` is used for GPU-resident graph execution. We don't allow queue\_size or queue\_policy for this type of `IOSpec`.

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

---

**`memory_block_size`** `size_t`

The memory block size of this input/output.

---

**`io_type`** `IOType`

The type of this input/output.

---

#### Overload 3

```cpp showLineNumbers={false}
holoscan::IOSpec::IOSpec(
    OperatorSpec *op_spec,
    const std::string &name,
    void *device_ptr,
    IOType io_type
)
```

Construct a new `IOSpec` object with device pointer.

This type of `IOSpec` is used for GPU-resident graph execution when a memory block is allocated in a customized way by the operator. We don't allow queue\_size or queue\_policy for this type of `IOSpec`.

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

---

**`device_ptr`** `void *`

The device pointer for this input/output.

---

**`io_type`** `IOType`

The type of this input/output.

---

### Destructor \[#destructor]

### \~IOSpec

```cpp showLineNumbers={false}
virtual holoscan::IOSpec::~IOSpec() = default
```

---

## Methods

### op\_spec \[#opspec]

```cpp showLineNumbers={false}
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 \[#name]

```cpp showLineNumbers={false}
const std::string & holoscan::IOSpec::name() const
```

Get the name of this input/output.

**Returns:** The name of this input/output.

### io\_type \[#iotype]

```cpp showLineNumbers={false}
IOType holoscan::IOSpec::io_type() const
```

Get the input/output type.

**Returns:** The input/output type.

### connector\_type \[#connectortype]

```cpp showLineNumbers={false}
ConnectorType holoscan::IOSpec::connector_type() const
```

Get the receiver/transmitter type.

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

### typeinfo \[#typeinfo]

```cpp showLineNumbers={false}
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 \[#memoryblocksize]

```cpp showLineNumbers={false}
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 \[#deviceptr]

```cpp showLineNumbers={false}
void * holoscan::IOSpec::device_ptr() const
```

Get the device pointer of this input/output.

**Returns:** The device pointer of this input/output.

### conditions \[#conditions]

```cpp showLineNumbers={false}
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 \[#condition]

```cpp showLineNumbers={false}
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 \[#connector]

#### Const

const

```cpp showLineNumbers={false}
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.

#### Overload 2

```cpp showLineNumbers={false}
void holoscan::IOSpec::connector(
    std::shared_ptr<Resource> connector
)
```

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

**Parameters**

**`connector`** `std::shared_ptr<Resource>`

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

---

#### Overload 3

```cpp showLineNumbers={false}
template <typename... ArgsT>
IOSpec & holoscan::IOSpec::connector(
    ConnectorType type,
    ArgsT &&... args
)
```

Add a connector (receiver/transmitter) to this input/output.

The following ConnectorTypes are supported:

* ConnectorType::kDefault
* ConnectorType::kDoubleBuffer
* ConnectorType::kAsyncBuffer
* ConnectorType::kUCX

Note: Typically the application author does not need to call this method. The SDK will assign an appropriate transmitter or receiver type automatically (e.g. [DoubleBufferReceiver](doublebufferreceiver) or [DoubleBufferTransmitter](doublebuffertransmitter) for with-fragment connections, but [UcxReceiver](ucxreceiver) or [UcxTransmitter](ucxtransmitter) for intra-fragment connections in distributed applications). Similarly, annotated variants of these are used when data flow tracking is enabled.

Note: If you just want to keep the default transmitter or receiver class, but override the queue capacity or policy, it is easier to specify the `capacity` and/or `policy` arguments to `IOSpec::input` or `IOSpec::output` instead of using this method.

**Returns:** The reference to this `IOSpec`.

**Parameters**

**`type`** `ConnectorType`

The type of the connector (receiver/transmitter).

---

**`args`** `ArgsT &&...`

The arguments of the connector (receiver/transmitter).

---

### topic \[#topic]

#### Mutable

```cpp showLineNumbers={false}
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`** `bool` — default: false

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

---

#### Const

const

nodiscard

```cpp showLineNumbers={false}
std::optional<std::string> holoscan::IOSpec::topic() const
```

Get the currently configured topic name for this port, if any.

For Pub/Sub ports this returns the latest configured `topic_name` argument, including values supplied through `topic(...)` or direct Pub/Sub connector arguments.

**Returns:** Configured topic name, or `std::nullopt` if this port is not topic-mapped.

### qos \[#qos]

#### Mutable

```cpp showLineNumbers={false}
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**

```cpp showLineNumbers={false}
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());
}
```

#### Const

const

nodiscard

```cpp showLineNumbers={false}
std::optional<nvidia::gxf::QoSProfile> holoscan::IOSpec::qos() const
```

Get the explicitly configured QoS profile for this port, if any.

This reflects QoS applied through `qos(...)` or directly on the Pub/Sub connector resource. Callers that need the effective runtime QoS should fall back to `QoSProfile::Default()` when a topic is configured but no explicit QoS override exists.

**Returns:** Configured QoS profile, or `std::nullopt` if no explicit override is present.

### queue\_size \[#queuesize]

#### Mutable

```cpp showLineNumbers={false}
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](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](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`](#queuesize)/`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.

---

#### Const

const

```cpp showLineNumbers={false}
int64_t holoscan::IOSpec::queue_size() const
```

Get 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 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](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](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`](#queuesize)/`size` to control queue capacity only; setting `min_size` explicitly now will make future migration straightforward.

**Returns:** The queue size of the input/output port.

### queue\_policy \[#queuepolicy]

#### Mutable

```cpp showLineNumbers={false}
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](#queuepolicy)' 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.

---

#### Const

const

```cpp showLineNumbers={false}
std::optional<IOSpec::QueuePolicy> holoscan::IOSpec::queue_policy() const
```

Get 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](#queuepolicy)' method.

**Returns:** The queue policy of the input/output port.

### to\_yaml\_node \[#toyamlnode]

```cpp showLineNumbers={false}
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 \[#description]

```cpp showLineNumbers={false}
std::string holoscan::IOSpec::description() const
```

Get a description of the `IOSpec`.

**Returns:** `YAML` string.

**See also:**
to\_yaml\_node()

### unique\_id \[#uniqueid]

```cpp showLineNumbers={false}
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 \[#setuniqueid]

```cpp showLineNumbers={false}
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.

| Name      | Value | Description |
| --------- | ----- | ----------- |
| `kInput`  |       |             |
| `kOutput` |       |             |

### ConnectorType

Connector type.

| Name            | Value | Description |
| --------------- | ----- | ----------- |
| `kDefault`      |       |             |
| `kDoubleBuffer` |       |             |
| `kAsyncBuffer`  |       |             |
| `kUCX`          |       |             |
| `kPubSub`       |       |             |

### QueuePolicy

Enum class representing the policy for handling queue operations.

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

---

## Member variables

| Name                     | Type                                                                      | Description |
| ------------------------ | ------------------------------------------------------------------------- | ----------- |
| `kAnySize` static        | `const IOSize`                                                            | Any size.   |
| `kPrecedingCount` static | `const IOSize`                                                            |             |
| `kSizeOne` static        | `const IOSize`                                                            | Size 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

```cpp showLineNumbers={false}
class holoscan::IOSpec::IOSize
```

Input/Output size.

| Name    | Type      | Description |
| ------- | --------- | ----------- |
| `size_` | `int64_t` |             |