I/O object for client-side, unary rpcs. More...

#include <agrpc/client_rpc.hpp>

Inheritance diagram for agrpc::ClientRPC< PrepareAsyncUnary, Executor >:

Collaboration diagram for agrpc::ClientRPC< PrepareAsyncUnary, Executor >:

Public Types
using	Stub = StubT
	The stub type.

using	Request = RequestT
	The response message type.

using	Response = ResponseT
	The request message type.

using	executor_type = Executor
	The executor type.

Public Member Functions
void	start (StubT &stub, const RequestT &req)
	Start the rpc. More...

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	finish (ResponseT &response, CompletionToken &&token=detail::DefaultCompletionTokenT< Executor >{})
	Finish the rpc. More...

auto	read_initial_metadata (CompletionToken &&token=detail::DefaultCompletionTokenT< Executor >{})
	Read initial metadata. More...

const executor_type &	get_executor () const noexcept
	Get the executor. More...

const executor_type &	get_scheduler () const noexcept
	Get the scheduler. More...

grpc::ClientContext &	context ()
	Get the underlying `grpc::ClientContext`

const grpc::ClientContext &	context () const
	Get the underlying `grpc::ClientContext` (const overload)

void	cancel () noexcept
	Cancel this RPC. More...

Static Public Member Functions
static constexpr std::string_view	service_name () noexcept
	Name of the gRPC service. More...

static constexpr std::string_view	method_name () noexcept
	Name of the gRPC method. More...

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
static auto	request (agrpc::GrpcContext &grpc_context, StubT &stub, grpc::ClientContext &context, const RequestT &request, ResponseT &response, CompletionToken &&token=detail::DefaultCompletionTokenT< Executor >{})
	Perform a request. More...

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
static auto	request (const Executor &executor, StubT &stub, grpc::ClientContext &context, const RequestT &request, ResponseT &response, CompletionToken &&token=detail::DefaultCompletionTokenT< Executor >{})
	Start a generic unary request (executor overload)

Static Public Attributes
static constexpr agrpc::ClientRPCType	TYPE = agrpc::ClientRPCType::UNARY
	The rpc type.

Detailed Description

template<class StubT, class RequestT, class ResponseT, std::unique_ptr< grpc::ClientAsyncResponseReader< ResponseT > >(StubT::*)(grpc::ClientContext *, const RequestT &, grpc::CompletionQueue *) PrepareAsyncUnary, class Executor>
class agrpc::ClientRPC< PrepareAsyncUnary, Executor >

I/O object for client-side, unary rpcs.

Example:

asio::awaitable<void> client_rpc_unary(agrpc::GrpcContext& grpc_context,
                                       example::v1::Example::Stub& stub)
{
    using RPC = asio::use_awaitable_t<>::as_default_on_t<
        agrpc::ClientRPC<&example::v1::Example::Stub::PrepareAsyncUnary>>;
    grpc::ClientContext client_context;
    client_context.set_deadline(std::chrono::system_clock::now() +
                                std::chrono::seconds(5));
    RPC::Request request;
    RPC::Response response;
    const grpc::Status status =
        co_await RPC::request(grpc_context, stub, client_context, request, response);
    if (!status.ok())
    {
        std::cerr << "Rpc failed: " << status.error_message();
        co_return;
    }
    std::cout << "Response: " << response.integer();
}

Alternative version that waits the server's initial metadata first:

asio::awaitable<void> client_rpc_unary_initial_metadata(agrpc::GrpcContext& grpc_context,
                                                        example::v1::Example::Stub& stub)
{
    using RPC =
        asio::use_awaitable_t<>::as_default_on_t<agrpc::ClientRPC<&example::v1::Example::Stub::PrepareAsyncUnary>>;
    RPC rpc{grpc_context};
    rpc.context().set_deadline(std::chrono::system_clock::now() + std::chrono::seconds(5));
    RPC::Request request;
    rpc.start(stub, request);
    co_await rpc.read_initial_metadata();
    // Do something with:
    // rpc.context().GetServerInitialMetadata();
    RPC::Response response;
    const grpc::Status status = co_await rpc.finish(response);
    if (!status.ok())
    {
        std::cerr << "Rpc failed: " << status.error_message();
        co_return;
    }
}

Based on .proto file:

syntax = "proto3";
 
package example.v1;
 
service Example {
  rpc ServerStreaming(Request) returns (stream Response) {}
 
  rpc ClientStreaming(stream Request) returns (Response) {}
 
  rpc BidirectionalStreaming(stream Request) returns (stream Response) {}
 
  rpc Unary(Request) returns (Response) {}
}
 
message Request {
  int32 integer = 1;
}
 
message Response {
  int32 integer = 1;
}

Template Parameters

PrepareAsyncUnary	A pointer to the generated, async version of the gRPC method. The async version starts with `PrepareAsync`.
Executor	The executor type, must be capable of referring to a `agrpc::GrpcContext`.

Per-Operation Cancellation

Terminal and partial. Cancellation is performed by invoking grpc::ClientContext::TryCancel. Operations are also cancelled when the deadline of the rpc has been reached (see grpc::ClientContext::set_deadline).

Since: 2.6.0

Member Function Documentation

◆ service_name()

template<class StubT , class RequestT , class ResponseT , template< class > class ResponderT, detail::PrepareAsyncClientUnaryRequest< StubT, RequestT, ResponderT< ResponseT > > PrepareAsyncUnary, class Executor >

static constexpr std::string_view agrpc::detail::ClientRPCUnaryBase< PrepareAsyncUnary, Executor >::service_name ( )

inlinestaticconstexprnoexceptinherited

Name of the gRPC service.

Equal to the generated Service::service_full_name().

E.g. for the .proto schema

package example.v1;
 
service Example { ... }

the return value would be "example.v1.Example".

Since: 2.6.0

◆ method_name()

template<class StubT , class RequestT , class ResponseT , template< class > class ResponderT, detail::PrepareAsyncClientUnaryRequest< StubT, RequestT, ResponderT< ResponseT > > PrepareAsyncUnary, class Executor >

static constexpr std::string_view agrpc::detail::ClientRPCUnaryBase< PrepareAsyncUnary, Executor >::method_name ( )

inlinestaticconstexprnoexceptinherited

Name of the gRPC method.

E.g. for agrpc::ClientRPC<&example::Example::Stub::PrepareAsyncMyMethod> the return value would be "MyMethod".

Since: 2.6.0

◆ request()

template<class StubT , class RequestT , class ResponseT , template< class > class ResponderT, detail::PrepareAsyncClientUnaryRequest< StubT, RequestT, ResponderT< ResponseT > > PrepareAsyncUnary, class Executor >

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>

static auto agrpc::detail::ClientRPCUnaryBase< PrepareAsyncUnary, Executor >::request	(	agrpc::GrpcContext &	grpc_context,
		StubT &	stub,
		grpc::ClientContext &	context,
		const RequestT &	request,
		ResponseT &	response,
		CompletionToken &&	token = `detail::DefaultCompletionTokenT<Executor>{}`
	)

inlinestaticinherited

Perform a request.

Parameters

request	The request message, save to delete when this function returns, unless a deferred completion token is used like `agrpc::use_sender` or `asio::deferred`.
response	The response message, will be filled by the server upon finishing this rpc. Must remain alive until this rpc is finished.
token	A completion token like `asio::yield_context` or `agrpc::use_sender`. The completion signature is `void(grpc::Status)`. Use `grpc::Status::ok()` to check whether the request was successful.

◆ start()

template<class StubT , class RequestT , class ResponseT , template< class > class ResponderT, detail::PrepareAsyncClientUnaryRequest< StubT, RequestT, ResponderT< ResponseT > > PrepareAsyncUnary, class Executor >

void agrpc::detail::ClientRPCUnaryBase< PrepareAsyncUnary, Executor >::start	(	StubT &	stub,
		const RequestT &	req
	)

inlineinherited

Start the rpc.

Parameters

req	The request message, save to delete when this function returns, unless a deferred completion token like `agrpc::use_sender` or `asio::deferred` is used.

◆ finish()

template<class StubT , class RequestT , class ResponseT , template< class > class ResponderT, detail::PrepareAsyncClientUnaryRequest< StubT, RequestT, ResponderT< ResponseT > > PrepareAsyncUnary, class Executor >

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>

auto agrpc::detail::ClientRPCUnaryBase< PrepareAsyncUnary, Executor >::finish	(	ResponseT &	response,
		CompletionToken &&	token = `detail::DefaultCompletionTokenT<Executor>{}`
	)

inlineinherited

Finish the rpc.

Receive the server's response message and final status for the call.

This operation will finish when either:

The server's response message and status have been received.
The server has returned a non-OK status (no message expected in this case).
The call failed for some reason and the library generated a non-OK status.

Side effect:

The ClientContext associated with the call is updated with possible initial and trailing metadata sent from the server.

Parameters

token A completion token like asio::yield_context or agrpc::use_sender. The completion signature is void(grpc::Status).

◆ read_initial_metadata()

auto agrpc::detail::ClientRPCBase< ResponderT< ResponseT > , Executor >::read_initial_metadata ( CompletionToken && token = detail::DefaultCompletionTokenT<Executor>{} )

inlineinherited

Read initial metadata.

Request notification of the reading of the initial metadata.

This call is optional.

Side effect:

Upon receiving initial metadata from the server, the ClientContext associated with this call is updated, and the calling code can access the received metadata through the ClientContext.

Attention: If the server does not explicitly send initial metadata (e.g. by calling agrpc::send_initial_metadata) but waits for a message from the client instead then this function won't complete until write() is called.

Parameters

token A completion token like asio::yield_context or agrpc::use_sender. The completion signature is void(bool). true indicates that the metadata was read. If it is false, then the call is dead.

◆ get_executor()

template<class Executor >

const executor_type & agrpc::detail::RPCExecutorBase< Executor >::get_executor ( ) const

inlinenoexceptinherited

Get the executor.

Thread-safe

◆ get_scheduler()

template<class Executor >

const executor_type & agrpc::detail::RPCExecutorBase< Executor >::get_scheduler ( ) const

inlinenoexceptinherited

Get the scheduler.

Thread-safe

Since: 2.9.0

◆ cancel()

void agrpc::detail::ClientRPCContextBase< ResponderT< ResponseT > >::cancel ( )

inlinenoexceptinherited

Cancel this RPC.

Effectively calls context().TryCancel().

Thread-safe

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ service_name()

◆ method_name()

◆ request()

◆ start()

◆ finish()

◆ read_initial_metadata()

◆ get_executor()

◆ get_scheduler()

◆ cancel()