#include <completion_queue.h>

Inheritance diagram for grpc::CompletionQueue:

Classes
class	CompletionQueueTLSCache

Public Types
enum	NextStatus { SHUTDOWN, GOT_EVENT, TIMEOUT }
	Tri-state return for AsyncNext: SHUTDOWN, GOT_EVENT, TIMEOUT. More...

Public Member Functions
template<typename T >
NextStatus	AsyncNext (void *tag, bool ok, const T &deadline)

	CompletionQueue ()

	CompletionQueue (grpc_completion_queue *take)

grpc_completion_queue *	cq ()

template<typename T , typename F >
NextStatus	DoThenAsyncNext (F &&f, void *tag, bool ok, const T &deadline)

bool	Next (void *tag, bool ok)

void	Shutdown ()

	~CompletionQueue () override
	Destructor. Destroys the owned wrapped completion queue / instance. More...

Protected Member Functions
	CompletionQueue (const grpc_completion_queue_attributes &attributes)
	Private constructor of CompletionQueue only visible to friend classes. More...

Private Member Functions
NextStatus	AsyncNextInternal (void *tag, bool ok, gpr_timespec deadline)

void	CompleteAvalanching ()

void	InitialAvalanching ()

bool	Pluck (grpc::internal::CompletionQueueTag *tag)

void	RegisterAvalanching ()

void	RegisterServer (const grpc::Server *server)

bool	ServerListEmpty () const

void	TryPluck (grpc::internal::CompletionQueueTag *tag)

void	TryPluck (grpc::internal::CompletionQueueTag *tag, gpr_timespec deadline)

void	UnregisterServer (const grpc::Server *server)

Private Member Functions inherited from grpc::GrpcLibraryCodegen
	GrpcLibraryCodegen (bool call_grpc_init=true)

virtual	~GrpcLibraryCodegen ()

Static Private Member Functions
static CompletionQueue *	CallbackAlternativeCQ ()

static void	ReleaseCallbackAlternativeCQ (CompletionQueue *cq)

Private Attributes
gpr_atm	avalanches_in_flight_

grpc_completion_queue *	cq_

std::list< const grpc::Server * >	server_list_

grpc::internal::Mutex	server_list_mutex_

Friends
class	grpc::Channel

template<class R >
class	grpc::ClientReader

template<class W , class R >
class	grpc::ClientReaderWriter

template<class W >
class	grpc::ClientWriter

template<class InputMessage , class OutputMessage >
class	grpc::internal::BlockingUnaryCallImpl

template<class Op1 , class Op2 , class Op3 , class Op4 , class Op5 , class Op6 >
class	grpc::internal::CallOpSet

template<class ServiceType , class RequestType , class ResponseType >
class	grpc::internal::ClientStreamingHandler

template<grpc::StatusCode code>
class	grpc::internal::ErrorMethodHandler

template<class W , class R >
class	grpc::internal::ServerReaderWriterBody

template<class ServiceType , class RequestType , class ResponseType >
class	grpc::internal::ServerStreamingHandler

template<class Streamer , bool WriteNeeded>
class	grpc::internal::TemplatedBidiStreamingHandler

template<class ResponseType >
void	grpc::internal::UnaryRunHandlerHelper (const grpc::internal::MethodHandler::HandlerParameter &, ResponseType *, grpc::Status &)

class	grpc::Server

class	grpc::ServerBuilder

class	grpc::ServerContextBase

class	grpc::ServerInterface

template<class R >
class	grpc::ServerReader

template<class W >
class	grpc::ServerWriter

Detailed Description

A thin wrapper around grpc_completion_queue (see src/core/lib/surface/completion_queue.h). See doc/cpp/perf_notes.md for notes on best practices for high performance servers.

Definition at line 104 of file include/grpcpp/impl/codegen/completion_queue.h.

Member Enumeration Documentation

◆ NextStatus

enum grpc::CompletionQueue::NextStatus

Tri-state return for AsyncNext: SHUTDOWN, GOT_EVENT, TIMEOUT.

Enumerator
SHUTDOWN	The completion queue has been shutdown and fully-drained.
GOT_EVENT	Got a new event; tag will be filled in with its associated value; ok indicating its success.
TIMEOUT	deadline was reached.

Definition at line 124 of file include/grpcpp/impl/codegen/completion_queue.h.

Constructor & Destructor Documentation

◆ CompletionQueue() [1/3]

grpc::CompletionQueue::CompletionQueue ( )

inline

Default constructor. Implicitly creates a grpc_completion_queue instance.

Definition at line 108 of file include/grpcpp/impl/codegen/completion_queue.h.

◆ CompletionQueue() [2/3]

grpc::CompletionQueue::CompletionQueue ( grpc_completion_queue * take )

explicit

Wrap take, taking ownership of the instance.

Parameters

take	The completion queue instance to wrap. Ownership is taken.

Definition at line 132 of file completion_queue_cc.cc.

◆ ~CompletionQueue()

grpc::CompletionQueue::~CompletionQueue ( )

inlineoverride

Destructor. Destroys the owned wrapped completion queue / instance.

Definition at line 119 of file include/grpcpp/impl/codegen/completion_queue.h.

◆ CompletionQueue() [3/3]

grpc::CompletionQueue::CompletionQueue ( const grpc_completion_queue_attributes & attributes )

inlineexplicitprotected

Private constructor of CompletionQueue only visible to friend classes.

Definition at line 253 of file include/grpcpp/impl/codegen/completion_queue.h.

Member Function Documentation

◆ AsyncNext()

template<typename T >

NextStatus grpc::CompletionQueue::AsyncNext	(	void **	tag,
		bool *	ok,
		const T &	deadline
	)

inline

Read from the queue, blocking up to deadline (or the queue's shutdown). Both tag and ok are updated upon success (if an event is available within the deadline). A tag points to an arbitrary location usually employed to uniquely identify an event.

Parameters

[out]	tag	Upon success, updated to point to the event's tag.
[out]	ok	Upon success, true if a successful event, false otherwise See documentation for CompletionQueue::Next for explanation of ok
[in]	deadline	How long to block in wait for an event.

Returns: The type of event read.

Definition at line 202 of file include/grpcpp/impl/codegen/completion_queue.h.

◆ AsyncNextInternal()

CompletionQueue::NextStatus grpc::CompletionQueue::AsyncNextInternal	(	void **	tag,
		bool *	ok,
		gpr_timespec	deadline
	)

private

Definition at line 148 of file completion_queue_cc.cc.

◆ CallbackAlternativeCQ()

CompletionQueue * grpc::CompletionQueue::CallbackAlternativeCQ ( )

staticprivate

Definition at line 196 of file completion_queue_cc.cc.

◆ CompleteAvalanching()

void grpc::CompletionQueue::CompleteAvalanching ( )

inlineprivate

Definition at line 390 of file include/grpcpp/impl/codegen/completion_queue.h.

◆ cq()

grpc_completion_queue* grpc::CompletionQueue::cq ( )

inline

Returns a raw pointer to the underlying grpc_completion_queue instance.

Warning: Remember that the returned instance is owned. No transfer of owership is performed.

Definition at line 249 of file include/grpcpp/impl/codegen/completion_queue.h.

◆ DoThenAsyncNext()

template<typename T , typename F >

NextStatus grpc::CompletionQueue::DoThenAsyncNext	(	F &&	f,
		void **	tag,
		bool *	ok,
		const T &	deadline
	)

inline

EXPERIMENTAL First executes F, then reads from the queue, blocking up to deadline (or the queue's shutdown). Both tag and ok are updated upon success (if an event is available within the deadline). A tag points to an arbitrary location usually employed to uniquely identify an event.

Parameters

[in]	f	Function to execute before calling AsyncNext on this queue.
[out]	tag	Upon success, updated to point to the event's tag.
[out]	ok	Upon success, true if read a regular event, false otherwise.
[in]	deadline	How long to block in wait for an event.

Returns: The type of event read.

Definition at line 222 of file include/grpcpp/impl/codegen/completion_queue.h.

◆ InitialAvalanching()

void grpc::CompletionQueue::InitialAvalanching ( )

inlineprivate

Manage state of avalanching operations : completion queue tags that trigger other completion queue operations. The underlying core completion queue should not really shutdown until all avalanching operations have been finalized. Note that we maintain the requirement that an avalanche registration must take place before CQ shutdown (which must be maintained elsehwere)

Definition at line 383 of file include/grpcpp/impl/codegen/completion_queue.h.

◆ Next()

bool grpc::CompletionQueue::Next	(	void **	tag,
		bool *	ok
	)

inline

Read from the queue, blocking until an event is available or the queue is shutting down.

Parameters

[out]	tag	Updated to point to the read event's tag.
[out]	ok	true if read a successful event, false otherwise.

Note that each tag sent to the completion queue (through RPC operations or alarms) will be delivered out of the completion queue by a call to Next (or a related method), regardless of whether the operation succeeded or not. Success here means that this operation completed in the normal valid manner.

Server-side RPC request: ok indicates that the RPC has indeed been started. If it is false, the server has been Shutdown before this particular call got matched to an incoming RPC.

Client-side StartCall/RPC invocation: ok indicates that the RPC is going to go to the wire. If it is false, it not going to the wire. This would happen if the channel is either permanently broken or transiently broken but with the fail-fast option. (Note that async unary RPCs don't post a CQ tag at this point, nor do client-streaming or bidi-streaming RPCs that have the initial metadata corked option set.)

Client-side Write, Client-side WritesDone, Server-side Write, Server-side Finish, Server-side SendInitialMetadata (which is typically included in Write or Finish when not done explicitly): ok means that the data/metadata/status/etc is going to go to the wire. If it is false, it not going to the wire because the call is already dead (i.e., canceled, deadline expired, other side dropped the channel, etc).

Client-side Read, Server-side Read, Client-side RecvInitialMetadata (which is typically included in Read if not done explicitly): ok indicates whether there is a valid message that got read. If not, you know that there are certainly no more messages that can ever be read from this stream. For the client-side operations, this only happens because the call is dead. For the server-sider operation, though, this could happen because the client has done a WritesDone already.

Client-side Finish: ok should always be true

Server-side AsyncNotifyWhenDone: ok should always be true

Alarm: ok is true if it expired, false if it was canceled

Returns: true if got an event, false if the queue is fully drained and shut down.

Definition at line 179 of file include/grpcpp/impl/codegen/completion_queue.h.

◆ Pluck()

bool grpc::CompletionQueue::Pluck ( grpc::internal::CompletionQueueTag * tag )

inlineprivate

Wraps grpc_completion_queue_pluck.

Warning: Must not be mixed with calls to Next.

Definition at line 324 of file include/grpcpp/impl/codegen/completion_queue.h.

◆ RegisterAvalanching()

void grpc::CompletionQueue::RegisterAvalanching ( )

inlineprivate

Definition at line 386 of file include/grpcpp/impl/codegen/completion_queue.h.

◆ RegisterServer()

void grpc::CompletionQueue::RegisterServer ( const grpc::Server * server )

inlineprivate

Definition at line 397 of file include/grpcpp/impl/codegen/completion_queue.h.

◆ ReleaseCallbackAlternativeCQ()

void grpc::CompletionQueue::ReleaseCallbackAlternativeCQ ( CompletionQueue * cq )

staticprivate

Definition at line 202 of file completion_queue_cc.cc.

◆ ServerListEmpty()

bool grpc::CompletionQueue::ServerListEmpty ( ) const

inlineprivate

Definition at line 411 of file include/grpcpp/impl/codegen/completion_queue.h.

◆ Shutdown()

void grpc::CompletionQueue::Shutdown ( )

Request the shutdown of the queue.

Warning: This method must be called at some point if this completion queue is accessed with Next or AsyncNext. Next will not return false until this method has been called and all pending tags have been drained. (Likewise for AsyncNext returning NextStatus::SHUTDOWN .) Only once either one of these methods does that (that is, once the queue has been drained) can an instance of this class be destroyed. Also note that applications must ensure that no work is enqueued on this completion queue after this method is called.

Definition at line 137 of file completion_queue_cc.cc.

◆ TryPluck() [1/2]

void grpc::CompletionQueue::TryPluck ( grpc::internal::CompletionQueueTag * tag )

inlineprivate

Performs a single polling pluck on tag.

Warning: Must not be mixed with calls to Next.

TODO: sreek - This calls tag->FinalizeResult() even if the cq_ is already shutdown. This is most likely a bug and if it is a bug, then change this implementation to simple call the other TryPluck function with a zero timeout. i.e: TryPluck(tag, gpr_time_0(GPR_CLOCK_REALTIME))

Definition at line 347 of file include/grpcpp/impl/codegen/completion_queue.h.