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

#include <agrpc/server_rpc.hpp>

Inheritance diagram for agrpc::ServerRPC< agrpc::ServerRPCType::GENERIC, TraitsT, Executor >:

Collaboration diagram for agrpc::ServerRPC< agrpc::ServerRPCType::GENERIC, TraitsT, Executor >:

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

Public Types
using	Ptr = agrpc::ServerRPCPtr<ServerRPC>
	ServerRPCPtr specialized on this type.

using	Request = RequestT
	The response message type.

using	Response = ResponseT
	The request message type.

using	Traits = TraitsT
	The traits type.

using	executor_type = Executor
	The executor type.

Public Member Functions
	ServerRPC ()=delete
	Deleted default constructor.

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	read (RequestT &req, CompletionToken &&token=CompletionToken{})
	Receive a message from the client.

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	write (const ResponseT &response, grpc::WriteOptions options, CompletionToken &&token=CompletionToken{})
	Send a message to the client.

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	write (const ResponseT &response, CompletionToken &&token=CompletionToken{})
	Send a message to the client (default WriteOptions)

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	write_and_finish (const ResponseT &response, grpc::WriteOptions options, const grpc::Status &status, CompletionToken &&token=CompletionToken{})
	Coalesce write and finish of this rpc.

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	write_and_finish (const ResponseT &response, const grpc::Status &status, CompletionToken &&token=CompletionToken{})
	Coalesce write and finish of this rpc (default WriteOptions)

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	finish (const grpc::Status &status, CompletionToken &&token=CompletionToken{})
	Finish this rpc.

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

bool	is_done () const noexcept
	Is this rpc done?

auto	wait_for_done (CompletionToken &&token=detail::DefaultCompletionTokenT< Executor >{})
	Wait for done.

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

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

auto &	context ()
	Get the underlying `ServerContext`

const auto &	context () const
	Get the underlying `ServerContext` (const overload)

void	cancel () noexcept
	Cancel this RPC.

Static Public Attributes
static constexpr agrpc::ServerRPCType	TYPE = agrpc::ServerRPCType::GENERIC
	The rpc type.

Detailed Description

template<class TraitsT, class Executor>
class agrpc::ServerRPC< agrpc::ServerRPCType::GENERIC, TraitsT, Executor >

I/O object for server-side, generic rpcs.

Use one of the agrpc::register_ functions to set up request handling.

Example:

void server_rpc_generic(agrpc::GrpcContext& grpc_context, grpc::AsyncGenericService& service)
{
    using RPC = agrpc::GenericServerRPC;
    agrpc::register_awaitable_rpc_handler<RPC>(
        grpc_context, service,
        [](RPC& rpc) -> asio::awaitable<void>
        {
            RPC::Request request_buffer;
            if (!co_await rpc.read(request_buffer))
            {
                co_return;
            }
            example::v1::Request request;
            if (const auto status =
                    grpc::GenericDeserialize<grpc::ProtoBufferReader, example::v1::Request>(&request_buffer, &request);
                !status.ok())
            {
                co_await rpc.finish(status);
                co_return;
            }
            example::v1::Response response;
            response.set_integer(request.integer());
            RPC::Response response_buffer;
            bool own_buffer;
            if (const auto status = grpc::GenericSerialize<grpc::ProtoBufferWriter, example::v1::Response>(
                    response, &response_buffer, &own_buffer);
                !status.ok())
            {
                co_await rpc.finish(status);
                co_return;
            }
            if (!co_await rpc.write(response_buffer))
            {
                co_return;
            }
            co_await rpc.finish(grpc::Status::OK);
        },
        asio::detached);
}

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

RequestUnary	A pointer to the generated gRPC method.
Traits	A type used to customize this rpc. See `agrpc::DefaultServerRPCTraits`.
Executor	The executor type, must be capable of referring to a GrpcContext.

Per-Operation Cancellation

(except wait_for_done()) Terminal and partial. Cancellation is performed by invoking grpc::ServerContext::TryCancel. After successful cancellation no further operations should be started on the rpc. Operations are also cancelled when the deadline of the rpc has been reached.

Since: 2.7.0

Member Function Documentation

◆ read()

template<class RequestT , class ResponseT , template< class, class > class ResponderT, class TraitsT , class Executor >

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

auto agrpc::detail::ServerRPCBidiStreamingBase< ResponderT< ResponseT, RequestT >, TraitsT, Executor >::read	(	RequestT &	req,
		CompletionToken &&	token = CompletionToken{} )

inlineinherited

Receive a message from the client.

It may not be called concurrently with operations other than write(). It is not meaningful to call it concurrently with another read on the same rpc since reads on the same stream are delivered in order.

Parameters

token A completion token like asio::yield_context or agrpc::use_sender. The completion signature is void(bool). true indicates that a valid message was read. false when there will be no more incoming messages, either because the other side has called WritesDone() or the stream has failed (or been cancelled).

◆ write()

template<class RequestT , class ResponseT , template< class, class > class ResponderT, class TraitsT , class Executor >

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

auto agrpc::detail::ServerRPCBidiStreamingBase< ResponderT< ResponseT, RequestT >, TraitsT, Executor >::write	(	const ResponseT &	response,
		grpc::WriteOptions	options,
		CompletionToken &&	token = CompletionToken{} )

inlineinherited

Send a message to the client.

Only one write may be outstanding at any given time. It may not be called concurrently with operations other than read().

GRPC does not take ownership or a reference to response, so it is safe to to deallocate once write() returns, unless a deferred completion token like agrpc::use_sender or asio::deferred is used.

Parameters

token A completion token like asio::yield_context or agrpc::use_sender. The completion signature is void(bool). true means that the data/metadata/status/etc is going to go to the wire. If it is false, it is not going to the wire because the call is already dead (i.e., canceled, deadline expired, other side dropped the channel, etc).

◆ write_and_finish()

template<class RequestT , class ResponseT , template< class, class > class ResponderT, class TraitsT , class Executor >

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

auto agrpc::detail::ServerRPCBidiStreamingBase< ResponderT< ResponseT, RequestT >, TraitsT, Executor >::write_and_finish	(	const ResponseT &	response,
		grpc::WriteOptions	options,
		const grpc::Status &	status,
		CompletionToken &&	token = CompletionToken{} )

inlineinherited

Coalesce write and finish of this rpc.

Write response and coalesce it with trailing metadata which contains status, using WriteOptions options. May not be used concurrently with other operations.

write_and_finish is equivalent of performing write with WriteOptions.set_last_message() and finish in a single step.

GRPC does not take ownership or a reference to response and status, so it is safe to deallocate once write_and_finish() returns, unless a deferred completion token like agrpc::use_sender or asio::deferred is used.

Implicit input parameter:

The ServerContext associated with the call is used for sending trailing (and initial) metadata to the client.

Note: Status must have an OK code.

Parameters

token A completion token like asio::yield_context or agrpc::use_sender. The completion signature is void(bool). true means that the data/metadata/status/etc is going to go to the wire. If it is false, it is not going to the wire because the call is already dead (i.e., canceled, deadline expired, other side dropped the channel, etc).

◆ finish()

template<class RequestT , class ResponseT , template< class, class > class ResponderT, class TraitsT , class Executor >

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

auto agrpc::detail::ServerRPCBidiStreamingBase< ResponderT< ResponseT, RequestT >, TraitsT, Executor >::finish	(	const grpc::Status &	status,
		CompletionToken &&	token = CompletionToken{} )

inlineinherited

Finish this rpc.

Indicate that the stream is to be finished with a certain status code.

Completes when the server has sent the appropriate signals to the client to end the call.

Should not be used concurrently with other operations and may only be called once.

It is appropriate to call this method when either:

all messages from the client have been received (either known implicitly, or explicitly because a previous read operation completed with false).
it is desired to end the call early with some non-OK status code.

This operation will end when the server has finished sending out initial metadata (if not sent already) and status, or if some failure occurred when trying to do so.

GRPC does not take ownership or a reference to status, so it is safe to to deallocate once finish() returns, unless a deferred completion token like agrpc::use_sender or asio::deferred is used.

Parameters

token A completion token like asio::yield_context or agrpc::use_sender. The completion signature is void(bool). true means that the data/metadata/status/etc is going to go to the wire. If it is false, it is not going to the wire because the call is already dead (i.e., canceled, deadline expired, other side dropped the channel, etc).

◆ send_initial_metadata()

auto agrpc::detail::ServerRPCBase< ResponderT< ResponseT, RequestT >, TraitsT, Executor >::send_initial_metadata ( CompletionToken && token = detail::DefaultCompletionTokenT<Executor>{} )

inlineinherited

Send initial metadata.

Request notification of the sending of initial metadata to the client.

This call is optional, but if it is used, it cannot be used concurrently with or after the finish()/finish_with_error() method.

Parameters

token A completion token like asio::yield_context or agrpc::use_sender. The completion signature is void(bool). true means that the data/metadata/status/etc is going to go to the wire. If it is false, it is not going to the wire because the call is already dead (i.e., canceled, deadline expired, other side dropped the channel, etc).

◆ is_done()

bool agrpc::detail::ServerRPCNotifyWhenDoneMixin< IsNotifyWhenDone, ResponderT< ResponseT, RequestT >, Executor >::is_done ( ) const

inlinenodiscardnoexceptinherited

Is this rpc done?

Only available if Traits contain NOTIFY_WHEN_DONE = true.

Returns true if NotifyWhenDone has fired which indicates that finish() has been called or that the rpc is dead (i.e., canceled, deadline expired, other side dropped the channel, etc).

Thread-safe

◆ wait_for_done()

auto agrpc::detail::ServerRPCNotifyWhenDoneMixin< IsNotifyWhenDone, ResponderT< ResponseT, RequestT >, Executor >::wait_for_done ( CompletionToken && token = detail::DefaultCompletionTokenT<Executor>{} )

inlineinherited

Wait for done.

Only available if Traits contain NOTIFY_WHEN_DONE = true.

Request notification of the completion of this rpc, either due to calling finish() or because the rpc is dead (i.e., canceled, deadline expired, other side dropped the channel, etc). rpc.context().IsCancelled() may only be called after this operation completes.

Cancelling this operation does not invoke grpc::ServerContext::TryCancel.

Internally, this operation uses grpc::ServerContext::AsyncNotifyWhenDone.

Attention: Only one call to wait_for_done() may be outstanding at a time.

Parameters

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

◆ 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()

template<class Responder >

void agrpc::detail::ServerRPCContextBase< Responder >::cancel ( )

inlinenoexceptinherited

Cancel this RPC.

Effectively calls context().TryCancel().

Thread-safe

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ read()

◆ write()

◆ write_and_finish()

◆ finish()

◆ send_initial_metadata()

◆ is_done()

◆ wait_for_done()

◆ get_executor()

◆ get_scheduler()

◆ cancel()