asio-grpc v3.5.0
Asynchronous gRPC with Asio/unified executors
Loading...
Searching...
No Matches
agrpc::ClientRPC< agrpc::ClientRPCType::GENERIC_STREAMING, Executor > Class Template Reference

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_typeget_executor () const noexcept
 Get the executor.
 
const executor_typeget_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
ExecutorThe 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
tokenA 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
tokenA 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
tokenA 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
requestThe request message, save to delete when this function returns, unless a deferred completion token is used like agrpc::use_sender or asio::deferred.
tokenA 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
tokenA 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
tokenA 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