userver: ugrpc::client::BidirectionalStream< Request, Response > Class Template Reference
Loading...
Searching...
No Matches
ugrpc::client::BidirectionalStream< Request, Response > Class Template Referencefinal

#include <userver/ugrpc/client/rpc.hpp>

Detailed Description

template<typename Request, typename Response>
class ugrpc::client::BidirectionalStream< Request, Response >

Controls a request stream -> response stream RPC.

It is safe to call the following methods from different coroutines:

  • GetContext;
  • one of (Read, ReadAsync);
  • one of (Write, WritesDone).

WriteAndCheck is NOT thread-safe.

The RPC is cancelled on destruction unless the stream is closed (Read has returned false). In that case the connection is not closed (it will be reused for new RPCs), and the server receives RpcInterruptedError immediately. gRPC provides no way to early-close a server-streaming RPC gracefully.

Read and AsyncRead can throw if error status is received from server. User MUST NOT call Read or AsyncRead again after failure of any of these operations.

Write and WritesDone methods do not throw, but indicate issues with the RPC by returning false.

WriteAndCheck is intended for ping-pong scenarios, when after write operation the user calls Read and vice versa.

If Write or WritesDone returns negative result, the user MUST NOT call any of these methods anymore. Instead the user SHOULD call Read method until the end of input. If Write or WritesDone finishes with negative result, finally Read will throw an exception.

Usage example:

auto write_task = engine::AsyncNoSpan([&stream, &requests] {
for (const auto& request : requests) {
const bool success = stream.Write(request);
if (!success) return false;
}
return stream.WritesDone();
});
sample::ugrpc::StreamGreetingResponse response;
while (stream.Read(response)) {
responses.push_back(std::move(response));
}
ASSERT_TRUE(write_task.Get());

Definition at line 364 of file rpc.hpp.

+ Inheritance diagram for ugrpc::client::BidirectionalStream< Request, Response >:

Public Member Functions

bool Read (Response &response)
 Await and read the next incoming message.
 
StreamReadFuture< BidirectionalStreamReadAsync (Response &response) noexcept
 Return future to read next incoming result.
 
bool Write (const Request &request)
 Write the next outgoing message.
 
void WriteAndCheck (const Request &request)
 Write the next outgoing message and check result.
 
bool WritesDone ()
 Announce end-of-output to the server.
 
 BidirectionalStream (BidirectionalStream &&) noexcept=default
 
BidirectionalStreamoperator= (BidirectionalStream &&) noexcept=default
 
grpc::ClientContext & GetContext ()
 
std::string_view GetClientName () const
 
std::string_view GetCallName () const
 
tracing::SpanGetSpan ()
 

Protected Member Functions

impl::RpcData & GetData ()
 

Member Function Documentation

◆ GetCallName()

std::string_view ugrpc::client::CallAnyBase::GetCallName ( ) const
inherited
Returns
RPC name

◆ GetClientName()

std::string_view ugrpc::client::CallAnyBase::GetClientName ( ) const
inherited
Returns
client name

◆ GetContext()

grpc::ClientContext & ugrpc::client::CallAnyBase::GetContext ( )
inherited
Returns
the ClientContext used for this RPC

◆ GetSpan()

tracing::Span & ugrpc::client::CallAnyBase::GetSpan ( )
inherited
Returns
RPC span

◆ Read()

template<typename Request , typename Response >
bool ugrpc::client::BidirectionalStream< Request, Response >::Read ( Response & response)

Await and read the next incoming message.

On end-of-input, Finish is called automatically.

Parameters
responsewhere to put response on success
Returns
true on success, false on end-of-input or task cancellation
Exceptions
ugrpc::client::RpcErroron an RPC error

Definition at line 658 of file rpc.hpp.

◆ ReadAsync()

template<typename Request , typename Response >
StreamReadFuture< BidirectionalStream< Request, Response > > ugrpc::client::BidirectionalStream< Request, Response >::ReadAsync ( Response & response)
noexcept

Return future to read next incoming result.

Parameters
responsewhere to put response on success
Returns
StreamReadFuture future
Exceptions
ugrpc::client::RpcErroron an RPC error

Definition at line 645 of file rpc.hpp.

◆ Write()

template<typename Request , typename Response >
bool ugrpc::client::BidirectionalStream< Request, Response >::Write ( const Request & request)

Write the next outgoing message.

RPC will be performed immediately. No references to request are saved, so it can be deallocated right after the call.

Parameters
requestthe next message to write
Returns
true if the data is going to the wire; false if the write operation failed (including due to task cancellation), in which case no more writes will be accepted, but Read may still have some data and status code available

Definition at line 664 of file rpc.hpp.

◆ WriteAndCheck()

template<typename Request , typename Response >
void ugrpc::client::BidirectionalStream< Request, Response >::WriteAndCheck ( const Request & request)

Write the next outgoing message and check result.

WriteAndCheck doesn't store any references to request, so it can be deallocated right after the call.

WriteAndCheck verifies result of the write and generates exception in case of issues.

Parameters
requestthe next message to write
Exceptions
ugrpc::client::RpcErroron an RPC error
ugrpc::client::RpcCancelledErroron task cancellation

Definition at line 673 of file rpc.hpp.

◆ WritesDone()

template<typename Request , typename Response >
bool ugrpc::client::BidirectionalStream< Request, Response >::WritesDone ( )

Announce end-of-output to the server.

Should be called to notify the server and receive the final response(s).

Returns
true if the data is going to the wire; false if the operation failed, but Read may still have some data and status code available

Definition at line 683 of file rpc.hpp.


The documentation for this class was generated from the following file: