A streaming read-write RPC.
Streaming read-write RPCs (sometimes called bidirectional streaming RPCs) allow applications to send multiple "requests" and receive multiple "responses" on the same request. They are often used in services where sending one request at a time introduces too much latency. The requests
Functions
Cancel()
Sends a best-effort request to cancel the RPC.
The application should still wait for the current operation(s) (any pending Start(), Read(), or Write*() requests) to complete and use Finish() to determine the status of the RPC.
| Returns | |
|---|---|
| Type | Description |
void | |
Start()
Start the streaming RPC.
Applications should call Start() and wait for its result before calling Read() and/or Write(). If Start() completes with false the stream has completed with an error. The application should not call Read() or Write() in this case. On errors, the application should callFinish() to determine the status of the streaming RPC.
| Returns | |
|---|---|
| Type | Description |
future< bool > | |
Read()
Read one response from the streaming RPC.
Whether Read() can be called before a Write() operation is specified by each service and RPC. Most services require at least one Write() call before calling Read(). Many services may return more than one response for a single Write() request. Each service and RPC specifies how to discover if more responses will be forthcoming.
If the optional<> is not engaged the streaming RPC has completed. The application should wait until any other pending operations (typically any other Write() calls) complete and then call Finish() to find the status of the streaming RPC.
| Returns | |
|---|---|
| Type | Description |
future< absl::optional< Response > > | |
Write(Request const &, grpc::WriteOptions)
Write one request to the streaming RPC.
Whether Write() can be called before waiting for a matching Read() operation is specified by each service and RPC. Many services tolerate multiple Write() calls before performing or at least receiving a Read() response.
If Write() completes with false the streaming RPC has completed. The application should wait until any other pending operations (typically any other Read() calls) complete and then call Finish() to find the status of the streaming RPC.
| Parameters | |
|---|---|
| Name | Description |
|
Request const &
|
|
grpc::WriteOptions
|
| Returns | |
|---|---|
| Type | Description |
future< bool > | |
WritesDone()
Half-closes the streaming RPC.
Sends an indication to the service that no more requests will be issued by the client.
If WritesDone() completes with false the streaming RPC has completed. The application should wait until any other pending operations (typically any other Read() calls) complete and then call Finish() to find the status of the streaming RPC.
| Returns | |
|---|---|
| Type | Description |
future< bool > | |
Finish()
Return the final status of the streaming RPC.
Streaming RPCs may return an error because the stream is closed, independently of any whether the application has called WritesDone() or signaled that the stream is closed using other mechanisms (some RPCs define specific attributes to "close" the stream).
The application must wait until all pending Read() and Write() operations have completed before calling Finish().
| Returns | |
|---|---|
| Type | Description |
future< Status > | |
virtual GetRequestMetadata() const
Return the request metadata.
Request metadata is useful for troubleshooting, but may be relatively expensive to extract. Application developers should avoid this function in the critical path.
| Returns | |
|---|---|
| Type | Description |
RpcMetadata | |