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

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_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

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

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
takeThe 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]tagUpon success, updated to point to the event's tag.
[out]okUpon success, true if a successful event, false otherwise See documentation for CompletionQueue::Next for explanation of ok
[in]deadlineHow 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 owership 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]fFunction to execute before calling AsyncNext on this queue.
[out]tagUpon success, updated to point to the event's tag.
[out]okUpon success, true if read a regular event, false otherwise.
[in]deadlineHow 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]tagUpdated to point to the read event's tag.
[out]oktrue 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.

Friends And Related Function Documentation

◆ grpc::Channel

friend class grpc::Channel
friend

◆ grpc::ClientReader

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

◆ grpc::ClientReaderWriter

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

◆ grpc::ClientWriter

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

◆ 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::ServerReaderWriterBody

template<class W , class R >
friend class grpc::internal::ServerReaderWriterBody
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::internal::UnaryRunHandlerHelper

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

◆ grpc::Server

friend class grpc::Server
friend

◆ grpc::ServerBuilder

friend class grpc::ServerBuilder
friend

◆ grpc::ServerContextBase

friend class grpc::ServerContextBase
friend

◆ grpc::ServerInterface

friend class grpc::ServerInterface
friend

◆ grpc::ServerReader

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

◆ grpc::ServerWriter

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

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