A thin wrapper around grpc_completion_queue (see src/core/lib/surface/completion_queue.h). More...

#include <completion_queue.h>

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

Public Member Functions
	CompletionQueue ()
	Default constructor. More...

	CompletionQueue (grpc_completion_queue *take)
	Wrap take, taking ownership of the instance. More...

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

bool	Next (void *tag, bool ok)
	Read from the queue, blocking until an event is available or the queue is shutting down. More...

template<typename T >
NextStatus	AsyncNext (void *tag, bool ok, const T &deadline)
	Read from the queue, blocking up to deadline (or the queue's shutdown). More...

template<typename T , typename F >
NextStatus	DoThenAsyncNext (F &&f, void *tag, bool ok, const T &deadline)
	EXPERIMENTAL First executes F, then reads from the queue, blocking up to deadline (or the queue's shutdown). More...

void	Shutdown ()
	Request the shutdown of the queue. More...

grpc_completion_queue *	cq ()
	Returns a raw pointer to the underlying grpc_completion_queue instance. More...

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

Friends
class	grpc::ServerBuilder

class	grpc::Server

template<class R >
class	grpc::ClientReader

template<class W >
class	grpc::ClientWriter

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

template<class R >
class	grpc::ServerReader

template<class W >
class	grpc::ServerWriter

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

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

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

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

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

class	grpc::ServerContextBase

class	grpc::ServerInterface

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

class	grpc::Channel

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

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

Detailed Description

A thin wrapper around grpc_completion_queue (see src/core/lib/surface/completion_queue.h).

See C++ Performance Notes for notes on best practices for high performance servers.

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.

Constructor & Destructor Documentation

◆ CompletionQueue() [1/3]

grpc::CompletionQueue::CompletionQueue ( )

inline

Default constructor.

Implicitly creates a grpc_completion_queue instance.

◆ 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.

◆ ~CompletionQueue()

grpc::CompletionQueue::~CompletionQueue ( )

inlineoverride

Destructor. Destroys the owned wrapped completion queue / instance.

◆ CompletionQueue() [3/3]

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

inlineexplicitprotected

Private constructor of CompletionQueue only visible to friend classes.

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.

◆ 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 ownership is performed.

◆ 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.

◆ 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.

◆ 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.