GRPC C++  1.24.0
Data Structures | Public Types | Public Member Functions | Protected Member Functions | Friends
grpc_impl::CompletionQueue Class Reference

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_queuecq ()
 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

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::internal::RpcMethodHandler
 
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_impl::Server
 
class ::grpc_impl::ServerContext
 
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

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

Friends And Related Function Documentation

◆ ::grpc::internal::BlockingUnaryCallImpl

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

◆ ::grpc::internal::CallOpSet

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

◆ ::grpc::internal::ClientStreamingHandler

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

◆ ::grpc::internal::ErrorMethodHandler

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

◆ ::grpc::internal::RpcMethodHandler

template<class ServiceType , class RequestType , class ResponseType >
friend class ::grpc::internal::RpcMethodHandler
friend

◆ ::grpc::internal::ServerStreamingHandler

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

◆ ::grpc::internal::TemplatedBidiStreamingHandler

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

◆ ::grpc::ServerInterface

friend class ::grpc::ServerInterface
friend

◆ ::grpc_impl::Channel

friend class ::grpc_impl::Channel
friend

◆ ::grpc_impl::ClientReader

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

◆ ::grpc_impl::ClientReaderWriter

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

◆ ::grpc_impl::ClientWriter

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

◆ ::grpc_impl::internal::ServerReaderWriterBody

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

◆ ::grpc_impl::Server

friend class ::grpc_impl::Server
friend

◆ ::grpc_impl::ServerContext

friend class ::grpc_impl::ServerContext
friend

◆ ::grpc_impl::ServerReader

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

◆ ::grpc_impl::ServerWriter

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

The documentation for this class was generated from the following file: