NVIDIA Docs Hub Homepage NVIDIA Holoscan Holoscan SDK v3.11.0 Class InputContext

Class InputContext

Defined in File io_context.hpp

Inheritance Relationships

Derived Type

public holoscan::gxf::GXFInputContext (Class GXFInputContext)

Class Documentation

class InputContext

Class to hold the input context.

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

Subclassed by holoscan::gxf::GXFInputContext

Public Functions

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

Construct a new InputContext object.

Parameters

execution_context – The pointer to the execution context.
op – The pointer to the operator that this context is associated with.
inputs – The references to the map of the input specs.

InputContext(ExecutionContext *execution_context, Operator *op)

Construct a new InputContext object.

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

Parameters

execution_context – The pointer to GXF execution runtime
op – The pointer to the operator that this context is associated with.

virtual ~InputContext() = default

inline ExecutionContext *execution_context() const

Get pointer to the execution context.

Returns: The pointer to the execution context.

inline Operator *op() const

Return the operator that this context is associated with.

Returns: The pointer to the operator.

inline std::unordered_map<std::string, std::shared_ptr<IOSpec>> &inputs() const

Return the reference to the map of the input specs.

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

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

Parameters: name – The name of the input port to check.
Returns: True, if it has no data, otherwise false.

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

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

Get the acquisition timestamp for a given input port.

Parameters: input_port_name – The name of the input port.
Returns: The acquisition timestamp. If no timestamp was published by the upstream operator, std::nullopt is returned.

std::vector<std::optional<int64_t>> 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.

Parameters: input_port_name – The name of the input port.
Returns: The acquisition timestamps. Values of std::nullopt in the vector indicate that the corresponding message did not contain a timestamp.

template<typename DataT> inline holoscan::expected<DataT, holoscan::RuntimeError> 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:

Copy
Copied!

            
            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());
    }
  }
};

Template Parameters: DataT – The type of the data to receive.
Parameters: name – The name of the input port to receive the data from.
Returns: The received data.

inline std::shared_ptr<CudaObjectHandler> 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.

inline void cuda_object_handler(std::shared_ptr<CudaObjectHandler> handler): Set the CUDA stream/event handler used by this input context.

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

Note

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

Parameters

input_port_name – The name of the input port. Can be omitted if the operator only has a single input port.
allocate – 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 – Whether to also synchronize the internal stream to cudaStreamDefault.

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.

inline virtual std::vector<std::optional<cudaStream_t>> 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.

Note

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

Parameters: input_port_name – The name of the input port. Can be omitted if the operator only has a single input port.
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.

Protected Types

enum class InputType

The input data type.

Values:

enumerator kGXFEntity: The message data to receive is a GXF entity.

enumerator kAny: The message data to receive is a std::any.

Protected Functions

inline virtual bool empty_impl(const char *name = nullptr)

The implementation of the empty method.

Parameters: name – The name of the input port
Returns: True if the input port is empty or by default. Otherwise, false.

inline virtual std::any receive_impl(const char *name = nullptr, InputType in_type = InputType::kAny, bool no_error_message = false, bool omit_data_logging = 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.

Parameters

name – The name of the input port.
in_type – The input type (kGXFEntity or kAny).
no_error_message – Whether to print an error message when the input port is not found.
omit_data_logging – Whether any calls to log_backend_specific should be skipped. Currently used to avoid duplication of logging of TensorMap contents.

Returns

The data received from the input port.

inline bool is_valid_param_type(const ArgType &arg_type)

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

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

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

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

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

inline bool populate_tensor_map(const holoscan::gxf::Entity &gxf_entity, holoscan::TensorMap &tensor_map)

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

template<typename DataT> inline void handle_null_value(DataT &input_vector)

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

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

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

template<typename DataT> inline holoscan::expected<DataT, holoscan::RuntimeError> handle_null_value()

void prepopulate_acquisition_timestamp_map()

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

Helper to extract the first received CUDA stream for logging.

Parameters: port_name – The name of the input port
Returns: The first CUDA stream if available, std::nullopt otherwise

Protected Attributes

ExecutionContext *execution_context_ = nullptr: The execution context that is associated with.

Operator *op_ = nullptr: The operator that this context is associated with.

std::unordered_map<std::string, std::shared_ptr<IOSpec>> &inputs_: The inputs.

std::shared_ptr<CudaObjectHandler> cuda_object_handler_ = {}

std::map<std::string, std::vector<std::optional<int64_t>>> acquisition_timestamp_map_

Previous Class WorkQueue

Next Class IOSpec