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

#include <completion_queue_impl.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 ()
	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_impl::ServerBuilder

class	::grpc_impl::Server

template<class R >
class	::grpc_impl::ClientReader

template<class W >
class	::grpc_impl::ClientWriter

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

template<class R >
class	::grpc_impl::ServerReader

template<class W >
class	::grpc_impl::ServerWriter

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

template<class ServiceType , class RequestType , class ResponseType >
class	::grpc_impl::internal::RpcMethodHandler

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

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

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

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

class	::grpc_impl::ServerContextBase

class	::grpc::ServerInterface

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

class	::grpc_impl::Channel

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

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_impl::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_impl::CompletionQueue::CompletionQueue ( )

inline

Default constructor.

Implicitly creates a grpc_completion_queue instance.

◆ CompletionQueue() [2/3]

grpc_impl::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_impl::CompletionQueue::~CompletionQueue ( )

inline

Destructor. Destroys the owned wrapped completion queue / instance.

◆ CompletionQueue() [3/3]

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

inlineprotected

Private constructor of CompletionQueue only visible to friend classes.

Member Function Documentation

◆ AsyncNext()

template<typename T >

NextStatus grpc_impl::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

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

Returns: The type of event read.

◆ cq()

grpc_completion_queue* grpc_impl::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.

◆ DoThenAsyncNext()

template<typename T , typename F >

NextStatus grpc_impl::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

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

Returns: The type of event read.

◆ Next()

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

inline

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

Parameters

tag	[out] Updated to point to the read event's tag.
ok	[out] 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_impl::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.