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

#include <agrpc/client_rpc.hpp>

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

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

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

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, ResponseT &response, CompletionToken &&token=detail::DefaultCompletionTokenT< Executor >{})
	Start a client-streaming request. More...

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

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

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	write (const RequestT &request, CompletionToken &&token=detail::DefaultCompletionTokenT< Executor >{})
	Send a message to the server. More...

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	finish (CompletionToken &&token=detail::DefaultCompletionTokenT< Executor >{})
	Finish the rpc. 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::CLIENT_STREAMING
	The rpc type.

Detailed Description

template<class StubT, class RequestT, class ResponseT, template< class > class ResponderT, detail::PrepareAsyncClientClientStreamingRequest< StubT, ResponderT< RequestT >, ResponseT > PrepareAsyncClientStreaming, class Executor>
class agrpc::ClientRPC< PrepareAsyncClientStreaming, Executor >

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

Example:

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

PrepareAsyncClientStreaming	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::PrepareAsyncClientClientStreamingRequest< StubT, ResponderT< RequestT >, ResponseT > PrepareAsyncClientStreaming, class Executor >

static constexpr std::string_view agrpc::ClientRPC< PrepareAsyncClientStreaming, Executor >::service_name ( )

inlinestaticconstexprnoexcept

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::PrepareAsyncClientClientStreamingRequest< StubT, ResponderT< RequestT >, ResponseT > PrepareAsyncClientStreaming, class Executor >

static constexpr std::string_view agrpc::ClientRPC< PrepareAsyncClientStreaming, Executor >::method_name ( )

inlinestaticconstexprnoexcept

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::PrepareAsyncClientClientStreamingRequest< StubT, ResponderT< RequestT >, ResponseT > PrepareAsyncClientStreaming, class Executor >

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

auto agrpc::ClientRPC< PrepareAsyncClientStreaming, Executor >::start	(	StubT &	stub,
		ResponseT &	response,
		CompletionToken &&	token = `detail::DefaultCompletionTokenT<Executor>{}`
	)

inline

Start a client-streaming request.

Attention: This function may not be used with the initial_metadata_corked option set.

Parameters

stub	The Stub that corresponds to the gRPC method.
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(bool)`. `true` means that the rpc was started successfully. If it is `false`, then call `finish` to obtain error details.

◆ read_initial_metadata()

template<class StubT , class RequestT , class ResponseT , template< class > class ResponderT, detail::PrepareAsyncClientClientStreamingRequest< StubT, ResponderT< RequestT >, ResponseT > PrepareAsyncClientStreaming, class Executor >

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

auto agrpc::ClientRPC< PrepareAsyncClientStreaming, Executor >::read_initial_metadata ( CompletionToken && token = detail::DefaultCompletionTokenT<Executor>{} )

inline

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.

◆ write() [1/2]

template<class StubT , class RequestT , class ResponseT , template< class > class ResponderT, detail::PrepareAsyncClientClientStreamingRequest< StubT, ResponderT< RequestT >, ResponseT > PrepareAsyncClientStreaming, class Executor >

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

auto agrpc::ClientRPC< PrepareAsyncClientStreaming, Executor >::write	(	const RequestT &	request,
		grpc::WriteOptions	options,
		CompletionToken &&	token = `detail::DefaultCompletionTokenT<Executor>{}`
	)

inline

Send a message to the server.

WriteOptions options is used to set the write options of this message, otherwise identical to: write(request, token).

◆ write() [2/2]

template<class StubT , class RequestT , class ResponseT , template< class > class ResponderT, detail::PrepareAsyncClientClientStreamingRequest< StubT, ResponderT< RequestT >, ResponseT > PrepareAsyncClientStreaming, class Executor >

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

auto agrpc::ClientRPC< PrepareAsyncClientStreaming, Executor >::write	(	const RequestT &	request,
		CompletionToken &&	token = `detail::DefaultCompletionTokenT<Executor>{}`
	)

inline

Send a message to the server.

Only one write may be outstanding at any given time. May not be called concurrently with read_initial_metadata.

Parameters

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 data 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 StubT , class RequestT , class ResponseT , template< class > class ResponderT, detail::PrepareAsyncClientClientStreamingRequest< StubT, ResponderT< RequestT >, ResponseT > PrepareAsyncClientStreaming, class Executor >

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

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

inline

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.

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.
Attempts to fill in the response parameter that was passed to start.

Parameters

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

◆ 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< RequestT > >::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

◆ service_name()

◆ method_name()

◆ start()

◆ read_initial_metadata()

◆ write() [1/2]

◆ write() [2/2]

◆ finish()

◆ get_executor()

◆ get_scheduler()

◆ cancel()