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

#include <agrpc/client_rpc.hpp>

Inheritance diagram for agrpc::ClientRPC< agrpc::ClientRPCType::GENERIC_STREAMING, Executor >:

Collaboration diagram for agrpc::ClientRPC< agrpc::ClientRPCType::GENERIC_STREAMING, Executor >:

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

Public Types
using	Stub = grpc::GenericStub
	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 (const std::string &method, grpc::GenericStub &stub, CompletionToken &&token=CompletionToken{})
	Start a generic streaming request.

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

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

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

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

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	writes_done (CompletionToken &&token=CompletionToken{})
	Signal writes done to the server.

template<class CompletionToken = detail::DefaultCompletionTokenT<Executor>>
auto	finish (CompletionToken &&token=CompletionToken{})
	Signal writes done and finish the rpc.

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

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

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.

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

Detailed Description

template<class Executor>
class agrpc::ClientRPC< agrpc::ClientRPCType::GENERIC_STREAMING, Executor >

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

Template Parameters

Executor The executor type, must be capable of referring to a 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

◆ start()

template<class Executor >

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

auto agrpc::ClientRPC< agrpc::ClientRPCType::GENERIC_STREAMING, Executor >::start	(	const std::string &	method,
		grpc::GenericStub &	stub,
		CompletionToken &&	token = CompletionToken{} )

inline

Start a generic streaming request.

Parameters

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 RequestT , class ResponseT , template< class, class > class ResponderT, class Executor >

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

auto agrpc::detail::ClientRPCBidiStreamingBase< ResponderT< RequestT, ResponseT >, Executor >::read_initial_metadata ( CompletionToken && token = CompletionToken{} )

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 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.

◆ read()

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

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

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

inlineinherited

Receive a message from the server.

This is thread-safe with respect to write() or writes_done() methods. It should not be called concurrently with other operations. 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).

◆ write()

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

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

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

inlineinherited

Send a message to the server.

Only one write may be outstanding at any given time. This is thread-safe with respect to read(). It should not be called concurrently with other operations.

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).

◆ writes_done()

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

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

auto agrpc::detail::ClientRPCBidiStreamingBase< ResponderT< RequestT, ResponseT >, Executor >::writes_done ( CompletionToken && token = CompletionToken{} )

inlineinherited

Signal writes done to the server.

May only be called once. Should not be called after performing a write with the set_last_message option.

Signal the client is done with the writes (half-close the client stream). Thread-safe with respect to read. May not be called concurrently with a write() that has the set_last_message option set.

Parameters

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 RequestT , class ResponseT , template< class, class > class ResponderT, class Executor >

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

auto agrpc::detail::ClientRPCBidiStreamingBase< ResponderT< RequestT, ResponseT >, Executor >::finish ( CompletionToken && token = CompletionToken{} )

inlineinherited

Signal writes done and 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).

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

void agrpc::detail::ClientRPCContextBase< ResponderT< RequestT, ResponseT > >::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

◆ start()

◆ read_initial_metadata()

◆ read()

◆ write()

◆ writes_done()

◆ finish()

◆ get_executor()

◆ get_scheduler()

◆ cancel()