holoscan::gxf::GXFInputContext

Beta

Class to hold the input context for a GXF Operator.

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

#include <holoscan/gxf/gxf_io_context.hpp>

Inherits from: holoscan::InputContext (public)

Constructors

GXFInputContext

Construct a new `GXFInputContext` object

Construct a new `GXFInputContext` object (with inputs)

holoscan::gxf::GXFInputContext::GXFInputContext(holoscan::gxf::GXFInputContext::GXFInputContext(
    ExecutionContext *execution_context,
    Operator *op
)

Construct a new GXFInputContext object.

Parameters

execution_context

ExecutionContext *

The pointer to the execution context.

Operator *

The pointer to the GXFOperator object.

Methods

gxf_context

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

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

Returns: The operator’s internal CUDA stream, when possible. Returns cudaStreamDefault instead if no CudaStreamPool resource 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 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

boolDefaults to false

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

receive_cuda_streams

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

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.

execution_context

ExecutionContext * holoscan::gxf::GXFInputContext::execution_context() constExecutionContext * holoscan::gxf::GXFInputContext::execution_context() const

Get pointer to the execution context.

Returns: The pointer to the execution context.

op

Operator * holoscan::gxf::GXFInputContext::op() constOperator * holoscan::gxf::GXFInputContext::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::gxf::GXFInputContext::inputs() conststd::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

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 *Defaults to nullptr

The name of the input port to check.

reset_acquisition_timestamps

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

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 *Defaults to nullptr

The name of the input port.

get_acquisition_timestamps

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 *Defaults to nullptr

The name of the input port.

receive

template <typename DataT>
holoscan::expected<DataT, holoscan::RuntimeError> holoscan::gxf::GXFInputContext::receive(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 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::gxf::GXFInputContext::cuda_object_handler()std::shared_ptr<CudaObjectHandler> holoscan::gxf::GXFInputContext::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.

empty_impl

bool holoscan::gxf::GXFInputContext::empty_impl(
    const char *name = nullptr
) override

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

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

retrieve_cuda_streams

gxf_result_t holoscan::gxf::GXFInputContext::retrieve_cuda_streams(
    nvidia::gxf::Entity &message,
    const std::string &input_name
)

gxf_cuda_object_handler

std::shared_ptr<gxf::CudaObjectHandler> holoscan::gxf::GXFInputContext::gxf_cuda_object_handler()std::shared_ptr<gxf::CudaObjectHandler> holoscan::gxf::GXFInputContext::gxf_cuda_object_handler()

is_valid_param_type

bool holoscan::gxf::GXFInputContext::is_valid_param_type(
    const ArgType &arg_type
)

any_size_param_count

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

should_fallback_to_direct_any_size_input

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

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

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

log_tensor

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

log_tensormap

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

populate_tensor_map

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

Overload 1

Overload 2

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

handle_bad_any_cast

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

template <typename DataT>
holoscan::expected<DataT, holoscan::RuntimeError> holoscan::gxf::GXFInputContext::receive_single_value(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

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

prepopulate_acquisition_timestamp_map

void holoscan::gxf::GXFInputContext::prepopulate_acquisition_timestamp_map()

get_first_stream_for_logging

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

Constructors

GXFInputContext

Construct a new GXFInputContext object

Construct a new GXFInputContext object (with inputs)

Methods

gxf_context

receive_cuda_stream

receive_cuda_streams

execution_context

op

inputs

empty

reset_acquisition_timestamps

get_acquisition_timestamp

get_acquisition_timestamps

receive

cuda_object_handler

Overload 1

Overload 2

empty_impl

receive_impl

retrieve_cuda_streams

gxf_cuda_object_handler

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

Construct a new `GXFInputContext` object (with inputs)