holoscan::InputContext

Beta

Class to hold the input context.

This class provides the interface to receive the input data from the operator.

#include <holoscan/io_context.hpp>

Constructors

InputContext

Construct a new `InputContext` object (with inputs)

Construct a new `InputContext` object

holoscan::InputContext::InputContext(holoscan::InputContext::InputContext(
    ExecutionContext *execution_context,
    Operator *op,
    std::unordered_map<std::string, std::shared_ptr<IOSpec>> &inputs
)

Construct a new InputContext object.

Parameters

execution_context

ExecutionContext *

The pointer to the execution context.

Operator *

The pointer to the operator that this context is associated with.

inputs

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

The references to the map of the input specs.

Destructor

~InputContext

virtual holoscan::InputContext::~InputContext() = defaultvirtual holoscan::InputContext::~InputContext() = default

Methods

execution_context

ExecutionContext * holoscan::InputContext::execution_context() constExecutionContext * holoscan::InputContext::execution_context() const

Get pointer to the execution context.

Returns: The pointer to the execution context.

op

Operator * holoscan::InputContext::op() constOperator * holoscan::InputContext::op() const

Return the operator that this context is associated with.

Returns: The pointer to the operator.

inputs

std::unordered_map<std::string, std::shared_ptr<IOSpec>> & holoscan::InputContext::inputs() conststd::unordered_map<std::string, std::shared_ptr<IOSpec>> & holoscan::InputContext::inputs() const

Return the reference to the map of the input specs.

Returns: The reference to the map of the input specs.

empty

bool holoscan::InputContext::empty(
    const char *name = nullptr
)

Return whether the input port has any data.

For parameters with std::vector<IOSpec*> type, if all the inputs are empty, it will return true. Otherwise, it will return false.

Returns: True, if it has no data, otherwise false.

Parameters

name

const char *Defaults to nullptr

The name of the input port to check.

reset_acquisition_timestamps

void holoscan::InputContext::reset_acquisition_timestamps()

Reset acquisition timestamp map values to std::nullopt for all input ports.

This method should be called before each compute call to reset the timestamp values while preserving the pre-initialized map structure for performance.

get_acquisition_timestamp

std::optional<int64_t> holoscan::InputContext::get_acquisition_timestamp(
    const char *input_port_name = nullptr
)

Get the acquisition timestamp for a given input port.

Returns: The acquisition timestamp. If no timestamp was published by the upstream operator, std::nullopt is returned.

Parameters

input_port_name

const char *Defaults to nullptr

The name of the input port.

get_acquisition_timestamps

std::vector<std::optional<int64_t>> holoscan::InputContext::get_acquisition_timestamps(
    const char *input_port_name = nullptr
)

Get all acquisition timestamp for a given input port.

For a port with queue size not equal to one (e.g. an IOSpec::kAnySize connection) there may be multiple messages in a queue, each with its own acquisition timestamp. This method returns a vector of std::optional<int64_t> where the length of the vector is the same as the number of messages received on that port.

Returns: The acquisition timestamps. Values of std::nullopt in the vector indicate that the corresponding message did not contain a timestamp.

Parameters

input_port_name

const char *Defaults to nullptr

The name of the input port.

receive

template <typename DataT>
holoscan::expected<DataT, holoscan::RuntimeError> holoscan::InputContext::receive(holoscan::expected<DataT, holoscan::RuntimeError> holoscan::InputContext::receive(
    const char *name = nullptr
)

Receive a message from the input port with the given name.

If the operator has a single input port, the name of the input port can be omitted.

If the input port with the given name and type (DataT) is available, it will return the data from the input port. Otherwise, it will return an object of the holoscan::unexpected class which will contain the error message. The error message can be access by calling the what() method of the holoscan::unexpected object.

It throws an invalid argument exception if the operator attempts to receive non-vector data (op_input.receive<T>()) from an input port with a queue size of IOSpec::kAnySize.

Example:

Returns: The received data.

Template parameters

DataT

typename

The type of the data to receive.

Parameters

name

const char *Defaults to nullptr

The name of the input port to receive the data from.

Example

class PingRxOp : public holoscan::ops::GXFOperator {
 public:
  HOLOSCAN_OPERATOR_FORWARD_ARGS_SUPER(PingRxOp, holoscan::ops::GXFOperator)
  PingRxOp() = default;
  void setup(OperatorSpec& spec) override {
    spec.input<std::shared_ptr<ValueData>>("in");
  }
  void compute(InputContext& op_input, [[maybe_unused]] OutputContext& op_output,
               [[maybe_unused]] ExecutionContext& context) override {
    auto value = op_input.receive<std::shared_ptr<ValueData>>("in");
    if (value.has_value()) {
      HOLOSCAN_LOG_INFO("Message received (value: {})", value->data());
    }
  }
};

cuda_object_handler

Overload 1

Overload 2

std::shared_ptr<CudaObjectHandler> holoscan::InputContext::cuda_object_handler()std::shared_ptr<CudaObjectHandler> holoscan::InputContext::cuda_object_handler()

Get the CUDA stream/event handler used by this input context.

This CudaObjectHandler class is designed primarily for internal use and is not guaranteed to have a stable API. Application authors should instead rely on the public receive_cuda_stream and receive_cuda_streams methods.

receive_cuda_stream

virtual cudaStream_t holoscan::InputContext::receive_cuda_stream(
    const char *input_port_name = nullptr,
    bool allocate = true,
    bool sync_to_default = false
)

Get the operator’s internal CUDA stream, synchronizing any upstream streams to it.

This is the recommended method for stream handling in most operators. It performs several operations:

Synchronizes upstream streams to the operator’s internal stream using non-blocking CUDA events (cudaEventRecord / cudaStreamWaitEvent). This ensures upstream GPU work completes before this operator’s work begins, without blocking the CPU.
Sets the CUDA device (cudaSetDevice) to match the internal stream’s device.
Configures all output ports to automatically emit the internal stream ID when emit() is called.
Returns the internal cudaStream_t for use in kernels and async memory operations.

If no CudaStreamPool resource was available on the operator, the operator will not have an internal stream. In that case, the first stream received on the input port will be returned and any additional streams on the input will have been synchronized to it. If no streams were found on the input and no CudaStreamPool resource was available, cudaStreamDefault is returned.

The receive() method must be called for input_port_name before calling this method. The receive() call captures stream IDs from incoming messages.

Returns: The operator’s internal CUDA stream (reused across all compute() calls). Returns cudaStreamDefault if no stream pool was available and no stream was found on the input port.

Parameters

input_port_name

const char *Defaults to nullptr

The name of the input port. Can be omitted if the operator only has a single input port.

allocate

boolDefaults to true

Whether to allocate an internal stream if not already allocated. If false or no CudaStreamPool is available, the first received stream is used as the internal stream.

sync_to_default

boolDefaults to false

Whether to also synchronize the internal stream to cudaStreamDefault.

receive_cuda_streams

virtual std::vector<std::optional<cudaStream_t>> holoscan::InputContext::receive_cuda_streams(
    const char *input_port_name = nullptr
)

Retrieve the CUDA streams found on an input port (advanced use).

Unlike receive_cuda_stream, this method does not perform any synchronization, does not allocate an internal stream, does not set the CUDA device, and does not configure output ports. It simply returns the raw stream information found in the received messages.

This method is intended for advanced use cases where manual stream management is required. For most operators, use receive_cuda_stream instead.

The receive() method must be called for input_port_name before calling this method. The receive() call captures stream IDs from incoming messages.

Returns: Vector of (optional) cudaStream_t. In normal operation, the length of the vector matches the number of messages on the input port, with std::nullopt for messages without a stream. If stream handling is unavailable (e.g., CudaObjectHandler not initialized), an empty vector is returned.

Parameters

input_port_name

const char *Defaults to nullptr

The name of the input port. Can be omitted if the operator only has a single input port.

empty_impl

virtual bool holoscan::InputContext::empty_impl(
    const char *name = nullptr
)

The implementation of the empty method.

Returns: True if the input port is empty or by default. Otherwise, false.

Parameters

name

const char *Defaults to nullptr

The name of the input port

receive_impl

virtual std::any holoscan::InputContext::receive_impl(
    const char *name = nullptr,
    InputType in_type = InputType::kAny,
    bool no_error_message = false,
    bool omit_data_logging = false,
    bool allow_any_size = false
)

The implementation of the receive method.

Depending on the type of the data, this method receives a message from the input port with the given name.

Returns: The data received from the input port.

Parameters

name

const char *Defaults to nullptr

The name of the input port.

in_type

InputTypeDefaults to InputType::kAny

The input type (kGXFEntity or kAny).

no_error_message

boolDefaults to false

Whether to print an error message when the input port is not found.

omit_data_logging

boolDefaults to false

Whether any calls to log_backend_specific should be skipped. Currently used to avoid duplication of logging of TensorMap contents.

is_valid_param_type

bool holoscan::InputContext::is_valid_param_type(
    const ArgType &arg_type
)

any_size_param_count

std::optional<size_t> holoscan::InputContext::any_size_param_count(
    ParameterWrapper &param_wrapper
)

should_fallback_to_direct_any_size_input

bool holoscan::InputContext::should_fallback_to_direct_any_size_input(
    ParameterWrapper &param_wrapper,
    const std::string &input_name
)

fill_input_vector_from_params

template <typename DataT>
bool holoscan::InputContext::fill_input_vector_from_params(
    ParameterWrapper &param_wrapper,
    const char *name,
    DataT &input_vector,
    InputType in_type,
    std::string &error_message
)

fill_input_vector_from_inputs

template <typename DataT>
bool holoscan::InputContext::fill_input_vector_from_inputs(
    const char *name,
    DataT &input_vector,
    InputType in_type,
    std::string &error_message
)

get_unique_id

std::string holoscan::InputContext::get_unique_id(
    Operator *op,
    const std::string &port_name
)

log_tensor

bool holoscan::InputContext::log_tensor(
    const std::shared_ptr<Tensor> &tensor,
    const char *port_name
)

log_tensormap

bool holoscan::InputContext::log_tensormap(
    const holoscan::TensorMap &tensor_map,
    const char *port_name
)

populate_tensor_map

bool holoscan::InputContext::populate_tensor_map(
    const holoscan::gxf::Entity &gxf_entity,
    holoscan::TensorMap &tensor_map,
    const char *port_name
)

process_received_value

template <typename DataT>
bool holoscan::InputContext::process_received_value(
    std::any &value,
    const std::type_info &value_type,
    const char *port_name,
    DataT &input_vector,
    std::string &error_message
)

handle_null_value

Overload 1

Overload 2

template <typename DataT>
void holoscan::InputContext::handle_null_value(
    DataT &input_vector
)

handle_bad_any_cast

template <typename DataT>
bool holoscan::InputContext::handle_bad_any_cast(
    std::any &value,
    const char *port_name,
    DataT &input_vector,
    std::string &error_message
)

receive_single_value

template <typename DataT>
holoscan::expected<DataT, holoscan::RuntimeError> holoscan::InputContext::receive_single_value(holoscan::expected<DataT, holoscan::RuntimeError> holoscan::InputContext::receive_single_value(
    const char *name,
    InputType in_type,
    bool omit_tensormap_logging = false
)

create_receive_error

holoscan::RuntimeError holoscan::InputContext::create_receive_error(holoscan::RuntimeError holoscan::InputContext::create_receive_error(
    const char *name,
    const char *message
)

prepopulate_acquisition_timestamp_map

void holoscan::InputContext::prepopulate_acquisition_timestamp_map()

get_first_stream_for_logging

std::optional<cudaStream_t> holoscan::InputContext::get_first_stream_for_logging(
    const char *port_name
)

Helper to extract the first received CUDA stream for logging.

Returns: The first CUDA stream if available, std::nullopt otherwise

Parameters

port_name

const char *

The name of the input port

Types

InputType

The input data type.

Name	Value	Description
`kGXFEntity`		The message data to receive is a GXF entity.
`kAny`		The message data to receive is a std::any.

Member variables

Name	Type	Description
`execution_context_`	`ExecutionContext *`	The execution context that is associated with.
`op_`	`Operator *`	The operator that this context is associated with.
`inputs_`	`std::unordered_map< std::string, std::shared_ptr< IOSpec > > &`	The inputs.
`cuda_object_handler_`	`std::shared_ptr< CudaObjectHandler >`
`acquisition_timestamp_map_`	`std::map< std::string, std::vector< std::optional< int64_t > > >`

Constructors

InputContext

Construct a new InputContext object (with inputs)

Construct a new InputContext object

Destructor

~InputContext

Methods

execution_context

op

inputs

empty

reset_acquisition_timestamps

get_acquisition_timestamp

get_acquisition_timestamps

receive

cuda_object_handler

Overload 1

Overload 2

receive_cuda_stream

receive_cuda_streams

empty_impl

receive_impl

is_valid_param_type

any_size_param_count

should_fallback_to_direct_any_size_input

fill_input_vector_from_params

fill_input_vector_from_inputs

get_unique_id

log_tensor

log_tensormap

populate_tensor_map

process_received_value

handle_null_value

Overload 1

Overload 2

handle_bad_any_cast

receive_single_value

create_receive_error

prepopulate_acquisition_timestamp_map

get_first_stream_for_logging

Types

InputType

Member variables

Construct a new `InputContext` object (with inputs)

Construct a new `InputContext` object