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

source code of include/grpcpp/impl/codegen/completion_queue_impl.h