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

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

Detailed Description

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

Client-side interface for bi-directional streaming.

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 should be completed by reading until ugrpc::client::Reader::Read returns false. If destroyed early, the RPC is cancelled. The server gets ugrpc::client::RpcInterruptedError and the abandoned-error metric is incremented. The connection stays open for reuse. 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 170 of file stream.hpp.

Public Types
using	StreamReadFuture = ugrpc::client::StreamReadFuture< typename impl::BidirectionalStream< Request, Response >::RawStream >

Public Member Functions
	ReaderWriter (ReaderWriter &&) noexcept=default
ReaderWriter &	operator= (ReaderWriter &&) noexcept=default
bool	Read (Response &response)
	Await and read the next incoming message.
StreamReadFuture	ReadAsync (Response &response)
	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.
CallContext &	GetContext ()
	Get call context, useful e.g. for accessing metadata.
const CallContext &	GetContext () const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Member Typedef Documentation

StreamReadFuture

template<typename Request , typename Response >

using ugrpc::client::ReaderWriter< Request, Response >::StreamReadFuture = ugrpc::client::StreamReadFuture<typename impl::BidirectionalStream<Request, Response>::RawStream>

Definition at line 172 of file stream.hpp.

Member Function Documentation

GetContext() [1/2]

template<typename Request , typename Response >

CallContext & ugrpc::client::ReaderWriter< Request, Response >::GetContext ( )

inline

Get call context, useful e.g. for accessing metadata.

Definition at line 246 of file stream.hpp.

GetContext() [2/2]

template<typename Request , typename Response >

const CallContext & ugrpc::client::ReaderWriter< Request, Response >::GetContext ( ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 248 of file stream.hpp.

Read()

template<typename Request , typename Response >

bool ugrpc::client::ReaderWriter< Request, Response >::Read ( Response &  response )

inline

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, task cancellation, or if the stream is already closed for reads

Exceptions

ugrpc::client::RpcError

on an RPC error

Definition at line 199 of file stream.hpp.

ReadAsync()

template<typename Request , typename Response >

StreamReadFuture ugrpc::client::ReaderWriter< Request, Response >::ReadAsync ( Response &  response )

inline

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
ugrpc::client::RpcError	if the stream is already closed for reads

Definition at line 207 of file stream.hpp.

Write()

template<typename Request , typename Response >

bool ugrpc::client::ReaderWriter< Request, Response >::Write ( const Request &  request )

inline

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 220 of file stream.hpp.

WriteAndCheck()

template<typename Request , typename Response >

void ugrpc::client::ReaderWriter< Request, Response >::WriteAndCheck ( const Request &  request )

inline

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
ugrpc::client::RpcError	if the stream is already closed for writes

Definition at line 234 of file stream.hpp.

WritesDone()

template<typename Request , typename Response >

bool ugrpc::client::ReaderWriter< Request, Response >::WritesDone ( )

inline

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 (including if the stream is already closed for writes), but Read may still have some data and status code available

Definition at line 243 of file stream.hpp.

---

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

• userver/ugrpc/client/stream.hpp