asio-grpc v1.6.0
Asynchronous gRPC with Asio/unified executors
agrpc::CancelSafe< CompletionArgs > Class Template Reference

(experimental) Cancellation safety for asynchronous operations More...

#include <agrpc/cancelSafe.hpp>

Public Member Functions

auto token () noexcept
 Create a completion token to initiate asynchronous operations. More...
 
template<class CompletionToken >
auto wait (CompletionToken token)
 Wait for the asynchronous operation to complete. More...
 

Detailed Description

template<class... CompletionArgs>
class agrpc::CancelSafe< CompletionArgs >

(experimental) Cancellation safety for asynchronous operations

This class provides a completion token that can be used to initiate asynchronous operations in a cancellation safe manner. A second method of this class is then used to wait for the operation to complete. Cancelling said waiting will not cancel the underlying operation but still invoke the completion handler with asio::error::operation_aborted. This can be useful in combination with asio::parallel_group or asio::awaitable_operators, e.g. to perform an action every 100ms while waiting for a server-stream:

grpc::ClientContext client_context;
example::v1::Request request;
std::unique_ptr<grpc::ClientAsyncReader<example::v1::Response>> reader;
co_await agrpc::request(&example::v1::Example::Stub::AsyncServerStreaming, stub, client_context, request, reader);
agrpc::GrpcCancelSafe safe; // equivalent to agrpc::CancelSafe<bool>
// Initiate a read with cancellation safety.
example::v1::Response response;
agrpc::read(*reader, response, asio::bind_executor(grpc_context, safe.token()));
grpc::Alarm alarm;
bool ok{true};
while (ok)
{
using namespace asio::experimental::awaitable_operators;
auto variant = co_await (agrpc::wait(alarm, hundred_milliseconds_from_now()) || safe.wait(asio::use_awaitable));
if (0 == variant.index()) // Alarm finished
{
// The read continues in the background.
}
else // Read finished
{
ok = std::get<1>(variant);
if (ok)
{
// Initiate the next read.
agrpc::read(*reader, response, asio::bind_executor(grpc_context, safe.token()));
}
}
}
(experimental) Cancellation safety for asynchronous operations
Definition: cancelSafe.hpp:51
auto token() noexcept
Create a completion token to initiate asynchronous operations.
Definition: cancelSafe.hpp:86
auto wait(CompletionToken token)
Wait for the asynchronous operation to complete.
Definition: cancelSafe.hpp:102
constexpr detail::WaitFn wait
Wait for a timer.
Definition: wait.hpp:78
constexpr detail::RequestFn request
Start a new RPC.
Definition: rpc.hpp:1493
constexpr detail::ReadFn read
Read from a streaming RPC.
Definition: rpc.hpp:1502
Template Parameters
CompletionArgsThe arguments of the completion signature. E.g. for asio::steady_timer::async_wait the completion arguments would be boost::system::error_code.
Since
1.6.0 (and Boost.Asio 1.77.0)

Member Function Documentation

◆ token()

template<class... CompletionArgs>
auto agrpc::CancelSafe< CompletionArgs >::token ( )
inlinenoexcept

Create a completion token to initiate asynchronous operations.

The CancelSafe may not be moved while the operation is outstanding.

◆ wait()

template<class... CompletionArgs>
template<class CompletionToken >
auto agrpc::CancelSafe< CompletionArgs >::wait ( CompletionToken  token)
inline

Wait for the asynchronous operation to complete.

Only one call to wait() may be outstanding at a time. Waiting for an already completed operation will immediately invoke the completion handler in a manner equivalent to using asio::post.

Per-Operation Cancellation

All. Upon cancellation, the asynchronous operation continues to run.

Parameters
tokenCompletion token that matches the completion args. Either void(error_code, CompletionArgs...) if the first argument in CompletionArgs is not error_code or void(CompletionArgs...) otherwise.