> 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::InputContext

> Class to hold the input context.

Class to hold the input context.

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

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

***

## Constructors

### InputContext \[#inputcontext]

#### Construct a new \`InputContext\` object (with inputs)

```cpp showLineNumbers={false}
holoscan::InputContext::InputContext(
    ExecutionContext *execution_context,
    Operator *op,
    std::unordered_map<std::string, std::shared_ptr<IOSpec>> &inputs
)
```

Construct a new `InputContext` object.

**Parameters**

The pointer to the execution context.

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

The references to the map of the input specs.

#### Construct a new \`InputContext\` object

```cpp showLineNumbers={false}
holoscan::InputContext::InputContext(
    ExecutionContext *execution_context,
    Operator *op
)
```

Construct a new `InputContext` object.

inputs for the `InputContext` will be set to op->spec()->inputs()

**Parameters**

The pointer to GXF execution runtime

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

### Destructor \[#destructor]

### \~InputContext

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

***

## Methods

### execution\_context \[#executioncontext]

```cpp showLineNumbers={false}
ExecutionContext * holoscan::InputContext::execution_context() const
```

Get pointer to the execution context.

**Returns:** The pointer to the execution context.

### op \[#op]

```cpp showLineNumbers={false}
Operator * holoscan::InputContext::op() const
```

Return the operator that this context is associated with.

**Returns:** The pointer to the operator.

### inputs \[#inputs]

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

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

The name of the input port to check.

### reset\_acquisition\_timestamps \[#resetacquisitiontimestamps]

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

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

The name of the input port.

### get\_acquisition\_timestamps \[#getacquisitiontimestamps]

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

The name of the input port.

### receive \[#receive]

```cpp showLineNumbers={false}
template <typename DataT>
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](../typedefs/unexpected) class which will contain the error message. The error message can be access by calling the `what()` method of the [holoscan::unexpected](../typedefs/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**

The type of the data to receive.

**Parameters**

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

**Example**

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

#### Overload 1

```cpp showLineNumbers={false}
std::shared_ptr<CudaObjectHandler> holoscan::InputContext::cuda_object_handler()
```

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

This [`CudaObjectHandler`](cudaobjecthandler) class is designed primarily for internal use and is not guaranteed to have a stable API. [Application](application) authors should instead rely on the public [`receive_cuda_stream`](#receivecudastream) and [`receive_cuda_streams`](#receivecudastreams) methods.

#### Overload 2

```cpp showLineNumbers={false}
void holoscan::InputContext::cuda_object_handler(
    std::shared_ptr<CudaObjectHandler> handler
)
```

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

### receive\_cuda\_stream \[#receivecudastream]

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

1. **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.
2. **Sets the CUDA device** (`cudaSetDevice`) to match the internal stream's device.
3. **Configures all output ports** to automatically emit the internal stream ID when `emit()` is called.
4. **Returns the internal cudaStream\_t** for use in kernels and async memory operations.

If no [`CudaStreamPool`](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`](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**

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

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

Whether to also synchronize the internal stream to `cudaStreamDefault`.

### receive\_cuda\_streams \[#receivecudastreams]

```cpp showLineNumbers={false}
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`](#receivecudastream), 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`](#receivecudastream) 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](../typedefs/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](cudaobjecthandler) not initialized), an empty vector is returned.

**Parameters**

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

### empty\_impl \[#emptyimpl]

```cpp showLineNumbers={false}
virtual bool holoscan::InputContext::empty_impl(
    const char *name = nullptr
)
```

The implementation of the [`empty`](#empty) method.

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

**Parameters**

The name of the input port

### receive\_impl \[#receiveimpl]

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

The name of the input port.

The input type (kGXFEntity or kAny).

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

Whether any calls to log\_backend\_specific should be skipped. Currently used to avoid duplication of logging of [TensorMap](tensormap) contents.

### is\_valid\_param\_type \[#isvalidparamtype]

```cpp showLineNumbers={false}
bool holoscan::InputContext::is_valid_param_type(
    const ArgType &arg_type
)
```

### any\_size\_param\_count \[#anysizeparamcount]

```cpp showLineNumbers={false}
std::optional<size_t> holoscan::InputContext::any_size_param_count(
    ParameterWrapper &param_wrapper
)
```

### should\_fallback\_to\_direct\_any\_size\_input \[#shouldfallbacktodirectanysizeinput]

```cpp showLineNumbers={false}
bool holoscan::InputContext::should_fallback_to_direct_any_size_input(
    ParameterWrapper &param_wrapper,
    const std::string &input_name
)
```

### fill\_input\_vector\_from\_params \[#fillinputvectorfromparams]

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

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

```cpp showLineNumbers={false}
std::string holoscan::InputContext::get_unique_id(
    Operator *op,
    const std::string &port_name
)
```

### log\_tensor \[#logtensor]

```cpp showLineNumbers={false}
bool holoscan::InputContext::log_tensor(
    const std::shared_ptr<Tensor> &tensor,
    const char *port_name
)
```

### log\_tensormap \[#logtensormap]

```cpp showLineNumbers={false}
bool holoscan::InputContext::log_tensormap(
    const holoscan::TensorMap &tensor_map,
    const char *port_name
)
```

### populate\_tensor\_map \[#populatetensormap]

```cpp showLineNumbers={false}
bool holoscan::InputContext::populate_tensor_map(
    const holoscan::gxf::Entity &gxf_entity,
    holoscan::TensorMap &tensor_map,
    const char *port_name
)
```

### process\_received\_value \[#processreceivedvalue]

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

#### Overload 1

```cpp showLineNumbers={false}
template <typename DataT>
void holoscan::InputContext::handle_null_value(
    DataT &input_vector
)
```

#### Overload 2

```cpp showLineNumbers={false}
template <typename DataT>
holoscan::expected<DataT, holoscan::RuntimeError> holoscan::InputContext::handle_null_value()
```

### handle\_bad\_any\_cast \[#handlebadanycast]

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

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

### create\_receive\_error \[#createreceiveerror]

```cpp showLineNumbers={false}
holoscan::RuntimeError holoscan::InputContext::create_receive_error(
    const char *name,
    const char *message
)
```

### prepopulate\_acquisition\_timestamp\_map \[#prepopulateacquisitiontimestampmap]

```cpp showLineNumbers={false}
void holoscan::InputContext::prepopulate_acquisition_timestamp_map()
```

### get\_first\_stream\_for\_logging \[#getfirststreamforlogging]

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

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 > > >` |                                                    |