Holohub gRPC Plugins for Holoscan SDK

Authors: Holoscan Team (NVIDIA)
Supported platforms: x86_64, aarch64
Language: C++, Python
Last modified: March 9, 2026
Latest version: 1.0
Minimum Holoscan SDK version: 2.6.0
Tested Holoscan SDK versions: 2.6.0
Contribution metric: Level 1 - Highly Reliable

Overview

This directory contains the Holohub gRPC plugins for Holoscan SDK, including:

• client: gRPC client and Holoscan Operators for sending, receiving, and streaming data to a gRPC server.
• server: gRPC server and Holoscan Operators for handling requests from a gRPC client and transmitting data back to the client.
• protos: Protocol buffers definitions of Holoscan SDK.
• common: Tensor <-> protobuf converters and Holoscan Resources to handle incoming and outgoing data.

Please refer to the gRPC h.264 Endoscopy Tool Tracking application for additional details.

The Python GrpcService permits plaintext only on loopback addresses and defaults to 127.0.0.1. Remote listeners require PEM private_key, certificate_chain, and root_certificates (the trusted client CA) arguments to initialize, along with a literal host IP address. Configured TLS always requires a trusted client certificate. Python EntityClientService accepts a credentials argument from grpc.ssl_channel_credentials for authenticated TLS connections and rejects remote plaintext targets. See the Python demo's mutual TLS setup for configuration and testing instructions.

API Reference

C++

holoscan::ops::ApplicationFactory

A factory class for creating and managing instances of HoloscanGrpcApplications.

Methods

Method	Description
ApplicationFactory(const ApplicationFactory &)=delete
ApplicationFactory & operator=(const ApplicationFactory &)=delete
void register_application(const std::string &service_name, create_application_instance_func func)	Register an application creation function with a service name.
std::shared_ptr<HoloscanGrpcApplication> create_application_instance(const std::string &service_name, std::queue< std::shared_ptr< nvidia::gxf::Entity > > &incoming_request_queue, std::queue< std::shared_ptr< EntityResponse > > &outgoing_response_queue)	Create an instance of HoloscanGrpcApplication.
void destroy_application_instance(std::shared_ptr< HoloscanGrpcApplication > application_instance)	Destroy an instance of HoloscanGrpcApplication.
std::shared_ptr<ApplicationFactory> get_instance()	Get the singleton instance of ApplicationFactory.

holoscan::ops::ApplicationFactory::ApplicationFactoryDeleter

A custom deleter for ApplicationFactory.

Methods

Method	Description
void operator()(ApplicationFactory *factory)

holoscan::ops::AsynchronousConditionQueue

Inherits from: holoscan::Resource

This class is a Holoscan Resource that is responsible for storing a queue of data entities.

Methods

Method	Description
AsynchronousConditionQueue(std::shared_ptr< AsynchronousCondition > request_available_condition)
void push(DataT entity)
DataT pop()
bool empty()

holoscan::ops::ConditionVariableQueue

Inherits from: holoscan::Resource

Methods

Method	Description
ConditionVariableQueue()
ConditionVariableQueue(std::queue< DataT > &queue)
void push(DataT value)
DataT pop()
bool empty()

holoscan::ops::EntityClient

A client class for handling gRPC communication with an entity server.

Methods

Method	Description
EntityClient(const std::string &server_address, const uint32_t rpc_timeout, std::shared_ptr< ConditionVariableQueue< std::shared_ptr< EntityRequest > > > request_queue, std::shared_ptr< AsynchronousConditionQueue< std::shared_ptr< nvidia::gxf::Entity > > > response_queue)
void EntityStream(on_new_response_available_callback response_cb, on_rpc_completed_callback rpc_completed_cb)

holoscan::ops::EntityClient::EntityStreamInternal

Inherits from: grpc::ClientBidiReactor< EntityRequest, EntityResponse >

Methods

Method	Description
EntityStreamInternal(EntityClient *client, on_new_response_available_callback response_cb, on_rpc_completed_callback rpc_completed_cb, uint32_t rpc_timeout)
void OnWriteDone(bool ok) override
void OnReadDone(bool ok) override
void OnDone(const grpc::Status &status) override
Status Await()

holoscan::ops::EntityClientService

A service class for handling gRPC client operations.

Methods

Method	Description
EntityClientService(const std::string &server_address, const uint32_t rpc_timeout, const bool interrupt, std::shared_ptr< ConditionVariableQueue< std::shared_ptr< EntityRequest > > > request_queue, std::shared_ptr< AsynchronousConditionQueue< std::shared_ptr< nvidia::gxf::Entity > > > response_queue, std::shared_ptr< GrpcClientRequestOp > grpc_request_operator)
void start_entity_stream()	Starts the entity stream RPC operation.
void stop_entity_stream()	Stops the entity stream RPC operation.

holoscan::ops::HoloscanEntityServiceImpl::EntityStreamInternal

Inherits from: grpc::ServerBidiReactor< EntityRequest, EntityResponse >

Methods

Method	Description
EntityStreamInternal(HoloscanEntityServiceImpl *server, std::shared_ptr< HoloscanGrpcApplication > app, on_entity_stream_rpc_complete entity_stream_rpc_complete)
void OnWriteDone(bool ok) override
void OnReadDone(bool ok) override
void OnDone() override

holoscan::ops::HoloscanEntityServiceImpl

Inherits from: Entity::CallbackService

Implementation of the gRPC Entity Service for Holoscan.

Methods

Method	Description
HoloscanEntityServiceImpl(on_new_entity_stream_rpc new_entity_stream_rpc, on_entity_stream_rpc_complete entity_stream_rpc_complete)
grpc::ServerBidiReactor<EntityRequest, EntityResponse> * EntityStream(CallbackServerContext *context) override	Handles the bidirectional streaming of entity requests and responses.

holoscan::ops::GrpcClientRequestOp

Inherits from: holoscan::Operator

Methods

Method	Description
void setup(OperatorSpec &spec) override
void compute(InputContext &op_input, OutputContext &op_output, ExecutionContext &context) override
std::shared_ptr<Allocator> allocator()
Executor & executor()
const cudaStream_t get_cuda_stream()

holoscan::ops::GrpcClientResponseOp

Inherits from: holoscan::Operator

A Holoscan Operator class for passing data received from gRPC server to downstream operators.

Methods

Method	Description
void start() override
void stop() override
void initialize() override
void setup(OperatorSpec &spec) override
void compute(InputContext &op_input, OutputContext &op_output, ExecutionContext &context) override

holoscan::ops::GrpcServerRequestOp

Inherits from: holoscan::Operator

A Holoscan Operator class for handling incoming gRPC requests.

Methods

Method	Description
void setup(OperatorSpec &spec) override
void compute(InputContext &op_input, OutputContext &op_output, ExecutionContext &context) override
std::shared_ptr<UnboundedAllocator> allocator()
const uint32_t rpc_timeout()
const cudaStream_t get_cuda_stream()

holoscan::ops::GrpcServerResponseOp

Inherits from: holoscan::Operator

A Holoscan Operator class for handling outgoing results.

Methods

Method	Description
void setup(OperatorSpec &spec) override
void compute(InputContext &op_input, OutputContext &op_output, ExecutionContext &context) override

holoscan::ops::HoloscanGrpcApplication

Inherits from: holoscan::Application

A class that represents a gRPC application for Holoscan.

Methods

Method	Description
HoloscanGrpcApplication(std::queue< std::shared_ptr< nvidia::gxf::Entity > > &incoming_request_queue, std::queue< std::shared_ptr< EntityResponse > > &outgoing_response_queue)
void compose() override	Composes the gRPC application by setting up necessary components and configurations.
void set_scheduler(const std::string &config_name)	Sets the scheduler configuration for the Holoscan application.
void set_data_path(const std::string path)	Sets the data path.
void enqueue_request(const EntityRequest &request)	Enqueues an EntityRequest for processing.
void enqueue_response(std::shared_ptr< EntityResponse > response)	Enqueues an EntityResponse to be sent to the client.
bool is_response_available()	Checks if a response is available.
std::shared_ptr<EntityResponse> dequeue_response()	Dequeues a response from the internal queue.
const uint32_t rpc_timeout()	Retrieves the RPC call timeout value.
void start_streaming()	Starts the streaming process.
void stop_streaming()	Stops the streaming process.
std::shared_ptr<GrpcServerRequestOp> get_grpc_request_op() const	Retrieves the gRPC server request operator.
std::shared_ptr<GrpcServerResponseOp> get_grpc_response_op() const	Retrieves the gRPC server response operator.
std::shared_ptr<ConditionVariableQueue<std::shared_ptr<nvidia::gxf::Entity>>> get_request_queue() const	Retrieves the request queue.
std::shared_ptr<ConditionVariableQueue<std::shared_ptr<EntityResponse>>> get_response_queue() const	Retrieves the response queue.
std::shared_ptr<BooleanCondition> get_streaming_enabled() const	Retrieves the current state of the streaming enabled condition.
std::string get_data_path() const	Retrieves the data path.

holoscan::ops::TensorProto

Methods

Method	Description
void tensor_to_entity_request(const nvidia::gxf::Entity &gxf_entity, std::shared_ptr< EntityRequest > request, const cudaStream_t cuda_stream)	Converts a GXF entity to an EntityRequest.
void tensor_to_entity_response(const nvidia::gxf::Entity &gxf_entity, std::shared_ptr< EntityResponse > response, const cudaStream_t cuda_stream)	Converts a GXF entity to an EntityResponse.
void entity_request_to_tensor(const EntityRequest *entity_request, nvidia::gxf::Entity &gxf_entity, nvidia::gxf::Handle< nvidia::gxf::Allocator > gxf_allocator, const cudaStream_t cuda_stream)	Converts an EntityRequest to a GXF entity.
void entity_response_to_tensor(const EntityResponse &entity_request, nvidia::gxf::Entity &gxf_entity, nvidia::gxf::Handle< nvidia::gxf::Allocator > gxf_allocator, const cudaStream_t cuda_stream)	Converts an EntityResponse to a GXF entity.