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

#include <agrpc/client_rpc.hpp>

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

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

Public Types
using	Stub = StubT
	The stub type.

using	Request = RequestT
	The request message type.

using	Response = ResponseT
	The response message type.

using	executor_type = Executor
	The executor type.

Public Member Functions
template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	start (StubT &stub, const RequestT &request, CompletionToken &&token=detail::DefaultCompletionTokenT< Executor >{})
	Start a server-streaming request. More...

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	read (ResponseT &response, CompletionToken &&token=detail::DefaultCompletionTokenT< Executor >{})
	Receive a message from the server. More...

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	finish (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...

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

Detailed Description

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

I/O object for client-side, server-streaming rpcs.

Example:

asio::awaitable<void> client_rpc_server_streaming(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::PrepareAsyncServerStreaming>>;
 
    RPC rpc{grpc_context};
    rpc.context().set_deadline(std::chrono::system_clock::now() +
                               std::chrono::seconds(5));
 
    RPC::Request request;
    request.set_integer(42);
    if (!co_await rpc.start(stub, request))
    {
        const grpc::Status status = co_await rpc.finish();
        std::cerr << "Rpc failed: " << status.error_message();
        co_return;
    }
 
    RPC::Response response;
    while (co_await rpc.read(response))
    {
        std::cout << "Response: " << response.integer() << '\n';
    }
 
    const grpc::Status status = co_await rpc.finish();
    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

PrepareAsyncServerStreaming	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. After successful cancellation no further operations may be started on the rpc (except finish). 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::PrepareAsyncClientServerStreamingRequest< StubT, RequestT, ResponderT< ResponseT > > PrepareAsyncServerStreaming, class Executor >

static constexpr std::string_view agrpc::detail::ClientRPCServerStreamingBase< PrepareAsyncServerStreaming, 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::PrepareAsyncClientServerStreamingRequest< StubT, RequestT, ResponderT< ResponseT > > PrepareAsyncServerStreaming, class Executor >

static constexpr std::string_view agrpc::detail::ClientRPCServerStreamingBase< PrepareAsyncServerStreaming, 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

◆ start()

template<class StubT , class RequestT , class ResponseT , template< class > class ResponderT, detail::PrepareAsyncClientServerStreamingRequest< StubT, RequestT, ResponderT< ResponseT > > PrepareAsyncServerStreaming, class Executor >

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

auto agrpc::detail::ClientRPCServerStreamingBase< PrepareAsyncServerStreaming, Executor >::start	(	StubT &	stub,
		const RequestT &	request,
		CompletionToken &&	token = `detail::DefaultCompletionTokenT<Executor>{}`
	)

inlineinherited

Start a server-streaming request.

Parameters

stub	The Stub that corresponds to the gRPC method.
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`.
token	A completion token like `asio::yield_context` or `agrpc::use_sender`. The completion signature is `void(bool)`. `true` means that the rpc was started successfully. If it is `false`, then call `finish` to obtain error details.

◆ read()

template<class StubT , class RequestT , class ResponseT , template< class > class ResponderT, detail::PrepareAsyncClientServerStreamingRequest< StubT, RequestT, ResponderT< ResponseT > > PrepareAsyncServerStreaming, class Executor >

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

auto agrpc::detail::ClientRPCServerStreamingBase< PrepareAsyncServerStreaming, Executor >::read	(	ResponseT &	response,
		CompletionToken &&	token = `detail::DefaultCompletionTokenT<Executor>{}`
	)

inlineinherited

Receive a message from the server.

May not be called concurrently with read_initial_metadata. It is not meaningful to call it concurrently with another read on the same stream 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 server is finished sending messages or the stream has failed (or been cancelled).

◆ finish()

template<class StubT , class RequestT , class ResponseT , template< class > class ResponderT, detail::PrepareAsyncClientServerStreamingRequest< StubT, RequestT, ResponderT< ResponseT > > PrepareAsyncServerStreaming, class Executor >

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

auto agrpc::detail::ClientRPCServerStreamingBase< PrepareAsyncServerStreaming, Executor >::finish ( CompletionToken && token = detail::DefaultCompletionTokenT<Executor>{} )

inlineinherited

Finish the rpc.

Indicate that the stream is to be finished and request notification for when the call has been ended.

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

It is appropriate to call this method when:

All messages from the server have been received (either known implictly, or explicitly because a previous read operation returned false).

The operation will finish when either:

The server has returned a status.
The call failed for some reason and the library generated a status.

Note that implementations of this method attempt to receive initial metadata from the server if initial metadata has not been received yet.

Side effect:

The ClientContext associated with the call is updated with possible initial and trailing metadata received 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()

◆ start()

◆ read()

◆ finish()

◆ read_initial_metadata()

◆ get_executor()

◆ get_scheduler()

◆ cancel()