1/*
2 *
3 * Copyright 2015 gRPC authors.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 */
18
19/// A completion queue implements a concurrent producer-consumer queue, with
20/// two main API-exposed methods: \a Next and \a AsyncNext. These
21/// methods are the essential component of the gRPC C++ asynchronous API.
22/// There is also a \a Shutdown method to indicate that a given completion queue
23/// will no longer have regular events. This must be called before the
24/// completion queue is destroyed.
25/// All completion queue APIs are thread-safe and may be used concurrently with
26/// any other completion queue API invocation; it is acceptable to have
27/// multiple threads calling \a Next or \a AsyncNext on the same or different
28/// completion queues, or to call these methods concurrently with a \a Shutdown
29/// elsewhere.
30/// \remark{All other API calls on completion queue should be completed before
31/// a completion queue destructor is called.}
32#ifndef GRPCPP_COMPLETION_QUEUE_H
33#define GRPCPP_COMPLETION_QUEUE_H
34
35#include <list>
36
37#include <grpc/support/atm.h>
38#include <grpcpp/impl/codegen/completion_queue_tag.h>
39#include <grpcpp/impl/codegen/core_codegen_interface.h>
40#include <grpcpp/impl/codegen/grpc_library.h>
41#include <grpcpp/impl/codegen/sync.h>
42#include <grpcpp/impl/rpc_service_method.h>
43#include <grpcpp/support/status.h>
44#include <grpcpp/support/time.h>
45
46struct grpc_completion_queue;
47
48namespace grpc {
49template <class R>
50class ClientReader;
51template <class W>
52class ClientWriter;
53template <class W, class R>
54class ClientReaderWriter;
55template <class R>
56class ServerReader;
57template <class W>
58class ServerWriter;
59namespace internal {
60template <class W, class R>
61class ServerReaderWriterBody;
62
63template <class ResponseType>
64void UnaryRunHandlerHelper(
65 const grpc::internal::MethodHandler::HandlerParameter&, ResponseType*,
66 grpc::Status&);
67template <class ServiceType, class RequestType, class ResponseType,
68 class BaseRequestType, class BaseResponseType>
69class RpcMethodHandler;
70template <class ServiceType, class RequestType, class ResponseType>
71class ClientStreamingHandler;
72template <class ServiceType, class RequestType, class ResponseType>
73class ServerStreamingHandler;
74template <class Streamer, bool WriteNeeded>
75class TemplatedBidiStreamingHandler;
76template <grpc::StatusCode code>
77class ErrorMethodHandler;
78} // namespace internal
79
80class Channel;
81class ChannelInterface;
82class Server;
83class ServerBuilder;
84class ServerContextBase;
85class ServerInterface;
86
87namespace internal {
88class CompletionQueueTag;
89class RpcMethod;
90template <class InputMessage, class OutputMessage>
91class BlockingUnaryCallImpl;
92template <class Op1, class Op2, class Op3, class Op4, class Op5, class Op6>
93class CallOpSet;
94} // namespace internal
95
96extern CoreCodegenInterface* g_core_codegen_interface;
97
98/// A thin wrapper around \ref grpc_completion_queue (see \ref
99/// src/core/lib/surface/completion_queue.h).
100/// See \ref doc/cpp/perf_notes.md for notes on best practices for high
101/// performance servers.
102class CompletionQueue : private grpc::GrpcLibraryCodegen {
103 public:
104 /// Default constructor. Implicitly creates a \a grpc_completion_queue
105 /// instance.
106 CompletionQueue()
107 : CompletionQueue(grpc_completion_queue_attributes{
108 GRPC_CQ_CURRENT_VERSION, .cq_completion_type: GRPC_CQ_NEXT, .cq_polling_type: GRPC_CQ_DEFAULT_POLLING,
109 .cq_shutdown_cb: nullptr}) {}
110
111 /// Wrap \a take, taking ownership of the instance.
112 ///
113 /// \param take The completion queue instance to wrap. Ownership is taken.
114 explicit CompletionQueue(grpc_completion_queue* take);
115
116 /// Destructor. Destroys the owned wrapped completion queue / instance.
117 ~CompletionQueue() override {
118 grpc::g_core_codegen_interface->grpc_completion_queue_destroy(cq: cq_);
119 }
120
121 /// Tri-state return for AsyncNext: SHUTDOWN, GOT_EVENT, TIMEOUT.
122 enum NextStatus {
123 SHUTDOWN, ///< The completion queue has been shutdown and fully-drained
124 GOT_EVENT, ///< Got a new event; \a tag will be filled in with its
125 ///< associated value; \a ok indicating its success.
126 TIMEOUT ///< deadline was reached.
127 };
128
129 /// Read from the queue, blocking until an event is available or the queue is
130 /// shutting down.
131 ///
132 /// \param[out] tag Updated to point to the read event's tag.
133 /// \param[out] ok true if read a successful event, false otherwise.
134 ///
135 /// Note that each tag sent to the completion queue (through RPC operations
136 /// or alarms) will be delivered out of the completion queue by a call to
137 /// Next (or a related method), regardless of whether the operation succeeded
138 /// or not. Success here means that this operation completed in the normal
139 /// valid manner.
140 ///
141 /// Server-side RPC request: \a ok indicates that the RPC has indeed
142 /// been started. If it is false, the server has been Shutdown
143 /// before this particular call got matched to an incoming RPC.
144 ///
145 /// Client-side StartCall/RPC invocation: \a ok indicates that the RPC is
146 /// going to go to the wire. If it is false, it not going to the wire. This
147 /// would happen if the channel is either permanently broken or
148 /// transiently broken but with the fail-fast option. (Note that async unary
149 /// RPCs don't post a CQ tag at this point, nor do client-streaming
150 /// or bidi-streaming RPCs that have the initial metadata corked option set.)
151 ///
152 /// Client-side Write, Client-side WritesDone, Server-side Write,
153 /// Server-side Finish, Server-side SendInitialMetadata (which is
154 /// typically included in Write or Finish when not done explicitly):
155 /// \a ok means that the data/metadata/status/etc is going to go to the
156 /// wire. If it is false, it not going to the wire because the call
157 /// is already dead (i.e., canceled, deadline expired, other side
158 /// dropped the channel, etc).
159 ///
160 /// Client-side Read, Server-side Read, Client-side
161 /// RecvInitialMetadata (which is typically included in Read if not
162 /// done explicitly): \a ok indicates whether there is a valid message
163 /// that got read. If not, you know that there are certainly no more
164 /// messages that can ever be read from this stream. For the client-side
165 /// operations, this only happens because the call is dead. For the
166 /// server-sider operation, though, this could happen because the client
167 /// has done a WritesDone already.
168 ///
169 /// Client-side Finish: \a ok should always be true
170 ///
171 /// Server-side AsyncNotifyWhenDone: \a ok should always be true
172 ///
173 /// Alarm: \a ok is true if it expired, false if it was canceled
174 ///
175 /// \return true if got an event, false if the queue is fully drained and
176 /// shut down.
177 bool Next(void** tag, bool* ok) {
178 // Check return type == GOT_EVENT... cases:
179 // SHUTDOWN - queue has been shutdown, return false.
180 // TIMEOUT - we passed infinity time => queue has been shutdown, return
181 // false.
182 // GOT_EVENT - we actually got an event, return true.
183 return (AsyncNextInternal(tag, ok,
184 deadline: grpc::g_core_codegen_interface->gpr_inf_future(
185 type: GPR_CLOCK_REALTIME)) == GOT_EVENT);
186 }
187
188 /// Read from the queue, blocking up to \a deadline (or the queue's shutdown).
189 /// Both \a tag and \a ok are updated upon success (if an event is available
190 /// within the \a deadline). A \a tag points to an arbitrary location usually
191 /// employed to uniquely identify an event.
192 ///
193 /// \param[out] tag Upon success, updated to point to the event's tag.
194 /// \param[out] ok Upon success, true if a successful event, false otherwise
195 /// See documentation for CompletionQueue::Next for explanation of ok
196 /// \param[in] deadline How long to block in wait for an event.
197 ///
198 /// \return The type of event read.
199 template <typename T>
200 NextStatus AsyncNext(void** tag, bool* ok, const T& deadline) {
201 grpc::TimePoint<T> deadline_tp(deadline);
202 return AsyncNextInternal(tag, ok, deadline: deadline_tp.raw_time());
203 }
204
205 /// EXPERIMENTAL
206 /// First executes \a F, then reads from the queue, blocking up to
207 /// \a deadline (or the queue's shutdown).
208 /// Both \a tag and \a ok are updated upon success (if an event is available
209 /// within the \a deadline). A \a tag points to an arbitrary location usually
210 /// employed to uniquely identify an event.
211 ///
212 /// \param[in] f Function to execute before calling AsyncNext on this queue.
213 /// \param[out] tag Upon success, updated to point to the event's tag.
214 /// \param[out] ok Upon success, true if read a regular event, false
215 /// otherwise.
216 /// \param[in] deadline How long to block in wait for an event.
217 ///
218 /// \return The type of event read.
219 template <typename T, typename F>
220 NextStatus DoThenAsyncNext(F&& f, void** tag, bool* ok, const T& deadline) {
221 CompletionQueueTLSCache cache = CompletionQueueTLSCache(this);
222 f();
223 if (cache.Flush(tag, ok)) {
224 return GOT_EVENT;
225 } else {
226 return AsyncNext(tag, ok, deadline);
227 }
228 }
229
230 /// Request the shutdown of the queue.
231 ///
232 /// \warning This method must be called at some point if this completion queue
233 /// is accessed with Next or AsyncNext. \a Next will not return false
234 /// until this method has been called and all pending tags have been drained.
235 /// (Likewise for \a AsyncNext returning \a NextStatus::SHUTDOWN .)
236 /// Only once either one of these methods does that (that is, once the queue
237 /// has been \em drained) can an instance of this class be destroyed.
238 /// Also note that applications must ensure that no work is enqueued on this
239 /// completion queue after this method is called.
240 void Shutdown();
241
242 /// Returns a \em raw pointer to the underlying \a grpc_completion_queue
243 /// instance.
244 ///
245 /// \warning Remember that the returned instance is owned. No transfer of
246 /// owership is performed.
247 grpc_completion_queue* cq() { return cq_; }
248
249 protected:
250 /// Private constructor of CompletionQueue only visible to friend classes
251 explicit CompletionQueue(const grpc_completion_queue_attributes& attributes) {
252 cq_ = grpc::g_core_codegen_interface->grpc_completion_queue_create(
253 factory: grpc::g_core_codegen_interface->grpc_completion_queue_factory_lookup(
254 attributes: &attributes),
255 attributes: &attributes, reserved: nullptr);
256 InitialAvalanching(); // reserve this for the future shutdown
257 }
258
259 private:
260 // Friends for access to server registration lists that enable checking and
261 // logging on shutdown
262 friend class grpc::ServerBuilder;
263 friend class grpc::Server;
264
265 // Friend synchronous wrappers so that they can access Pluck(), which is
266 // a semi-private API geared towards the synchronous implementation.
267 template <class R>
268 friend class grpc::ClientReader;
269 template <class W>
270 friend class grpc::ClientWriter;
271 template <class W, class R>
272 friend class grpc::ClientReaderWriter;
273 template <class R>
274 friend class grpc::ServerReader;
275 template <class W>
276 friend class grpc::ServerWriter;
277 template <class W, class R>
278 friend class grpc::internal::ServerReaderWriterBody;
279 template <class ResponseType>
280 friend void grpc::internal::UnaryRunHandlerHelper(
281 const grpc::internal::MethodHandler::HandlerParameter&, ResponseType*,
282 grpc::Status&);
283 template <class ServiceType, class RequestType, class ResponseType>
284 friend class grpc::internal::ClientStreamingHandler;
285 template <class ServiceType, class RequestType, class ResponseType>
286 friend class grpc::internal::ServerStreamingHandler;
287 template <class Streamer, bool WriteNeeded>
288 friend class grpc::internal::TemplatedBidiStreamingHandler;
289 template <grpc::StatusCode code>
290 friend class grpc::internal::ErrorMethodHandler;
291 friend class grpc::ServerContextBase;
292 friend class grpc::ServerInterface;
293 template <class InputMessage, class OutputMessage>
294 friend class grpc::internal::BlockingUnaryCallImpl;
295
296 // Friends that need access to constructor for callback CQ
297 friend class grpc::Channel;
298
299 // For access to Register/CompleteAvalanching
300 template <class Op1, class Op2, class Op3, class Op4, class Op5, class Op6>
301 friend class grpc::internal::CallOpSet;
302
303 /// EXPERIMENTAL
304 /// Creates a Thread Local cache to store the first event
305 /// On this completion queue queued from this thread. Once
306 /// initialized, it must be flushed on the same thread.
307 class CompletionQueueTLSCache {
308 public:
309 explicit CompletionQueueTLSCache(CompletionQueue* cq);
310 ~CompletionQueueTLSCache();
311 bool Flush(void** tag, bool* ok);
312
313 private:
314 CompletionQueue* cq_;
315 bool flushed_;
316 };
317
318 NextStatus AsyncNextInternal(void** tag, bool* ok, gpr_timespec deadline);
319
320 /// Wraps \a grpc_completion_queue_pluck.
321 /// \warning Must not be mixed with calls to \a Next.
322 bool Pluck(grpc::internal::CompletionQueueTag* tag) {
323 auto deadline =
324 grpc::g_core_codegen_interface->gpr_inf_future(type: GPR_CLOCK_REALTIME);
325 while (true) {
326 auto ev = grpc::g_core_codegen_interface->grpc_completion_queue_pluck(
327 cq: cq_, tag, deadline, reserved: nullptr);
328 bool ok = ev.success != 0;
329 void* ignored = tag;
330 if (tag->FinalizeResult(tag: &ignored, status: &ok)) {
331 GPR_CODEGEN_ASSERT(ignored == tag);
332 return ok;
333 }
334 }
335 }
336
337 /// Performs a single polling pluck on \a tag.
338 /// \warning Must not be mixed with calls to \a Next.
339 ///
340 /// TODO: sreek - This calls tag->FinalizeResult() even if the cq_ is already
341 /// shutdown. This is most likely a bug and if it is a bug, then change this
342 /// implementation to simple call the other TryPluck function with a zero
343 /// timeout. i.e:
344 /// TryPluck(tag, gpr_time_0(GPR_CLOCK_REALTIME))
345 void TryPluck(grpc::internal::CompletionQueueTag* tag) {
346 auto deadline =
347 grpc::g_core_codegen_interface->gpr_time_0(type: GPR_CLOCK_REALTIME);
348 auto ev = grpc::g_core_codegen_interface->grpc_completion_queue_pluck(
349 cq: cq_, tag, deadline, reserved: nullptr);
350 if (ev.type == GRPC_QUEUE_TIMEOUT) return;
351 bool ok = ev.success != 0;
352 void* ignored = tag;
353 // the tag must be swallowed if using TryPluck
354 GPR_CODEGEN_ASSERT(!tag->FinalizeResult(&ignored, &ok));
355 }
356
357 /// Performs a single polling pluck on \a tag. Calls tag->FinalizeResult if
358 /// the pluck() was successful and returned the tag.
359 ///
360 /// This exects tag->FinalizeResult (if called) to return 'false' i.e expects
361 /// that the tag is internal not something that is returned to the user.
362 void TryPluck(grpc::internal::CompletionQueueTag* tag,
363 gpr_timespec deadline) {
364 auto ev = grpc::g_core_codegen_interface->grpc_completion_queue_pluck(
365 cq: cq_, tag, deadline, reserved: nullptr);
366 if (ev.type == GRPC_QUEUE_TIMEOUT || ev.type == GRPC_QUEUE_SHUTDOWN) {
367 return;
368 }
369
370 bool ok = ev.success != 0;
371 void* ignored = tag;
372 GPR_CODEGEN_ASSERT(!tag->FinalizeResult(&ignored, &ok));
373 }
374
375 /// Manage state of avalanching operations : completion queue tags that
376 /// trigger other completion queue operations. The underlying core completion
377 /// queue should not really shutdown until all avalanching operations have
378 /// been finalized. Note that we maintain the requirement that an avalanche
379 /// registration must take place before CQ shutdown (which must be maintained
380 /// elsehwere)
381 void InitialAvalanching() {
382 gpr_atm_rel_store(&avalanches_in_flight_, static_cast<gpr_atm>(1));
383 }
384 void RegisterAvalanching() {
385 gpr_atm_no_barrier_fetch_add(&avalanches_in_flight_,
386 static_cast<gpr_atm>(1));
387 }
388 void CompleteAvalanching() {
389 if (gpr_atm_no_barrier_fetch_add(&avalanches_in_flight_,
390 static_cast<gpr_atm>(-1)) == 1) {
391 grpc::g_core_codegen_interface->grpc_completion_queue_shutdown(cq: cq_);
392 }
393 }
394
395 void RegisterServer(const grpc::Server* server) {
396 (void)server;
397#ifndef NDEBUG
398 grpc::internal::MutexLock l(&server_list_mutex_);
399 server_list_.push_back(server);
400#endif
401 }
402 void UnregisterServer(const grpc::Server* server) {
403 (void)server;
404#ifndef NDEBUG
405 grpc::internal::MutexLock l(&server_list_mutex_);
406 server_list_.remove(server);
407#endif
408 }
409 bool ServerListEmpty() const {
410#ifndef NDEBUG
411 grpc::internal::MutexLock l(&server_list_mutex_);
412 return server_list_.empty();
413#endif
414 return true;
415 }
416
417 static CompletionQueue* CallbackAlternativeCQ();
418 static void ReleaseCallbackAlternativeCQ(CompletionQueue* cq);
419
420 grpc_completion_queue* cq_; // owned
421
422 gpr_atm avalanches_in_flight_;
423
424 // List of servers associated with this CQ. Even though this is only used with
425 // NDEBUG, instantiate it in all cases since otherwise the size will be
426 // inconsistent.
427 mutable grpc::internal::Mutex server_list_mutex_;
428 std::list<const grpc::Server*>
429 server_list_ /* GUARDED_BY(server_list_mutex_) */;
430};
431
432/// A specific type of completion queue used by the processing of notifications
433/// by servers. Instantiated by \a ServerBuilder or Server (for health checker).
434class ServerCompletionQueue : public CompletionQueue {
435 public:
436 bool IsFrequentlyPolled() { return polling_type_ != GRPC_CQ_NON_LISTENING; }
437
438 protected:
439 /// Default constructor
440 ServerCompletionQueue() : polling_type_(GRPC_CQ_DEFAULT_POLLING) {}
441
442 private:
443 /// \param completion_type indicates whether this is a NEXT or CALLBACK
444 /// completion queue.
445 /// \param polling_type Informs the GRPC library about the type of polling
446 /// allowed on this completion queue. See grpc_cq_polling_type's description
447 /// in grpc_types.h for more details.
448 /// \param shutdown_cb is the shutdown callback used for CALLBACK api queues
449 ServerCompletionQueue(grpc_cq_completion_type completion_type,
450 grpc_cq_polling_type polling_type,
451 grpc_completion_queue_functor* shutdown_cb)
452 : CompletionQueue(grpc_completion_queue_attributes{
453 GRPC_CQ_CURRENT_VERSION, .cq_completion_type: completion_type, .cq_polling_type: polling_type,
454 .cq_shutdown_cb: shutdown_cb}),
455 polling_type_(polling_type) {}
456
457 grpc_cq_polling_type polling_type_;
458 friend class grpc::ServerBuilder;
459 friend class grpc::Server;
460};
461
462} // namespace grpc
463
464#endif // GRPCPP_COMPLETION_QUEUE_H
465

source code of include/grpcpp/completion_queue.h