Public namespace. More...

Classes
class	BasicGrpcExecutor
	GrpcContext's executor. More...

class	ClientRPC
	Primary ClientRPC template. More...

class	ClientRPC< agrpc::ClientRPCType::GENERIC_STREAMING, Executor >
	I/O object for client-side, generic, streaming rpcs. More...

class	ClientRPC< agrpc::ClientRPCType::GENERIC_UNARY, Executor >
	I/O object for client-side, generic, unary rpcs. More...

class	ClientRPC< PrepareAsyncBidiStreaming, Executor >
	I/O object for client-side, bidirectional-streaming rpcs. More...

class	ClientRPC< PrepareAsyncClientStreaming, Executor >
	I/O object for client-side, client-streaming rpcs. More...

class	ClientRPC< PrepareAsyncServerStreaming, Executor >
	I/O object for client-side, server-streaming rpcs. More...

class	ClientRPC< PrepareAsyncUnary, Executor >
	I/O object for client-side, unary rpcs. More...

struct	DefaultRunTraits
	(experimental) Default run traits More...

class	GrpcContext
	Execution context based on `grpc::CompletionQueue` More...

class	HealthCheckService
	CompletionQueue-based implementation of grpc::HealthCheckServiceInterface. More...

class	ServerRPC
	Primary ServerRPC template. More...

class	ServerRPC< agrpc::ServerRPCType::GENERIC, TraitsT, Executor >
	I/O object for server-side, generic rpcs. More...

class	ServerRPC< RequestBidiStreaming, TraitsT, Executor >
	I/O object for server-side, bidirectional-streaming rpcs. More...

class	ServerRPC< RequestClientStreaming, TraitsT, Executor >
	I/O object for server-side, client-streaming rpcs. More...

class	ServerRPC< RequestServerStreaming, TraitsT, Executor >
	I/O object for server-side, server-streaming rpcs. More...

class	ServerRPC< RequestUnary, TraitsT, Executor >
	I/O object for server-side, unary rpcs. More...

class	ServerRPCPtr
	Allocated ServerRPC created by register_callback_rpc_handler. More...

struct	UseSender
	Sender completion token. More...

class	Waiter
	(experimental) Utility class for uncancelable operations More...

Typedefs
using	GenericUnaryClientRPC = agrpc::ClientRPC< agrpc::ClientRPCType::GENERIC_UNARY >
	I/O object for client-side, generic, unary rpcs (type alias) More...

using	GenericStreamingClientRPC = agrpc::ClientRPC< agrpc::ClientRPCType::GENERIC_STREAMING >
	I/O object for client-side, generic, streaming rpcs (type alias) More...

using	GrpcExecutor = agrpc::BasicGrpcExecutor<>
	Default GrpcExecutor. More...

using	GenericServerRPC = agrpc::ServerRPC< agrpc::ServerRPCType::GENERIC >
	I/O object for server-side, generic rpcs (type alias) More...

Enumerations
enum class	ClientRPCType { UNARY , GENERIC_UNARY , SERVER_STREAMING , CLIENT_STREAMING , BIDIRECTIONAL_STREAMING , GENERIC_STREAMING }
	The type of a ClientRPC. More...

enum class	ServerRPCType { UNARY , SERVER_STREAMING , CLIENT_STREAMING , BIDIRECTIONAL_STREAMING , GENERIC }
	The type of a ServerRPC. More...

Functions
template<class ServerRPC , class RPCHandler , class CompletionToken >
auto	register_awaitable_rpc_handler (const typename ServerRPC::executor_type &executor, detail::GetServerRPCServiceT< ServerRPC > &service, RPCHandler rpc_handler, CompletionToken &&token)
	Register an awaitable rpc handler for the given method. More...

template<class ServerRPC , class RPCHandler , class CompletionToken >
auto	register_awaitable_rpc_handler (agrpc::GrpcContext &grpc_context, detail::GetServerRPCServiceT< ServerRPC > &service, RPCHandler &&rpc_handler, CompletionToken &&token)
	Register an awaitable rpc handler for the given method (GrpcContext overload) More...

template<class ServerRPC , class RPCHandler , class CompletionToken >
auto	register_callback_rpc_handler (const typename ServerRPC::executor_type &executor, detail::GetServerRPCServiceT< ServerRPC > &service, RPCHandler rpc_handler, CompletionToken &&token)
	Register a callback rpc handler for the given method. More...

template<class ServerRPC , class RPCHandler , class CompletionToken >
auto	register_callback_rpc_handler (agrpc::GrpcContext &grpc_context, detail::GetServerRPCServiceT< ServerRPC > &service, RPCHandler &&rpc_handler, CompletionToken &&token)
	Register a callback rpc handler for the given method (GrpcContext overload) More...

template<class ServerRPC , class RPCHandler >
detail::RPCHandlerSender< ServerRPC, RPCHandler >	register_sender_rpc_handler (agrpc::GrpcContext &grpc_context, detail::GetServerRPCServiceT< ServerRPC > &service, RPCHandler rpc_handler)
	Register an sender rpc handler for the given method. More...

template<class ServerRPC , class RPCHandler , class CompletionToken >
auto	register_yield_rpc_handler (const typename ServerRPC::executor_type &executor, detail::GetServerRPCServiceT< ServerRPC > &service, RPCHandler rpc_handler, CompletionToken &&token)
	Register a Boost.Coroutine rpc handler for the given method. More...

template<class ServerRPC , class RPCHandler , class CompletionToken >
auto	register_yield_rpc_handler (agrpc::GrpcContext &grpc_context, detail::GetServerRPCServiceT< ServerRPC > &service, RPCHandler &&rpc_handler, CompletionToken &&token)
	Register a rpc handler for the given method (GrpcContext overload) More...

template<class Traits = agrpc::DefaultRunTraits, class ExecutionContext = void>
void	run (agrpc::GrpcContext &grpc_context, ExecutionContext &execution_context)
	(experimental) Run an execution context in the same thread as a GrpcContext More...

template<class Traits = agrpc::DefaultRunTraits, class ExecutionContext = void, class StopCondition = void>
void	run (agrpc::GrpcContext &grpc_context, ExecutionContext &execution_context, StopCondition stop_condition)
	(experimental) Run an execution context in the same thread as a GrpcContext More...

template<class Traits = agrpc::DefaultRunTraits, class ExecutionContext = void>
void	run_completion_queue (agrpc::GrpcContext &grpc_context, ExecutionContext &execution_context)
	(experimental) Run an execution context in the same thread as a GrpcContext's completion queue More...

template<class Traits = agrpc::DefaultRunTraits, class ExecutionContext = void, class StopCondition = void>
void	run_completion_queue (agrpc::GrpcContext &grpc_context, ExecutionContext &execution_context, StopCondition stop_condition)
	(experimental) Run an execution context in the same thread as a GrpcContext's completion queue More...

void	process_grpc_tag (agrpc::GrpcContext &grpc_context, void *tag, bool ok)
	Test utility to manually process gRPC tags. More...

Variables
constexpr detail::NotifyOnStateChangeFn	notify_on_state_change {}
	Set notification for a `grpc::Channel` state change. More...

constexpr detail::ReadFn	read {}
	Read from a streaming RPC. More...

constexpr agrpc::UseSender	use_sender {}
	Instance and factory for sender completion tokens. More...

Detailed Description

Public namespace.

Typedef Documentation

◆ GenericUnaryClientRPC

using agrpc::GenericUnaryClientRPC = typedef agrpc::ClientRPC<agrpc::ClientRPCType::GENERIC_UNARY>

I/O object for client-side, generic, unary rpcs (type alias)

See also: agrpc::ClientRPC<agrpc::ClientRPCType::GENERIC_UNARY,Executor>

Since: 2.6.0

◆ GenericStreamingClientRPC

using agrpc::GenericStreamingClientRPC = typedef agrpc::ClientRPC<agrpc::ClientRPCType::GENERIC_STREAMING>

I/O object for client-side, generic, streaming rpcs (type alias)

See also: agrpc::ClientRPC<agrpc::ClientRPCType::GENERIC_STREAMING,Executor>

Since: 2.6.0

◆ GrpcExecutor

using agrpc::GrpcExecutor = typedef agrpc::BasicGrpcExecutor<>

Default GrpcExecutor.

The default GrpcExecutor does not track outstanding work, has the relationship.fork and blocking.never properties and uses the default allocator (std::allocator<void>).

◆ GenericServerRPC

using agrpc::GenericServerRPC = typedef agrpc::ServerRPC<agrpc::ServerRPCType::GENERIC>

I/O object for server-side, generic rpcs (type alias)

See also: agrpc::ServerRPC<agrpc::ServerRPCType::GENERIC,TraitsT,Executor>

Since: 2.7.0

Enumeration Type Documentation

◆ ClientRPCType

enum class agrpc::ClientRPCType

strong

The type of a ClientRPC.

Since: 2.1.0

Enumerator
UNARY	Client-side unary rpc.
GENERIC_UNARY	Client-side generic unary rpc.
SERVER_STREAMING	Client-side server-streaming rpc.
CLIENT_STREAMING	Client-side client-streaming rpc.
BIDIRECTIONAL_STREAMING	Client-side bidirectional-streaming rpc.
GENERIC_STREAMING	Client-side generic streaming rpc.

◆ ServerRPCType

enum class agrpc::ServerRPCType

strong

The type of a ServerRPC.

Since: 2.7.0

Enumerator
UNARY	Server-side unary rpc.
SERVER_STREAMING	Server-side server-streaming rpc.
CLIENT_STREAMING	Server-side client-streaming rpc.
BIDIRECTIONAL_STREAMING	Server-side bidirectional-streaming rpc.
GENERIC	Server-side generic streaming rpc.

Function Documentation

◆ register_awaitable_rpc_handler() [1/2]

template<class ServerRPC , class RPCHandler , class CompletionToken >

auto agrpc::register_awaitable_rpc_handler	(	const typename ServerRPC::executor_type &	executor,
		detail::GetServerRPCServiceT< ServerRPC > &	service,
		RPCHandler	rpc_handler,
		CompletionToken &&	token
	)

Register an awaitable rpc handler for the given method.

The rpc handler will be invoked for every incoming request of this gRPC method. It must take ServerRPC& as first argument and ServerRPC::Request& as second argument (only for unary and server-streaming rpcs). The ServerRPC is automatically cancelled at the end of the rpc handler if finish() was not called earlier. The return value of the rpc handler is co_spawned in a manner similar to: asio::co_spawn(asio::get_associated_executor(completion_handler, executor), rpc_handler()), where completion_handler is created from token and executor the first argument passed to this function.

This asynchronous operation runs forever unless it is cancelled, the rpc handler throws an exception or the server is shutdown (grpc::Server::Shutdown is called). At which point it invokes the completion handler (passing forward the exception thrown by the request handler, if any) after all awaitables produced by invoking the rpc handler complete.

Example:

void server_rpc_unary(agrpc::GrpcContext& grpc_context,
                      example::v1::Example::AsyncService& service)
{
    using RPC = asio::use_awaitable_t<>::as_default_on_t<
        agrpc::ServerRPC<&example::v1::Example::AsyncService::RequestUnary>>;
    agrpc::register_awaitable_rpc_handler<RPC>(
        grpc_context, service,
        [](RPC& rpc, RPC::Request& request) -> asio::awaitable<void>
        {
            RPC::Response response;
            response.set_integer(request.integer());
            co_await rpc.finish(response, grpc::Status::OK);
 
            // Alternatively finish with an error:
            co_await rpc.finish_with_error(grpc::Status::CANCELLED);
        },
        asio::detached);
}

Template Parameters

ServerRPC An instantiation of agrpc::ServerRPC

Parameters

executor	The executor used to handle each rpc
service	The service associated with the gRPC method of the ServerRPC
rpc_handler	A callable that produces an `asio::awaitable<void, Executor>`. The awaitable's return value is ignored. The Executor must be constructible from `asio::get_associated_executor(completion_handler, executor)`, where `completion_handler` is obtained from `token` and `executor` the first argument passed to this function.
token	A completion token for signature `void(std::exception_ptr)`.

Since: 2.7.0

◆ register_awaitable_rpc_handler() [2/2]

template<class ServerRPC , class RPCHandler , class CompletionToken >

auto agrpc::register_awaitable_rpc_handler	(	agrpc::GrpcContext &	grpc_context,
		detail::GetServerRPCServiceT< ServerRPC > &	service,
		RPCHandler &&	rpc_handler,
		CompletionToken &&	token
	)

Register an awaitable rpc handler for the given method (GrpcContext overload)

Since: 2.7.0

◆ register_callback_rpc_handler() [1/2]

template<class ServerRPC , class RPCHandler , class CompletionToken >

auto agrpc::register_callback_rpc_handler	(	const typename ServerRPC::executor_type &	executor,
		detail::GetServerRPCServiceT< ServerRPC > &	service,
		RPCHandler	rpc_handler,
		CompletionToken &&	token
	)

Register a callback rpc handler for the given method.

The rpc handler will be invoked for every incoming request of this gRPC method. It must take ServerRPC::Ptr as first and ServerRPC::Request& as second (only for unary and server-streaming rpcs) argument. The ServerRPC is automatically cancelled during destruction of the ServerRPC::Ptr if finish() was not called earlier.

This asynchronous operation runs forever unless it is cancelled, the rpc handler throws an exception or the server is shutdown (grpc::Server::Shutdown is called). At which point it invokes the completion handler (passing forward the exception thrown by the request handler, if any) after all ServerRPC::Ptrs have been destructed.

Example:

void server_rpc_unary_callback(agrpc::GrpcContext& grpc_context, example::v1::Example::AsyncService& service)
{
    using RPC = agrpc::ServerRPC<&example::v1::Example::AsyncService::RequestUnary>;
    agrpc::register_callback_rpc_handler<RPC>(
        grpc_context, service,
        [](RPC::Ptr ptr, RPC::Request& request)
        {
            RPC::Response response;
            response.set_integer(request.integer());
            auto& rpc = *ptr;
            rpc.finish(response, grpc::Status::OK, [p = std::move(ptr)](bool) {});
        },
        asio::detached);
}

Template Parameters

ServerRPC An instantiation of agrpc::ServerRPC

Parameters

executor	The executor used to handle each rpc
service	The service associated with the gRPC method of the ServerRPC
rpc_handler	A callable that handles the client's request
token	A completion token for signature `void(std::exception_ptr)`.

Since: 2.8.0

◆ register_callback_rpc_handler() [2/2]

template<class ServerRPC , class RPCHandler , class CompletionToken >

auto agrpc::register_callback_rpc_handler	(	agrpc::GrpcContext &	grpc_context,
		detail::GetServerRPCServiceT< ServerRPC > &	service,
		RPCHandler &&	rpc_handler,
		CompletionToken &&	token
	)

Register a callback rpc handler for the given method (GrpcContext overload)

Since: 2.8.0

◆ register_sender_rpc_handler()

template<class ServerRPC , class RPCHandler >

detail::RPCHandlerSender< ServerRPC, RPCHandler > agrpc::register_sender_rpc_handler	(	agrpc::GrpcContext &	grpc_context,
		detail::GetServerRPCServiceT< ServerRPC > &	service,
		RPCHandler	rpc_handler
	)

Register an sender rpc handler for the given method.

The rpc handler will be invoked for every incoming request of this gRPC method. It must take ServerRPC& as first argument and ServerRPC::Request& as second argument (only for unary and server-streaming rpcs). The ServerRPC is automatically cancelled at the end of the rpc handler's sender if finish() was not called earlier.

This asynchronous operation runs forever unless it is cancelled, the rpc handler throws an exception or the server is shutdown (grpc::Server::Shutdown is called). At which point it invokes the receiver (passing forward the exception thrown by the request handler, if any) after all sender produced by invoking the rpc handler complete.

Example:

auto server_rpc_unary_sender(agrpc::GrpcContext& grpc_context, example::v1::Example::AsyncService& service)
{
    using RPC = agrpc::ServerRPC<&example::v1::Example::AsyncService::RequestUnary>;
    return agrpc::register_sender_rpc_handler<RPC>(grpc_context, service,
                                                   [](RPC& rpc, RPC::Request& request)
                                                   {
                                                       return unifex::let_value_with(
                                                           []
                                                           {
                                                               return RPC::Response{};
                                                           },
                                                           [&](auto& response)
                                                           {
                                                               response.set_integer(request.integer());
                                                               return rpc.finish(response, grpc::Status::OK);
                                                           });
                                                   });
}

Template Parameters

ServerRPC An instantiation of agrpc::ServerRPC

Parameters

grpc_context	The GrpcContext used to handle each rpc
service	The service associated with the gRPC method of the ServerRPC
rpc_handler	A callable that produces a sender

Since: 2.7.0

◆ register_yield_rpc_handler() [1/2]

template<class ServerRPC , class RPCHandler , class CompletionToken >

auto agrpc::register_yield_rpc_handler	(	const typename ServerRPC::executor_type &	executor,
		detail::GetServerRPCServiceT< ServerRPC > &	service,
		RPCHandler	rpc_handler,
		CompletionToken &&	token
	)

Register a Boost.Coroutine rpc handler for the given method.

The rpc handler will be invoked for every incoming request of this gRPC method. It must take ServerRPC& as first, ServerRPC::Request& as second (only for unary and server-streaming rpcs) and asio::basic_yield_context<Executor> as third argument. The Executor is obtained by calling asio::get_associated_executor(completion_handler, executor), where completion_handler is created from token and executor the first argument passed to this function. The ServerRPC is automatically cancelled at the end of the rpc handler if finish() was not called earlier.

This asynchronous operation runs forever unless it is cancelled, the rpc handler throws an exception or the server is shutdown (grpc::Server::Shutdown is called). At which point it invokes the completion handler (passing forward the exception thrown by the request handler, if any) after all invocations of the rpc handler return.

Example:

void server_rpc_unary_yield(agrpc::GrpcContext& grpc_context, example::v1::Example::AsyncService& service)
{
    using RPC = agrpc::ServerRPC<&example::v1::Example::AsyncService::RequestUnary>;
    agrpc::register_yield_rpc_handler<RPC>(
        grpc_context, service,
        [](RPC& rpc, RPC::Request& request, const asio::yield_context& yield)
        {
            RPC::Response response;
            response.set_integer(request.integer());
            rpc.finish(response, grpc::Status::OK, yield);
        },
        asio::detached);
}

Template Parameters

ServerRPC An instantiation of agrpc::ServerRPC

Parameters

executor	The executor used to handle each rpc
service	The service associated with the gRPC method of the ServerRPC
rpc_handler	A callable that takes an `asio::basic_yield_context<Executor>` as last argument. The return value is ignored. The Executor must be constructible from `asio::get_associated_executor(completion_handler, executor)`, where `completion_handler` is obtained from `token` and `executor` the first argument passed to this function.
token	A completion token for signature `void(std::exception_ptr)`.

Since: 2.7.0

◆ register_yield_rpc_handler() [2/2]

template<class ServerRPC , class RPCHandler , class CompletionToken >

auto agrpc::register_yield_rpc_handler	(	agrpc::GrpcContext &	grpc_context,
		detail::GetServerRPCServiceT< ServerRPC > &	service,
		RPCHandler &&	rpc_handler,
		CompletionToken &&	token
	)

Register a rpc handler for the given method (GrpcContext overload)

Since: 2.7.0

◆ run() [1/2]

template<class Traits = agrpc::DefaultRunTraits, class ExecutionContext = void>

void agrpc::run	(	agrpc::GrpcContext &	grpc_context,
		ExecutionContext &	execution_context
	)

(experimental) Run an execution context in the same thread as a GrpcContext

The GrpcContext should be in the ready state when this function is invoked, other than that semantically identical to GrpcContext::run(). This function ends when the GrpcContext is stopped, e.g. because it ran out of work.

Template Parameters

Traits See DefaultRunTraits

Since: 1.7.0

◆ run() [2/2]

template<class Traits = agrpc::DefaultRunTraits, class ExecutionContext = void, class StopCondition = void>

void agrpc::run	(	agrpc::GrpcContext &	grpc_context,
		ExecutionContext &	execution_context,
		StopCondition	stop_condition
	)

(experimental) Run an execution context in the same thread as a GrpcContext

The GrpcContext should be in the ready state when this function is invoked, other than that semantically identical to GrpcContext::run(). This function ends when the stop_condition returns true.

Template Parameters

Traits See DefaultRunTraits

Since: 1.7.0

◆ run_completion_queue() [1/2]

template<class Traits = agrpc::DefaultRunTraits, class ExecutionContext = void>

void agrpc::run_completion_queue	(	agrpc::GrpcContext &	grpc_context,
		ExecutionContext &	execution_context
	)

(experimental) Run an execution context in the same thread as a GrpcContext's completion queue

The GrpcContext should be in the ready state when this function is invoked, other than that semantically identical to GrpcContext::run_completion_queue(). This function ends when the GrpcContext is stopped, e.g. because it ran out of work.

Template Parameters

Traits See DefaultRunTraits

Since: 2.0.0

◆ run_completion_queue() [2/2]

template<class Traits = agrpc::DefaultRunTraits, class ExecutionContext = void, class StopCondition = void>

void agrpc::run_completion_queue	(	agrpc::GrpcContext &	grpc_context,
		ExecutionContext &	execution_context,
		StopCondition	stop_condition
	)

(experimental) Run an execution context in the same thread as a GrpcContext's completion queue

The GrpcContext should be in the ready state when this function is invoked, other than that semantically identical to GrpcContext::run_completion_queue(). This function ends when the stop_condition returns true.

Template Parameters

Traits See DefaultRunTraits

Since: 2.0.0

◆ process_grpc_tag()

void agrpc::process_grpc_tag	(	agrpc::GrpcContext &	grpc_context,
		void *	tag,
		bool	ok
	)

inline

Test utility to manually process gRPC tags.

This function can be used to process gRPC tags in places where the tag does not go through the grpc::CompletionQueue, for example in mocked stubs. It processes the tag in a manner equivalent to asio::post.

Example using Google Mock:

    // Setup mock stub
    struct MockResponseReader : grpc::ClientAsyncResponseReaderInterface<example::v1::Response>
    {
        MOCK_METHOD0(StartCall, void());
        MOCK_METHOD1(ReadInitialMetadata, void(void*));
        MOCK_METHOD3(Finish, void(example::v1::Response*, grpc::Status*, void*));
    };
    testing::NiceMock<example::v1::MockExampleStub> mock_stub;
    testing::NiceMock<MockResponseReader> mock_reader;
    EXPECT_CALL(mock_reader, Finish)
        .WillOnce(
            [&](example::v1::Response* response, grpc::Status* status, void* tag)
            {
                *status = grpc::Status::OK;
                response->set_integer(42);
                agrpc::process_grpc_tag(grpc_context, tag, true);
            });
    EXPECT_CALL(mock_stub, AsyncUnaryRaw).WillOnce(testing::Return(&mock_reader));
 
    // Inject mock_stub into code under test
    using RPC = agrpc::ClientRPC<&example::v1::Example::StubInterface::AsyncUnary>;
    grpc::ClientContext client_context;
    example::v1::Response response;
    example::v1::Request request;
    const grpc::Status status =
        co_await RPC::request(grpc_context, mock_stub, client_context, request, response, asio::use_awaitable);
 
    assert(status.ok());
    assert(42 == response.integer());

Since: 1.7.0

Variable Documentation

◆ notify_on_state_change

constexpr detail::NotifyOnStateChangeFn agrpc::notify_on_state_change {}

inlineconstexpr

Set notification for a grpc::Channel state change.

Function to set notification for a grpc::Channel state change.

Since: 2.3.0

◆ read

constexpr detail::ReadFn agrpc::read {}

inlineconstexpr

Read from a streaming RPC.

Client and server-side function to read from streaming RPCs.

◆ use_sender

constexpr agrpc::UseSender agrpc::use_sender {}

inlineconstexpr

Instance and factory for sender completion tokens.

Sender completion token.

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ GenericUnaryClientRPC

◆ GenericStreamingClientRPC

◆ GrpcExecutor

◆ GenericServerRPC

Enumeration Type Documentation

◆ ClientRPCType

◆ ServerRPCType

Function Documentation

◆ register_awaitable_rpc_handler() [1/2]

◆ register_awaitable_rpc_handler() [2/2]

◆ register_callback_rpc_handler() [1/2]

◆ register_callback_rpc_handler() [2/2]

◆ register_sender_rpc_handler()

◆ register_yield_rpc_handler() [1/2]

◆ register_yield_rpc_handler() [2/2]

◆ run() [1/2]

◆ run() [2/2]

◆ run_completion_queue() [1/2]

◆ run_completion_queue() [2/2]

◆ process_grpc_tag()

Variable Documentation

◆ notify_on_state_change

◆ read

◆ use_sender