An Executor, Networking TS and std::execution interface to grpc::CompletionQueue for writing asynchronous gRPC clients and servers using C++20 coroutines, Boost.Coroutines, Asio's stackless coroutines, callbacks, sender/receiver and more.

• Asio ExecutionContext compatible wrapper around grpc::CompletionQueue
• Executor and Networking TS requirements fulfilling associated executor
• Support for all RPC types: unary, client-streaming, server-streaming and bidirectional-streaming with any mix of Asio CompletionToken as well as TypedSender, including allocator customization
• Support for asynchronously waiting for grpc::Alarms including cancellation through cancellation_slots and StopTokens
• Support for std::execution through libunifex
• Support for generic gRPC clients and servers (aka. proxies)
• No extra codegen required, works with the vanilla gRPC C++ plugin (grpc_cpp_plugin)
• Experimental support for Rust/Golang select-style programming with the help of cancellation safety
• No-Boost version with standalone Asio
• No-Asio version with libunifex
• CMake function to generate gRPC source files: asio_grpc_protobuf_generate

• Client-side 'hello world':

helloworld::Greeter::Stub stub{grpc::CreateChannel(host, grpc::InsecureChannelCredentials())};
agrpc::GrpcContext grpc_context;

asio::co_spawn(
    grpc_context,
    [&]() -> asio::awaitable<void>
    {
        using RPC = agrpc::RPC<&helloworld::Greeter::Stub::PrepareAsyncSayHello>;
        grpc::ClientContext client_context;
        helloworld::HelloRequest request;
        request.set_name("world");
        helloworld::HelloReply response;
        status = co_await RPC::request(grpc_context, stub, client_context, request, response, asio::use_awaitable);
        std::cout << status.ok() << " response: " << response.message() << std::endl;
    },
    asio::detached);

grpc_context.run();

^{snippet source | anchor}

More examples for things like streaming RPCs, double-buffered file transfer with io_uring, libunifex-based coroutines, sharing a thread with an io_context and generic clients/servers can be found in the example directory. Even more examples can be found in another repository.

Asio-grpc is a C++17, header-only library. To install it, CMake (3.14+) is all that is needed.

To use it, gRPC and either Boost.Asio (min. 1.74.0), standalone Asio (min. 1.17.0) or libunifex must be present and linked into your application.

Supported compilers are GCC 8+, Clang 10+, AppleClang 14+ and latest MSVC.

The library can be added to a CMake project using either add_subdirectory or find_package. Once set up, include the individual headers from the agrpc/ directory or the convenience header:

#include <agrpc/asio_grpc.hpp>

add_subdirectory(/path/to/asio-grpc)
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc)

# Also link with the equivalents of gRPC::grpc++_unsecure, Boost::headers and
# Boost::container (if ASIO_GRPC_USE_BOOST_CONTAINER has been set)

add_subdirectory(/path/to/asio-grpc)
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc-standalone-asio)

# Also link with the equivalents of gRPC::grpc++_unsecure, asio::asio and
# Boost::container (if ASIO_GRPC_USE_BOOST_CONTAINER has been set)

add_subdirectory(/path/to/asio-grpc)
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc-unifex)

# Also link with the equivalents of gRPC::grpc++_unsecure, unifex::unifex and
# Boost::container (if ASIO_GRPC_USE_BOOST_CONTAINER has been set)

set(ASIO_GRPC_USE_BOOST_CONTAINER on)
add_subdirectory(/path/to/asio-grpc)

cmake -B build -DCMAKE_INSTALL_PREFIX=/desired/installation/directory .
cmake --build build --target install

# Make sure CMAKE_PREFIX_PATH contains /desired/installation/directory
find_package(asio-grpc)
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc)

# Make sure CMAKE_PREFIX_PATH contains /desired/installation/directory
find_package(asio-grpc)
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc-standalone-asio)

# Make sure CMAKE_PREFIX_PATH contains /desired/installation/directory
find_package(asio-grpc)
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc-unifex)

{
    "name": "your_app",
    "version": "0.1.0",
    "dependencies": [
        "asio-grpc",
        // To use the Boost.Asio backend add
        // "boost-asio",
        // To use the standalone Asio backend add
        // "asio",
        // To use the libunifex backend add
        // "libunifex"
    ]
}

find_package(asio-grpc)
# Using the Boost.Asio backend
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc)
# Or use the standalone Asio backend
#target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc-standalone-asio)
# Or use the libunifex backend
#target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc-unifex)

find_package(asio-grpc)
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc)

ASIO_GRPC_USE_BOOST_CONTAINER (deprecated) - Use Boost.Container instead of <memory_resource>. Mutually exclusive with ASIO_GRPC_USE_RECYCLING_ALLOCATOR.

ASIO_GRPC_USE_RECYCLING_ALLOCATOR (deprecated) - Use asio::recycling_allocator instead of <memory_resource>. Mutually exclusive with ASIO_GRPC_USE_BOOST_CONTAINER.

ASIO_GRPC_DISABLE_AUTOLINK - Set before using find_package(asio-grpc) to prevent asio-grpcConfig.cmake from finding and setting up interface link libraries like gRPC::grpc++.

asio-grpc is part of grpc_bench. Head over there to compare its performance against other libraries and languages.

Below are the results from the helloworld unary RPC for:
Intel(R) Core(TM) i7-8750H CPU @ 2.20GHz
Linux, GCC 12.2.0, Boost 1.80.0, gRPC 1.50.0, asio-grpc v2.4.0, jemalloc 5.2.1
Request scenario: string_100B

Documentation

The main workhorses of this library are the agrpc::GrpcContext and its executor_type - agrpc::GrpcExecutor.

The agrpc::GrpcContext implements asio::execution_context and can be used as an argument to Asio functions that expect an ExecutionContext like asio::spawn.

Likewise, the agrpc::GrpcExecutor satisfies the Executor and Networking TS and Scheduler requirements and can therefore be used in places where Asio/libunifex expects an Executor or Scheduler.

The API for RPCs is modeled closely after the asynchronous, tag-based API of gRPC. As an example, the equivalent for grpc::ClientAsyncReader<helloworld::HelloReply>.Read(helloworld::HelloReply*, void*) would be agrpc::read(grpc::ClientAsyncReader<helloworld::HelloReply>&, helloworld::HelloReply&, CompletionToken).

Instead of the void* tag in the gRPC API the functions in this library expect a CompletionToken. Asio comes with several CompletionTokens already: C++20 coroutine, stackless coroutine, callback and Boost.Coroutine. There is also a special token called agrpc::use_sender that causes RPC functions to return a TypedSender.

If you are interested in learning more about the implementation details of this library then check out this blog article.

grpc::ServerBuilder builder;
agrpc::GrpcContext grpc_context{builder.AddCompletionQueue()};

agrpc::GrpcContext grpc_context;

example::v1::Example::Stub stub(grpc::CreateChannel("localhost:50051", grpc::InsecureChannelCredentials()));
asio::co_spawn(
    grpc_context,
    [&]() -> asio::awaitable<void>
    {
        grpc::ClientContext client_context;
        example::v1::Request request;
        request.set_integer(42);
        example::v1::Response response;
        using RPC = agrpc::RPC<&example::v1::Example::Stub::PrepareAsyncUnary>;
        grpc::Status status = co_await RPC::request(grpc_context, stub, client_context, request, response);
        assert(status.ok());
    },
    asio::detached);
grpc_context.run();