asio-grpc

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.

Features

• Asio ExecutionContext compatible wrapper around grpc::CompletionQueue
• Support for all RPC types: unary, client-streaming, server-streaming and bidirectional-streaming with any mix of Asio CompletionToken as well as Sender, including allocator customization
• Support for asynchronously waiting for grpc::Alarms including cancellation through cancellation_slots and StopTokens
• Support for sender/receiver through either libunifex or stdexec
• Support for generic gRPC clients and servers
• No extra codegen required, works with the vanilla gRPC C++ plugin (grpc_cpp_plugin)
• No-Boost version with standalone Asio
• No-Asio version with libunifex or stdexec
• CMake function to easily generate gRPC source files: asio_grpc_protobuf_generate

Example

Hello world client using C++20 coroutines. Other Asio completion tokens are supported as well.

helloworld::Greeter::Stub stub(grpc::CreateChannel("localhost:50051", grpc::InsecureChannelCredentials()));
agrpc::GrpcContext grpc_context;
asio::co_spawn(
    grpc_context,
    [&]() -> asio::awaitable<void>
    {
        using RPC = agrpc::ClientRPC<&helloworld::Greeter::Stub::PrepareAsyncSayHello>;
        grpc::ClientContext client_context;
        helloworld::HelloRequest request;
        request.set_name("world");
        helloworld::HelloReply response;
        const grpc::Status status =
            co_await RPC::request(grpc_context, stub, client_context, request, response, asio::use_awaitable);
        assert(status.ok());
    },
    asio::detached);
grpc_context.run();

^{snippet source | anchor}

Requirements

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), libunifex or stdexec must be present and linked into your application.

Officially supported compilers are GCC 10+, Clang 13+, AppleClang 15+ and latest MSVC.

Usage

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.

vcpkg

Add asio-grpc to the dependencies inside your vcpkg.json:

{
    "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",
        // To use the stdexec backend add
        // "stdexec"
    ]
}

Find asio-grpc and link it to your target.

Using Boost.Asio:

find_package(asio-grpc CONFIG REQUIRED)
find_package(Boost REQUIRED)
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc Boost::headers)

Or using standalone Asio:

find_package(asio-grpc CONFIG REQUIRED)
find_package(asio CONFIG REQUIRED)
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc-standalone-asio asio::asio)

Or using libunifex:

find_package(asio-grpc CONFIG REQUIRED)
find_package(unifex CONFIG REQUIRED)
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc-unifex unifex::unifex)

Or using stdexec:

find_package(asio-grpc CONFIG REQUIRED)
find_package(stdexec CONFIG REQUIRED)
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc-stdexec STDEXEC::stdexec)

Hunter

See asio-grpc's documentation on the Hunter website: https://hunter.readthedocs.io/en/latest/packages/pkg/asio-grpc.html.

conan

The recipe in conan-center is called asio-grpc.
If you are using conan's CMake generator then link with asio-grpc::asio-grpc independent of the backend that you choose:

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

CPM

To use asio-grpc via CPM.cmake, add it directly from GitHub:

CPMAddPackage(
        NAME asio-grpc
        GITHUB_REPOSITORY Tradias/asio-grpc
        VERSION 3.7.0
)

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

This links the Boost.Asio backend. If you're using a different backend (like standalone Asio, libunifex, or stdexec), you need to link against the corresponding target, e.g., asio-grpc::asio-grpc-standalone-asio.

CMake package

Clone the repository and install it.

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

Locate it and link it to your target.

Using Boost.Asio:

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

Or using standalone Asio:

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

Or using libunifex:

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

Or using stdexec:

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

CMake subdirectory

Clone the repository into a subdirectory of your CMake project. Then add it and link it to your target.

Independent of the backend you chose, find and link with gRPC:

find_package(gRPC)
target_link_libraries(your_app PUBLIC gRPC::grpc++)

Using Boost.Asio:

add_subdirectory(/path/to/asio-grpc SYSTEM)
find_package(Boost)
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc Boost::headers)

Or using standalone Asio:

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

Or using libunifex:

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

Or using stdexec:

add_subdirectory(/path/to/asio-grpc SYSTEM)
find_package(stdexec)
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc-stdexec STDEXEC::stdexec)

CMake FetchContent

Fetch asio-grpc and other dependencies like gRPC:

include(FetchContent)
FetchContent_Declare(
    asio-grpc
    GIT_REPOSITORY https://github.com/Tradias/asio-grpc.git
    GIT_TAG v3.7.0
    SYSTEM)
FetchContent_MakeAvailable(asio-grpc)

Link with gRPC:

target_link_libraries(your_app PUBLIC gRPC::grpc++)

Finally chose the desired backend for asio-grpc:

Using Boost.Asio:

find_package(Boost) # or FetchContent equivalent
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc Boost::headers)

Or using standalone Asio:

find_package(asio) # or FetchContent equivalent
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc-standalone-asio asio::asio)

Or using libunifex:

find_package(unifex) # or FetchContent equivalent
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc-unifex unifex::unifex)

Or using stdexec:

find_package(stdexec) # or FetchContent equivalent
target_link_libraries(your_app PUBLIC asio-grpc::asio-grpc-stdexec STDEXEC::stdexec)

Raw source code

This type of usage is unsupported. Future versions of asio-grpc might break it without notice.

Copy the contents of the src/ directory into your project and add it to your project's include directories. Depending on your desired backend: Boost.Asio, standalone Asio, libunifex or stdexec, set the preprocessor definitions AGRPC_BOOST_ASIO, AGRPC_STANDALONE_ASIO, AGRPC_UNIFEX or AGRPC_STDEXEC respectively. Also make sure that the backend's header files and libraries can be found correctly.

CMake Options

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++.

Performance

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

Results

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.52.1, asio-grpc v2.5.0, jemalloc 5.2.1
Request scenario: string_100B

1 CPU server

name	req/s	avg. latency	90 % in	95 % in	99 % in	avg. cpu	avg. memory
rust_thruster_mt	48796	20.19 ms	9.42 ms	12.11 ms	516.23 ms	104.51%	12.06 MiB
rust_tonic_mt	43343	22.86 ms	10.42 ms	11.29 ms	662.73 ms	102.29%	14.39 MiB
go_grpc	38541	25.33 ms	38.74 ms	42.98 ms	53.94 ms	100.0%	25.19 MiB
rust_grpcio	34757	28.65 ms	30.18 ms	30.60 ms	31.68 ms	101.91%	18.59 MiB
cpp_grpc_mt	33433	29.77 ms	31.56 ms	32.07 ms	33.58 ms	102.22%	5.69 MiB
cpp_asio_grpc_callback	32521	30.61 ms	32.54 ms	33.14 ms	35.29 ms	101.65