Class IOSpec

• Defined in File io_spec.hpp

Nested Types

• Class IOSpec::IOSize

class IOSpec

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.

Public Types

enum class IOType

Input/Output type.

Values:

enumerator kInput

enumerator kOutput

enum class ConnectorType

Connector type. Determines the type of Receiver (when IOType is kInput) or Transmitter (when IOType is kOutput) class used.

Values:

enumerator kDefault

enumerator kDoubleBuffer

enumerator kAsyncBuffer

enumerator kUCX

enum class QueuePolicy : uint8_t

Enum class representing the policy for handling queue operations.

This enum class defines the different policies that can be applied to queue operations when a queue is full.

Values:

enumerator kPop

Policy to pop the oldest item in the queue so the new item can be added.

enumerator kReject

Policy to reject the incoming item.

enumerator kFault

Policy to log a warning and reject the new item if the queue is full.

Public Functions

virtual ~IOSpec() = default

inline 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 – The pointer to the operator specification that contains this input/output.

• name – The name of this input/output.

• io_type – The type of this input/output.

• typeinfo – The type info of the data of this input/output.

• size – The size of the input/output queue.

• policy – The queue policy (optional).

inline OperatorSpec *op_spec() const

Get the operator specification that contains this input/output.

Returns

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

inline const std::string &name() const

Get the name of this input/output.

Returns

The name of this input/output.

inline IOType io_type() const

Get the input/output type.

Returns

The input/output type.

inline ConnectorType connector_type() const

Get the receiver/transmitter type.

Returns

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

inline const std::type_info *typeinfo() const

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

Returns

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

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

Get the conditions of this input/output.

Returns

The reference to the conditions of this input/output.

template<typename ...ArgsT>
inline 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

Parameters

• type – The type of the condition.

• args – The arguments of the condition.

Returns

The reference to this IOSpec.

inline std::shared_ptr<Resource> connector() const

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

Returns

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

inline void connector(std::shared_ptr<Resource> connector)

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

Parameters

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

template<typename ...ArgsT>
inline 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 or DoubleBufferTransmitter for with-fragment connections, but UcxReceiver or 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.

Parameters

• type – The type of the connector (receiver/transmitter).

• args – The arguments of the connector (receiver/transmitter).

Returns

The reference to this IOSpec.

inline int64_t 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) will use the queue size for initialization (‘capacity’ for the connector and ‘min_size’ for the condition) if they are not set.

Returns

The queue size of the input/output port.

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

Parameters

size – The queue size of the input/output port.

Returns

The reference to this IOSpec.

inline std::optional<IOSpec::QueuePolicy> 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’ method.

Returns

The queue policy of the input/output port.

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

Parameters

policy – The queue policy of the input/output port.

Returns

The reference to this IOSpec.

virtual YAML::Node to_yaml_node() const

Get a YAML representation of the IOSpec.

Returns

YAML node including the parameters of this component.

std::string description() const

Get a description of the IOSpec.

See also

to_yaml_node()

Returns

YAML string.

inline const std::string &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.

inline void 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 – The unique identifier string to set.

Public Static Attributes

static const IOSize kAnySize = IOSize{-1}

Any size.

static const IOSize kPrecedingCount = IOSize{0}

of preceding connections

static const IOSize kSizeOne = IOSize{1}

Size one.

class IOSize

Input/Output size.

Public Functions

inline explicit IOSize(int64_t size = 0)

Construct a new IOSize object.

Parameters

size – The size of the input/output.

inline void size(int64_t size)

Set the size of the input/output.

Parameters

size – The new size of the input/output.

inline int64_t size() const

Get the size of the input/output.

Returns

The size of the input/output.

inline operator int64_t() const

Cast the IOSize to int64_t.

Returns

The size of the input/output.