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

#include <agrpc/client_rpc.hpp>

Inheritance diagram for agrpc::ClientRPC< agrpc::ClientRPCType::GENERIC_UNARY, Executor >:

Collaboration diagram for agrpc::ClientRPC< agrpc::ClientRPCType::GENERIC_UNARY, Executor >:

Classes
struct	rebind_executor
	Rebind the ClientRPC to another executor. More...

Public Types
using	Stub = grpc::GenericStub
	The stub type.

using	Request = grpc::ByteBuffer
	The response message type.

using	Response = grpc::ByteBuffer
	The request message type.

using	executor_type = Executor
	The executor type.

Public Member Functions
void	start (const std::string &method, grpc::GenericStub &stub, const grpc::ByteBuffer &req)
	Start the rpc.

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

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

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

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

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.

Static Public Member Functions
template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
static auto	request (agrpc::GrpcContext &grpc_context, const std::string &method, grpc::GenericStub &stub, grpc::ClientContext &context, const grpc::ByteBuffer &request, grpc::ByteBuffer &response, CompletionToken &&token=CompletionToken{})
	Start a generic unary request.

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

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

Detailed Description

template<class Executor>
class agrpc::ClientRPC< agrpc::ClientRPCType::GENERIC_UNARY, Executor >

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

Example:

asio::awaitable<void> client_rpc_generic_unary(agrpc::GrpcContext& grpc_context, grpc::GenericStub& stub)
{
    grpc::ClientContext client_context;
    client_context.set_deadline(std::chrono::system_clock::now() + std::chrono::seconds(5));
 
    example::v1::Request request;
    grpc::ByteBuffer request_buffer;
    bool own_buffer;
    grpc::GenericSerialize<grpc::ProtoBufferWriter, example::v1::Request>(request, &request_buffer, &own_buffer);
    (void)own_buffer;
 
    grpc::ByteBuffer response_buffer;
 
    using RPC = agrpc::GenericUnaryClientRPC;
    if (const grpc::Status status =
            co_await RPC::request(grpc_context, "/example.v1.Example/Unary", stub, client_context, request_buffer,
                                  response_buffer, asio::use_awaitable);
        !status.ok())
    {
        std::cerr << "Rpc failed: " << status.error_message();
        co_return;
    }
 
    example::v1::Response response;
    if (const grpc::Status status =
            grpc::GenericDeserialize<grpc::ProtoBufferReader, example::v1::Response>(&response_buffer, &response);
        !status.ok())
    {
        std::cerr << "Rpc failed: unexpected response type";
        co_return;
    }
 
    std::cout << "Response: " << response.integer();
}

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

Executor The executor type, must be capable of referring to a 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

◆ request()

template<class Executor >

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

static auto agrpc::ClientRPC< agrpc::ClientRPCType::GENERIC_UNARY, Executor >::request	(	agrpc::GrpcContext &	grpc_context,
		const std::string &	method,
		grpc::GenericStub &	stub,
		grpc::ClientContext &	context,
		const grpc::ByteBuffer &	request,
		grpc::ByteBuffer &	response,
		CompletionToken &&	token = CompletionToken{} )

inlinestatic

Start a generic unary request.

Parameters

method	The gRPC method to call, e.g. "/test.v1.Test/Unary"
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 Executor >

void agrpc::ClientRPC< agrpc::ClientRPCType::GENERIC_UNARY, Executor >::start	(	const std::string &	method,
		grpc::GenericStub &	stub,
		const grpc::ByteBuffer &	req )

inline

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.
method	The RPC method to call, e.g. "/test.v1.Test/Unary"

◆ finish()

template<class Executor >

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

auto agrpc::ClientRPC< agrpc::ClientRPCType::GENERIC_UNARY, Executor >::finish	(	grpc::ByteBuffer &	response,
		CompletionToken &&	token = CompletionToken{} )

inline

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< grpc::GenericClientAsyncResponseReader, 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.

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

inlinenodiscardnoexceptinherited

Get the executor.

Thread-safe

◆ get_scheduler()

template<class Executor >

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

inlinenodiscardnoexceptinherited

Get the scheduler.

Thread-safe

Since: 2.9.0

◆ cancel()

void agrpc::detail::ClientRPCContextBase< grpc::GenericClientAsyncResponseReader >::cancel ( )

inlinenoexceptinherited

Cancel this RPC.

Effectively calls context().TryCancel().

Thread-safe

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ request()

◆ start()

◆ finish()

◆ read_initial_metadata()

◆ get_executor()

◆ get_scheduler()

◆ cancel()