ugrpc::client::BidirectionalStream< Request, Response > Class Template Reference

#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 344 of file rpc.hpp.

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

Collaboration diagram for ugrpc::client::BidirectionalStream< Request, Response >:

Public Member Functions
bool	Read (Response &response)
	Await and read the next incoming message.
StreamReadFuture< BidirectionalStream >	ReadAsync (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
BidirectionalStream &	operator= (BidirectionalStream &&) noexcept=default
Public Member Functions inherited from ugrpc::client::CallAnyBase
grpc::ClientContext &	GetContext ()
std::string_view	GetClientName () const
std::string_view	GetCallName () const
tracing::Span &	GetSpan ()

Additional Inherited Members
Protected Member Functions inherited from ugrpc::client::CallAnyBase
impl::RpcData &	GetData ()

Member Function Documentation

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

response

where to put response on success

Returns

true on success, false on end-of-input or task cancellation

Exceptions

ugrpc::client::RpcError

on an RPC error

Definition at line 621 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

response

where to put response on success

Returns

StreamReadFuture future

Exceptions

ugrpc::client::RpcError

on an RPC error

Definition at line 614 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

request

the 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 627 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

request

the next message to write

Exceptions

ugrpc::client::RpcError	on an RPC error
ugrpc::client::RpcCancelledError	on task cancellation

Definition at line 635 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 644 of file rpc.hpp.

---

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

• userver/ugrpc/client/rpc.hpp