asio-grpc v1.6.0
Asynchronous gRPC with Asio/unified executors
agrpc::detail::RequestFn Struct Reference

Client and server-side function object to start RPCs. More...

#include <agrpc/rpc.hpp>

Public Member Functions

template<class RPC , class Service , class Request , class Responder , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (detail::ServerMultiArgRequest< RPC, Request, Responder > rpc, Service &service, grpc::ServerContext &server_context, Request &request, Responder &responder, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Wait for a unary or server-streaming RPC request from a client. More...
 
template<class RPC , class Service , class Responder , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (detail::ServerSingleArgRequest< RPC, Responder > rpc, Service &service, grpc::ServerContext &server_context, Responder &responder, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Wait for a client-streaming or bidirectional-streaming RPC request from a client. More...
 
template<class Stub , class Request , class Response , class Executor = asio::any_io_executor>
auto operator() (detail::ClientUnaryRequest< Stub, Request, Response > rpc, Stub &stub, grpc::ClientContext &client_context, const Request &request, asio::use_awaitable_t< Executor > token={}) const -> typename asio::async_result< asio::use_awaitable_t< Executor >, void(std::unique_ptr< grpc::ClientAsyncResponseReader< Response > >)>::return_type
 Convenience function for starting a unary request. More...
 
template<class Stub , class Request , class Response , class Executor = asio::any_io_executor>
auto operator() (detail::ClientUnaryRequest< Stub, Request, Response > rpc, Stub &stub, grpc::ClientContext &client_context, const Request &request, std::unique_ptr< grpc::ClientAsyncResponseReader< Response > > &reader, asio::use_awaitable_t< Executor > token={}) const -> typename asio::async_result< asio::use_awaitable_t< Executor >, void()>::return_type
 Convenience function for starting a unary request. More...
 
template<class Stub , class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (detail::ClientServerStreamingRequest< Stub, Request, Response > rpc, Stub &stub, grpc::ClientContext &client_context, const Request &request, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Convenience function for starting a server-streaming request. More...
 
template<class Stub , class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (detail::ClientServerStreamingRequest< Stub, Request, Response > rpc, Stub &stub, grpc::ClientContext &client_context, const Request &request, std::unique_ptr< grpc::ClientAsyncReader< Response > > &reader, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Start a server-streaming request. More...
 
template<class Stub , class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (detail::ClientClientStreamingRequest< Stub, Request, Response > rpc, Stub &stub, grpc::ClientContext &client_context, Response &response, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Convenience function for starting a client-streaming request. More...
 
template<class Stub , class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (detail::ClientClientStreamingRequest< Stub, Request, Response > rpc, Stub &stub, grpc::ClientContext &client_context, std::unique_ptr< grpc::ClientAsyncWriter< Request > > &writer, Response &response, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Start a client-streaming request. More...
 
template<class Stub , class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (detail::ClientBidirectionalStreamingRequest< Stub, Request, Response > rpc, Stub &stub, grpc::ClientContext &client_context, CompletionToken &&token={}) const
 Convenience function for starting a bidirectional-streaming request. More...
 
template<class Stub , class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto operator() (detail::ClientBidirectionalStreamingRequest< Stub, Request, Response > rpc, Stub &stub, grpc::ClientContext &client_context, std::unique_ptr< grpc::ClientAsyncReaderWriter< Request, Response > > &reader_writer, CompletionToken &&token={}) const noexcept(detail::IS_NOTRHOW_GRPC_INITIATE_COMPLETION_TOKEN< CompletionToken >)
 Start a bidirectional-streaming request. More...
 

Detailed Description

Client and server-side function object to start RPCs.

The examples below are based on the following .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;
}
Attention
The completion handler created from the completion token that is provided to the functions described below must have an associated executor that refers to a GrpcContext:
asio::io_context io_context;
asio::co_spawn(
io_context,
[&]() -> asio::awaitable<void>
{
grpc::ServerContext server_context;
grpc::ServerAsyncReader<example::v1::Response, example::v1::Request> reader{&server_context};
// error: asio::this_coro::executor does not refer to a GrpcContext
// co_await agrpc::request(&example::v1::Example::AsyncService::RequestClientStreaming, service,
// server_context, reader, asio::use_awaitable);
// correct:
co_await agrpc::request(&example::v1::Example::AsyncService::RequestClientStreaming, service,
server_context, reader, asio::bind_executor(grpc_context, asio::use_awaitable));
},
asio::detached);
constexpr detail::RequestFn request
Start a new RPC.
Definition: rpc.hpp:1493

Per-Operation Cancellation

None. gRPC does not support cancellation of requests.

Member Function Documentation

◆ operator()() [1/10]

template<class Stub , class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::RequestFn::operator() ( detail::ClientBidirectionalStreamingRequest< Stub, Request, Response >  rpc,
Stub &  stub,
grpc::ClientContext &  client_context,
CompletionToken &&  token = {} 
) const
inline

Convenience function for starting a bidirectional-streaming request.

Sends std::unique_ptr<grpc::ClientAsyncWriter<Request>> through the completion handler, otherwise identical to operator()(ClientClientStreamingRequest, Stub&, ClientContext&, Writer&, Response&, CompletionToken&&)

Example:

grpc::ClientContext client_context;
auto [reader_writer, request_ok] = co_await agrpc::request(&example::v1::Example::Stub::AsyncBidirectionalStreaming,
stub, client_context, asio::use_awaitable);
Parameters
rpcA pointer to the async version of the RPC method. The async version always starts with Async.
stubThe Stub that corresponds to the RPC method. In the example above the stub is: example::v1::Example::Stub.
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(std::pair<std::unique_ptr<grpc::ClientAsyncWriter<Request>>, bool>). true indicates that the RPC is going to go to the wire. If it is false, it is not going to the wire. This would happen if the channel is either permanently broken or transiently broken but with the fail-fast option.

◆ operator()() [2/10]

template<class Stub , class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::RequestFn::operator() ( detail::ClientBidirectionalStreamingRequest< Stub, Request, Response >  rpc,
Stub &  stub,
grpc::ClientContext &  client_context,
std::unique_ptr< grpc::ClientAsyncReaderWriter< Request, Response > > &  reader_writer,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Start a bidirectional-streaming request.

Example:

grpc::ClientContext client_context;
std::unique_ptr<grpc::ClientAsyncReaderWriter<example::v1::Request, example::v1::Response>> reader_writer;
bool request_ok = co_await agrpc::request(&example::v1::Example::Stub::AsyncBidirectionalStreaming, stub,
client_context, reader_writer, asio::use_awaitable);
Attention
Do not use this function with the initial_metadata_corked option set. Call the member function directly instead:
grpc::ClientContext client_context;
client_context.set_initial_metadata_corked(true);
auto reader_writer =
stub.AsyncBidirectionalStreaming(&client_context, agrpc::get_completion_queue(grpc_context), nullptr);
constexpr detail::GetCompletionQueueFn get_completion_queue
Get grpc::CompletionQueue* from an object.
Definition: getCompletionQueue.hpp:107
Parameters
rpcA pointer to the async version of the RPC method. The async version always starts with Async.
stubThe Stub that corresponds to the RPC method. In the example above the stub is: example::v1::Example::Stub.
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(bool). true indicates that the RPC is going to go to the wire. If it is false, it is not going to the wire. This would happen if the channel is either permanently broken or transiently broken but with the fail-fast option.

◆ operator()() [3/10]

template<class Stub , class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::RequestFn::operator() ( detail::ClientClientStreamingRequest< Stub, Request, Response >  rpc,
Stub &  stub,
grpc::ClientContext &  client_context,
Response &  response,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Convenience function for starting a client-streaming request.

Sends std::unique_ptr<grpc::ClientAsyncWriter<Request>> through the completion handler, otherwise identical to operator()(ClientClientStreamingRequest, Stub&, ClientContext&, Writer&, Response&, CompletionToken&&)

Example:

grpc::ClientContext client_context;
example::v1::Response response;
auto [writer, request_ok] = co_await agrpc::request(&example::v1::Example::Stub::AsyncClientStreaming, stub,
client_context, response, asio::use_awaitable);
Parameters
rpcA pointer to the async version of the RPC method. The async version always starts with Async.
stubThe Stub that corresponds to the RPC method. In the example above the stub is: example::v1::Example::Stub.
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(std::pair<std::unique_ptr<grpc::ClientAsyncWriter<Request>>, bool>). true indicates that the RPC is going to go to the wire. If it is false, it is not going to the wire. This would happen if the channel is either permanently broken or transiently broken but with the fail-fast option.

◆ operator()() [4/10]

template<class Stub , class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::RequestFn::operator() ( detail::ClientClientStreamingRequest< Stub, Request, Response >  rpc,
Stub &  stub,
grpc::ClientContext &  client_context,
std::unique_ptr< grpc::ClientAsyncWriter< Request > > &  writer,
Response &  response,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Start a client-streaming request.

Example:

grpc::ClientContext client_context;
example::v1::Response response;
std::unique_ptr<grpc::ClientAsyncWriter<example::v1::Request>> writer;
bool request_ok = co_await agrpc::request(&example::v1::Example::Stub::AsyncClientStreaming, stub, client_context,
writer, response, asio::use_awaitable);
Attention
Do not use this function with the initial_metadata_corked option set. Call the member function directly instead:
grpc::ClientContext client_context;
client_context.set_initial_metadata_corked(true);
example::v1::Response response;
auto writer =
stub.AsyncClientStreaming(&client_context, &response, agrpc::get_completion_queue(grpc_context), nullptr);
Parameters
rpcA pointer to the async version of the RPC method. The async version always starts with Async.
stubThe Stub that corresponds to the RPC method. In the example above the stub is: example::v1::Example::Stub.
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(bool). true indicates that the RPC is going to go to the wire. If it is false, it is not going to the wire. This would happen if the channel is either permanently broken or transiently broken but with the fail-fast option.

◆ operator()() [5/10]

template<class Stub , class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::RequestFn::operator() ( detail::ClientServerStreamingRequest< Stub, Request, Response >  rpc,
Stub &  stub,
grpc::ClientContext &  client_context,
const Request &  request,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Convenience function for starting a server-streaming request.

Sends std::unique_ptr<grpc::ClientAsyncReader<Response>> through the completion handler, otherwise identical to operator()(ClientServerStreamingRequest, Stub&, ClientContext&, const Request&, Reader&, CompletionToken&&)

Example:

grpc::ClientContext client_context;
example::v1::Request request;
auto [reader, request_ok] = co_await agrpc::request(&example::v1::Example::Stub::AsyncServerStreaming, stub,
client_context, request, asio::use_awaitable);
Parameters
rpcA pointer to the async version of the RPC method. The async version always starts with Async.
stubThe Stub that corresponds to the RPC method. In the example above the stub is: example::v1::Example::Stub.
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(std::pair<std::unique_ptr<grpc::ClientAsyncReader<Response>>, bool>). true indicates that the RPC is going to go to the wire. If it is false, it is not going to the wire. This would happen if the channel is either permanently broken or transiently broken but with the fail-fast option.

◆ operator()() [6/10]

template<class Stub , class Request , class Response , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::RequestFn::operator() ( detail::ClientServerStreamingRequest< Stub, Request, Response >  rpc,
Stub &  stub,
grpc::ClientContext &  client_context,
const Request &  request,
std::unique_ptr< grpc::ClientAsyncReader< Response > > &  reader,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Start a server-streaming request.

Example:

grpc::ClientContext client_context;
example::v1::Request request;
std::unique_ptr<grpc::ClientAsyncReader<example::v1::Response>> reader;
bool request_ok = co_await agrpc::request(&example::v1::Example::Stub::AsyncServerStreaming, stub, client_context,
request, reader, asio::use_awaitable);
Parameters
rpcA pointer to the async version of the RPC method. The async version always starts with Async.
stubThe Stub that corresponds to the RPC method. In the example above the stub is: example::v1::Example::Stub.
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(bool). true indicates that the RPC is going to go to the wire. If it is false, it is not going to the wire. This would happen if the channel is either permanently broken or transiently broken but with the fail-fast option.

◆ operator()() [7/10]

template<class Stub , class Request , class Response , class Executor = asio::any_io_executor>
auto agrpc::detail::RequestFn::operator() ( detail::ClientUnaryRequest< Stub, Request, Response >  rpc,
Stub &  stub,
grpc::ClientContext &  client_context,
const Request &  request,
asio::use_awaitable_t< Executor >  token = {} 
) const -> typename asio::async_result<asio::use_awaitable_t<Executor>, void(std::unique_ptr<grpc::ClientAsyncResponseReader<Response>>)>::return_type
inline

Convenience function for starting a unary request.

Example:

grpc::ClientContext client_context;
example::v1::Request request;
std::unique_ptr<grpc::ClientAsyncResponseReader<example::v1::Response>> reader =
co_await agrpc::request(&example::v1::Example::Stub::AsyncUnary, stub, client_context, request);
Note
For better performance use:
grpc::ClientContext client_context;
example::v1::Request request;
std::unique_ptr<grpc::ClientAsyncResponseReader<example::v1::Response>> reader =
stub.AsyncUnary(&client_context, request, agrpc::get_completion_queue(grpc_context));
instead.
Parameters
rpcA pointer to the async version of the RPC method. The async version always starts with Async.
stubThe Stub that corresponds to the RPC method. In the example above the stub is: example::v1::Example::Stub.

◆ operator()() [8/10]

template<class Stub , class Request , class Response , class Executor = asio::any_io_executor>
auto agrpc::detail::RequestFn::operator() ( detail::ClientUnaryRequest< Stub, Request, Response >  rpc,
Stub &  stub,
grpc::ClientContext &  client_context,
const Request &  request,
std::unique_ptr< grpc::ClientAsyncResponseReader< Response > > &  reader,
asio::use_awaitable_t< Executor >  token = {} 
) const -> typename asio::async_result<asio::use_awaitable_t<Executor>, void()>::return_type
inline

Convenience function for starting a unary request.

Takes std::unique_ptr<grpc::ClientAsyncResponseReader<Response>> as an output parameter, otherwise identical to: operator()(ClientUnaryRequest, Stub&, ClientContext&, const Request&, use_awaitable_t<Executor>)

◆ operator()() [9/10]

template<class RPC , class Service , class Request , class Responder , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::RequestFn::operator() ( detail::ServerMultiArgRequest< RPC, Request, Responder >  rpc,
Service &  service,
grpc::ServerContext &  server_context,
Request &  request,
Responder &  responder,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Wait for a unary or server-streaming RPC request from a client.

Unary RPC:

grpc::ServerContext server_context;
example::v1::Request request;
grpc::ServerAsyncResponseWriter<example::v1::Response> writer{&server_context};
bool request_ok = co_await agrpc::request(&example::v1::Example::AsyncService::RequestUnary, service,
server_context, request, writer, asio::use_awaitable);

Server-streaming RPC:

grpc::ServerContext server_context;
example::v1::Request request;
grpc::ServerAsyncWriter<example::v1::Response> writer{&server_context};
bool request_ok = co_await agrpc::request(&example::v1::Example::AsyncService::RequestServerStreaming, service,
server_context, request, writer, asio::use_awaitable);
Parameters
rpcA pointer to the async version of the RPC method. The async version always starts with Request.
serviceThe AsyncService that corresponds to the RPC method. In the examples above the service is: example::v1::Example::AsyncService.
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(bool). true indicates that the RPC has indeed been started. If it is false then the server has been Shutdown before this particular call got matched to an incoming RPC.

◆ operator()() [10/10]

template<class RPC , class Service , class Responder , class CompletionToken = agrpc::DefaultCompletionToken>
auto agrpc::detail::RequestFn::operator() ( detail::ServerSingleArgRequest< RPC, Responder >  rpc,
Service &  service,
grpc::ServerContext &  server_context,
Responder &  responder,
CompletionToken &&  token = {} 
) const
inlinenoexcept

Wait for a client-streaming or bidirectional-streaming RPC request from a client.

Client-streaming RPC:

grpc::ServerContext server_context;
grpc::ServerAsyncReader<example::v1::Response, example::v1::Request> reader{&server_context};
bool request_ok = co_await agrpc::request(&example::v1::Example::AsyncService::RequestClientStreaming, service,
server_context, reader, asio::use_awaitable);

Bidirectional-streaming RPC:

grpc::ServerContext server_context;
grpc::ServerAsyncReaderWriter<example::v1::Response, example::v1::Request> reader_writer{&server_context};
bool request_ok = co_await agrpc::request(&example::v1::Example::AsyncService::RequestBidirectionalStreaming,
service, server_context, reader_writer, asio::use_awaitable);
Parameters
rpcA pointer to the async version of the RPC method. The async version always starts with Request.
serviceThe AsyncService that corresponds to the RPC method. In the examples above the service is: example::v1::Example::AsyncService.
tokenA completion token like asio::yield_context or the one created by agrpc::use_sender. The completion signature is void(bool). true indicates that the RPC has indeed been started. If it is false then the server has been Shutdown before this particular call got matched to an incoming RPC.