> 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::gxf::GXFInputContext

> Class to hold the input context for a GXF Operator.

Class to hold the input context for a GXF [Operator](../../../classes/operator).

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

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

**Inherits from:** `holoscan::InputContext` (public)

---

## Constructors

### GXFInputContext \[#gxfinputcontext]

#### Construct a new \`GXFInputContext\` object

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

Construct a new `GXFInputContext` object.

**Parameters**

**`execution_context`** `ExecutionContext *`

The pointer to the execution context.

---

**`op`** `Operator *`

The pointer to the GXFOperator object.

---

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

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

Construct a new `GXFInputContext` object.

**Parameters**

**`execution_context`** `ExecutionContext *`

The pointer to the execution context.

---

**`op`** `Operator *`

The pointer to the GXFOperator object.

---

**`inputs`** `std::unordered_map<std::string, std::shared_ptr<IOSpec>> &`

Inputs The references to the map of the input specs.

---

---

## Methods

### gxf\_context \[#gxfcontext]

```cpp showLineNumbers={false}
gxf_context_t holoscan::gxf::GXFInputContext::gxf_context() const
```

Get a pointer to the GXF execution runtime.

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

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

```cpp showLineNumbers={false}
cudaStream_t holoscan::gxf::GXFInputContext::receive_cuda_stream(
    const char *input_port_name = nullptr,
    bool allocate = true,
    bool sync_to_default = false
) override
```

Synchronize any streams found on this port to the operator's internal CUDA stream.

The [`receive`](../../../classes/inputcontext#receive) method must have been called for `input_port_name` prior to calling this method in order for any received streams to be found. This method will call `cudaSetDevice` to make the device corresponding to the operator's internal stream current.

If no [`CudaStreamPool`](../../../classes/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`](../../../classes/cudastreampool) resource was available, `cudaStreamDefault` is returned.

**Returns:** The operator's internal CUDA stream, when possible. Returns `cudaStreamDefault` instead if no [CudaStreamPool](../../../classes/cudastreampool) resource was available and no stream was found on the input port.

**Parameters**

**`input_port_name`** `const char *` — default: nullptr

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

---

**`allocate`** `bool` — default: true

Whether to allocate a new stream if no stream is found. If false or the operator does not have a `cuda_stream_pool` parameter set, returns cudaStreamDefault.

---

**`sync_to_default`** `bool` — default: false

Whether to also synchronize any received streams to the default stream.

---

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

```cpp showLineNumbers={false}
std::vector<std::optional<cudaStream_t>> holoscan::gxf::GXFInputContext::receive_cuda_streams(
    const char *input_port_name = nullptr
) override
```

Retrieve the CUDA streams found on an input port.

This method is intended for advanced use cases where it is the users responsibility to manage any necessary stream synchronization. In most cases, it is recommended to use [`receive_cuda_stream`](#receivecudastream) instead.

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

**`input_port_name`** `const char *` — default: nullptr

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

---

### execution\_context \[#executioncontext]

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

Get pointer to the execution context.

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

### op \[#op]

```cpp showLineNumbers={false}
Operator * holoscan::gxf::GXFInputContext::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::gxf::GXFInputContext::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::gxf::GXFInputContext::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 *` — default: nullptr

The name of the input port to check.

---

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

```cpp showLineNumbers={false}
void holoscan::gxf::GXFInputContext::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::gxf::GXFInputContext::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 *` — default: nullptr

The name of the input port.

---

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

```cpp showLineNumbers={false}
std::vector<std::optional<int64_t>> holoscan::gxf::GXFInputContext::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 *` — default: nullptr

The name of the input port.

---

### receive \[#receive]

```cpp showLineNumbers={false}
template <typename DataT>
holoscan::expected<DataT, holoscan::RuntimeError> holoscan::gxf::GXFInputContext::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**

**`DataT`** `typename`

The type of the data to receive.

---

**Parameters**

**`name`** `const char *` — default: nullptr

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::gxf::GXFInputContext::cuda_object_handler()
```

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

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

#### Overload 2

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

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

### empty\_impl \[#emptyimpl]

```cpp showLineNumbers={false}
bool holoscan::gxf::GXFInputContext::empty_impl(
    const char *name = nullptr
) override
```

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

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

**Parameters**

**`name`** `const char *` — default: nullptr

The name of the input port

---

### receive\_impl \[#receiveimpl]

```cpp showLineNumbers={false}
std::any holoscan::gxf::GXFInputContext::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
) override
```

The implementation of the [`receive`](../../../classes/inputcontext#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 *` — default: nullptr

The name of the input port.

---

**`in_type`** `InputType` — default: InputType::kAny

The input type (kGXFEntity or kAny).

---

**`no_error_message`** `bool` — default: false

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

---

**`omit_data_logging`** `bool` — default: false

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

---

### retrieve\_cuda\_streams \[#retrievecudastreams]

```cpp showLineNumbers={false}
gxf_result_t holoscan::gxf::GXFInputContext::retrieve_cuda_streams(
    nvidia::gxf::Entity &message,
    const std::string &input_name
)
```

### gxf\_cuda\_object\_handler \[#gxfcudaobjecthandler]

```cpp showLineNumbers={false}
std::shared_ptr<gxf::CudaObjectHandler> holoscan::gxf::GXFInputContext::gxf_cuda_object_handler()
```

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

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

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

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

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

```cpp showLineNumbers={false}
bool holoscan::gxf::GXFInputContext::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::gxf::GXFInputContext::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::gxf::GXFInputContext::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::gxf::GXFInputContext::get_unique_id(
    Operator *op,
    const std::string &port_name
)
```

### log\_tensor \[#logtensor]

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

### log\_tensormap \[#logtensormap]

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

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

```cpp showLineNumbers={false}
bool holoscan::gxf::GXFInputContext::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::gxf::GXFInputContext::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::gxf::GXFInputContext::handle_null_value(
    DataT &input_vector
)
```

#### Overload 2

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

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

```cpp showLineNumbers={false}
template <typename DataT>
bool holoscan::gxf::GXFInputContext::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::gxf::GXFInputContext::receive_single_value(
    const char *name,
    InputType in_type,
    bool omit_tensormap_logging = false
)
```

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

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

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

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

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

```cpp showLineNumbers={false}
std::optional<cudaStream_t> holoscan::gxf::GXFInputContext::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 > > >` |                                                    |