Class CompletionQueue (2.21.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.

Deprecated: Applications should have no need to call this function. The libraries provide Async*() member functions in the generated (or) hand-crafted *Client classes for the same purpose.

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.

Deprecated: Applications should have no need to call this function. The libraries provide Async*() member functions in the generated (or) hand-crafted *Client classes for the same purpose.

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)