Class CompletionQueue (2.17.0)

Call the functor associated with asynchronous operations when they complete.

Constructors

CompletionQueue()

CompletionQueue(std::shared_ptr< internal::CompletionQueueImpl >)

Parameter
Name Description
impl std::shared_ptr< internal::CompletionQueueImpl >

Functions

Run()

Run the completion queue event loop.

Note that more than one thread can call this member function, to create a pool of threads completing asynchronous operations.

Returns
Type Description
void

Shutdown()

Terminate the completion queue event loop.

Returns
Type Description
void

CancelAll()

Cancel all pending operations.

Returns
Type Description
void

MakeDeadlineTimer(std::chrono::system_clock::time_point)

Create a timer that fires at deadline.

Parameter
Name Description
deadline std::chrono::system_clock::time_point

when should the timer expire.

Returns
Type Description
google::cloud::future< StatusOr< std::chrono::system_clock::time_point > >

a future that becomes satisfied after deadline. The result of the future is the time at which it expired, or an error Status if the timer did not run to expiration (e.g. it was cancelled).

MakeRelativeTimer(std::chrono::duration< Rep, Period >)

Create a timer that fires after the duration.

Parameters
Name Description
duration std::chrono::duration< Rep, Period >

when should the timer expire relative to the current time.

typename Rep

a placeholder to match the Rep tparam for duration type, the semantics of this template parameter are documented in std::chrono::duration<> (in brief, the underlying arithmetic type used to store the number of ticks), for our purposes it is simply a formal parameter.

typename Period

a placeholder to match the Period tparam for duration type, the semantics of this template parameter are documented in std::chrono::duration<> (in brief, the length of the tick in seconds, expressed as a std::ratio<>), for our purposes it is simply a formal parameter.

Returns
Type Description
future< StatusOr< std::chrono::system_clock::time_point > >

a future that becomes satisfied after duration time has elapsed. The result of the future is the time at which it expired, or an error Status if the timer did not run to expiration (e.g. it was cancelled).

MakeUnaryRpc(AsyncCallType, Request const &, std::unique_ptr< grpc::ClientContext >)

Make an asynchronous unary RPC.

Parameters
Name Description
async_call AsyncCallType

a callable to start the asynchronous RPC.

request Request const &

the contents of the request.

context std::unique_ptr< grpc::ClientContext >

an initialized request context to make the call.

typename AsyncCallType

the type of async_call. It must be invocable with (grpc::ClientContext*, Request const&, grpc::CompletionQueue*). Furthermore, it should return a std::unique_ptr<grpc::ClientAsyncResponseReaderInterface<Response>>>. These requirements are verified by internal::CheckAsyncUnaryRpcSignature<>, and this function is excluded from overload resolution if the parameters do not meet these requirements.

typename Request

the type of the request parameter in the gRPC.

typename Response

the response from the asynchronous RPC.

Returns
Type Description
future< StatusOr< Response > >

a future that becomes satisfied when the operation completes.

MakeStreamingReadRpc(AsyncCallType &&, Request const &, std::unique_ptr< grpc::ClientContext >, OnReadHandler &&, OnFinishHandler &&)

Make an asynchronous streaming read RPC.

Reading from the stream starts automatically, and the handler is notified of all interesting events in the stream. Note that then handler is called by any thread blocked on this object's Run() member function. However, only one callback in the handler is called at a time.

Parameters
Name Description
async_call AsyncCallType &&

a callable to start the asynchronous RPC.

request Request const &

the contents of the request.

context std::unique_ptr< grpc::ClientContext >

an initialized request context to make the call.

on_read OnReadHandler &&

the callback to be invoked on each successful Read().

on_finish OnFinishHandler &&

the callback to be invoked when the stream is closed.

typename AsyncCallType

the type of async_call. It must be invocable with parameters (grpc::ClientContext*, RequestType const&, grpc::CompletionQueue*). Furthermore, it should return a type convertible to std::unique_ptr<grpc::ClientAsyncReaderInterface<Response>>>. These requirements are verified by internal::AsyncStreamingReadRpcUnwrap<>, and this function is excluded from overload resolution if the parameters do not meet these requirements.

typename Request

the type of the request in the streaming RPC.

typename Response

the type of the response in the streaming RPC.

typename OnReadHandler

the type of the on_read callback.

typename OnFinishHandler

the type of the on_finish callback.

Returns
Type Description
std::shared_ptr< AsyncOperation >

RunAsync(Functor &&)

Asynchronously run a functor on a thread Run()ning the CompletionQueue.

Parameters
Name Description
functor Functor &&

the functor to call in one of the CompletionQueue's threads.

typename Functor

the type of functor. It must satisfy std::is_invocable<Functor>.

Returns
Type Description
void

RunAsync(Functor &&)

Asynchronously run a functor on a thread Run()ning the CompletionQueue.

Parameters
Name Description
functor Functor &&

the functor to call in one of the CompletionQueue's threads.

typename Functor

the type of functor. It must satisfy std::is_invocable<Functor>.

Returns
Type Description
void

AsyncWaitConnectionReady(std::shared_ptr< grpc::Channel >, std::chrono::system_clock::time_point)

Asynchronously wait for a connection to become ready.

Parameters
Name Description
channel std::shared_ptr< grpc::Channel >

the channel on which to wait for state changes

deadline std::chrono::system_clock::time_point

give up waiting for the state change if this deadline passes

Returns
Type Description
future< Status >

future<> which will be satisfied when either of these events happen: (a) the connection is ready, (b) the connection permanently failed, (c) deadline passes before (a) or (b) happen; the future will be satisfied with StatusCode::kOk for (a), StatusCode::kCancelled for (b) and StatusCode::kDeadlineExceeded for (c)