Google Cloud C++ Client  2.2.1
C++ Client Library for Google Cloud Platform
async_streaming_read_write_rpc.h
Go to the documentation of this file.
1 // Copyright 2020 Google LLC
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_ASYNC_STREAMING_READ_WRITE_RPC_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_ASYNC_STREAMING_READ_WRITE_RPC_H
17 
18 #include "google/cloud/future.h"
19 #include "google/cloud/status.h"
20 #include "google/cloud/version.h"
21 #include "absl/types/optional.h"
22 #include <grpcpp/support/async_stream.h>
23 
24 namespace google {
25 namespace cloud {
27 
28 /**
29  * A streaming read-write RPC
30  *
31  * Streaming read-write RPCs (sometimes called bidirectional streaming RPCs)
32  * allow applications to send multiple "requests" and receive multiple
33  * "responses" on the same request. They are often used in services where
34  * sending one request at a time introduces too much latency. The requests
35  */
36 template <typename Request, typename Response>
38  public:
39  virtual ~AsyncStreamingReadWriteRpc() = default;
40 
41  /**
42  * Sends a best-effort request to cancel the RPC.
43  *
44  * The application should still wait for the current operation(s) (any pending
45  * `Start()`, `Read()`, or `Write*()` requests) to complete and use `Finish()`
46  * to determine the status of the RPC.
47  */
48  virtual void Cancel() = 0;
49 
50  /**
51  * Start the streaming RPC.
52  *
53  * Applications should call `Start()` and wait for its result before calling
54  * `Read()` and/or `Write()`. If `Start()` completes with `false` the stream
55  * has completed with an error. The application should not call `Read()` or
56  * `Write()` in this case. On errors, the application should call`Finish()` to
57  * determine the status of the streaming RPC.
58  */
59  virtual future<bool> Start() = 0;
60 
61  /**
62  * Read one response from the streaming RPC.
63  *
64  * @note Only **one** `Read()` operation may be pending at a time. The
65  * application is responsible for waiting until any previous `Read()`
66  * operations have completed before calling `Read()` again.
67  *
68  * Whether `Read()` can be called before a `Write()` operation is specified by
69  * each service and RPC. Most services require at least one `Write()` call
70  * before calling `Read()`. Many services may return more than one response
71  * for a single `Write()` request. Each service and RPC specifies how to
72  * discover if more responses will be forthcoming.
73  *
74  * If the `optional<>` is not engaged the streaming RPC has completed. The
75  * application should wait until any other pending operations (typically any
76  * other `Write()` calls) complete and then call `Finish()` to find the status
77  * of the streaming RPC.
78  */
79  virtual future<absl::optional<Response>> Read() = 0;
80 
81  /**
82  * Write one request to the streaming RPC.
83  *
84  * @note Only **one** `Write()` operation may be pending at a time. The
85  * application is responsible for waiting until any previous `Write()`
86  * operations have completed before calling `Write()` again.
87  *
88  * Whether `Write()` can be called before waiting for a matching `Read()`
89  * operation is specified by each service and RPC. Many services tolerate
90  * multiple `Write()` calls before performing or at least receiving a `Read()`
91  * response.
92  *
93  * If `Write()` completes with `false` the streaming RPC has completed. The
94  * application should wait until any other pending operations (typically any
95  * other `Read()` calls) complete and then call `Finish()` to find the status
96  * of the streaming RPC.
97  */
98  virtual future<bool> Write(Request const&, grpc::WriteOptions) = 0;
99 
100  /**
101  * Half-closes the streaming RPC.
102  *
103  * Sends an indication to the service that no more requests will be issued by
104  * the client.
105  *
106  * If `WritesDone()` completes with `false` the streaming RPC has completed.
107  * The application should wait until any other pending operations (typically
108  * any other `Read()` calls) complete and then call `Finish()` to find the
109  * status of the streaming RPC.
110  */
111  virtual future<bool> WritesDone() = 0;
112 
113  /**
114  * Return the final status of the streaming RPC.
115  *
116  * Streaming RPCs may return an error because the stream is closed,
117  * independently of any whether the application has called `WritesDone()` or
118  * signaled that the stream is closed using other mechanisms (some RPCs define
119  * specific attributes to "close" the stream).
120  *
121  * The application must wait until all pending `Read()` and `Write()`
122  * operations have completed before calling `Finish()`.
123  */
124  virtual future<Status> Finish() = 0;
125 };
126 
128 } // namespace cloud
129 } // namespace google
130 
131 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_ASYNC_STREAMING_READ_WRITE_RPC_H