Features

• Add cancellation support to agrpc::RPC.
• Add a new install option to use asio::recycling_allocator instead of <memory_resource> or Boost.Container. This can be handy in combination with libc++ and standalone Asio to avoid taking a dependency on Boost.
• Deprecated: Constructor agrpc::GrpcContext{std::make_unique<grpc::CompletionQueue>()}, use the new default constructor instead.
• Deprecated: Member function agrpc::CancelSafe::is_running has been renamed to is_wait_pending() because it never reported whether the asynchronous operation is still running but instead whether a wait is currently pending.

Fixes

• A failed write with grpc::WriteOptions::set_last_message on a high-level client streaming RPC incorrectly completes with true.
• The operation state obtained by connecting a receiver to the sender returned by agprc::notify_when_done is deallocated during GrpcContext destruction, leading to double free because the lifetime of the operation state is expected to be handled by the connector.
• Using asio::deferred for agrpc::RPC::finish and agrpc::RPC::writes_done does not compile.
• The rvalue-overload of agrpc::Alarm::wait does not extend the lifetime of the alarm correctly when using completion tokens like asio::deferred.
• Honor ASIO_GRPC_USE_BOOST_CONTAINER CMake variable when using asio-grpc with add_subdirectory.
• Compatibility of sender/receiver with Asio 1.25/Boost 1.81.

Performance

• Improve performance of high-level client read_initial_metadata, read, write and finish by replacing some if-conditions with compile time dispatch.
• Reduce allocation size of each health check watch request.
• Reduce size of all sender operation states by one pointer and the notify_when_done operation state by two pointers.

Documentation

• Correctly state that agrpc::RPC::read_initial_metadata may not be called concurrently with write.

Chore

• Adjust .clang-tidy rules.
• Fix CMAKE_UNITY_BUILD and enable it for some CI builds.
• Add test for add_subdirectory-consumption of asio-grpc.
• Update doxygen and doxygen-awesome.

Features

• Add agrpc::notify_when_done, a function for grpc::ServerContext::AsyncNotifyWhenDone that does not suffer from memory leaks like a agrpc::grpc_initiate version would.
• Add agrpc::notify_on_state_change, a function for grpc::ChannelInterface::NotifyOnStateChange.
• Deprecate agrpc::grpc_initiate, use the above functions instead.
• Add a CompletionQueue-based implementation of grpc::HealthCheckServiceInterface. GRPC's default health check service is implemented with the callback API which significantly reduces the performance of a server that also uses the CompletionQueue API (aka. any functionality of this library).

Chore

• Update libunifex to 2022-10-10 and gRPC to 1.50.1

Features

• Add agrpc::RPC<>::service/method_name():

package example.v1;
 
service Example { rpc Unary(Request) returns (Response) {} }

using RPC = agrpc::RPC<&example::v1::Example::Stub::PrepareAsyncUnary>;
static_assert(RPC::service_name() == "example.v1.Example");
static_assert(RPC::method_name() == "Unary");

• Add agrpc::Alarm, an I/O object that wraps grpc::Alarm. A safer alternative to the agrpc::wait free function. Additionally supports ad-hoc waits which automatically extend the lifetime of the underlying gRPC alarm, for example with a callback:

agrpc::Alarm(grpc_context).wait(deadline, [](bool ok, agrpc::Alarm&& alarm) {});

Fixes

• Leak of uncompleted sender operation states and asynchronous operations started by the high-level client API upon destruction of the GrpcContext.
• For each request in the sender overload of agrpc::repeatedly_request, make a copy of the request handler to avoid lifetime surprises when the handler returns unifex::task<>.

Performance

• Improve compile times by no longer instantiating entire operation states with two different allocators, but instead only their completion function. This affects all free functions, like agrpc::read and agrpc::wait, as well as the high-level client API.

Chore

• Use a more meticulous gRPC shutdown sequence in tests to make them less flaky.
• Update tests and examples to Boost 1.80.

Features

• Add a high-level client API - a new major feature that makes writing asynchronous gRPC clients easier and safer.
• In asio_grpc_protobuf_generate, check the validity of IMPORT_DIRS at CMake configure time instead of build time.
• The asio-grpc source files can now be consumed without CMake. In that case, the compile definition AGRPC_USE_BOOST_CONTAINER can be used to choose between <memory_resource> and Boost.Container.

Fixes

• Enable cancellation support for standalone Asio 1.19.0 instead of 1.20.0. Note that throwing exceptions from the request handler of agrpc::repeatedly_request crashes until 1.19.2.
• Correctly handle .proto filenames that include dots in asio_grpc_protobuf_generate.
• Return correct sender from asio::execution::schedule(GrpcExecutor) when compiling in C++17 using MSVC.

Performance

• Turn cancellation check in agrpc::repeatedly_request to a no-op when the completion handler does not support cancellation.
• Replace most calls to std::move and std::forward with static_cast and use a simpler version of std::tuple to improve compile times.

Documentation

• State that read_initial_metadata will not complete until the server calls write_initial_metadata or the client performs a write/finish.
• Add generic bidirectional streaming example.
• Add dark mode to documentation website.

Chore

• No longer run CodeQL in Github Actions since it stopped working and never diagnosed anything useful.

Breaking change: All headers now use snake_case instead of camelCase, e.g. #include <agrpc/asioGrpc.hpp> becomes #include <agrpc/asio_grpc.hpp>.

Breaking change: Two overloads for requesting unary RPCs have been removed, example: co_await agrpc::request(&example::v1::Example::Stub::AsyncUnary, stub, client_context, request). Please use other means of obtaining a reference to the agrpc::GrpcContext and then call agrpc::request(&example::v1::Example::Stub::AsyncUnary, stub, client_context, request, grpc_context).

Breaking change: Unsafe overloads of agrpc::get_completion_queue have been removed.

Breaking change: asio-grpcConfig.cmake will now autolink with gRPC::grpc++_unsecure instead of gRPC::grpc++. If you are using encrypted gRPC then you need to explicitly link with gRPC::grpc++ in your CMake files.

Breaking change: If the completion handler passed to an asynchronous operation does not have an associated allocator then asio-grpc will no longer attempt to retrieve one from the associated executor through asio::query(executor, asio::execution::allocator). This behavior had been deprecated in v1.6.0.

Features

• Add run_until(deadline) to agrpc::GrpcContext.
• Add PrepareAsync overloads for requesting RPCs in a thread-safe manner.
• Deprecate the Async overloads for requesting client-side streaming RPCs as they can lead to race-conditions.
• Add agrpc::BasicGrpcStream overload to agrpc::get_completion_queue.
• Make agrpc::AllocatorBinder fully constexpr compatible.

Style

• No longer use std::aligned_storage since it is deprecated in C++23.
• Continue to implement compile time improvements.

Documentation

• Add examples for multi-threaded clients and servers.
• Make the ServerShutdown that is used in examples thread-safe.

Chore

• Asio-grpc is now available on conan-center!
• Use CTest's --build-and-test command for the asio-grpc-cmake test. Also use an older version of CMake (3.16) for that test.
• Remove GCC 9 and Clang 11 pipelines.
• Update doctest, gRPC, gtest, libunifex and liburing in the pipelines.

Features

• Add overloads to agrpc::request and agrpc::repeatedly_request for generic RPCs.
• Add overload to agrpc::request for starting a client-side unary request. The last argument to this function is a agrpc::GrpcContext instead of a CompletionToken because the function completes immediately.
• Add overloads to RPC functions for -Interface versions of stub/service/reader/writer/reader_writer/response_writer.
• Add agrpc::GrpcContext.run_completion_queue()/poll_completion_queue() which only process events from the grpc::CompletionQueue. They can be used as a better performing alternative to run()/poll() where the GrpcContext is not used as an Asio execution context.
• RPC functions now automatically unwrap std::unique_ptr. (Except stubs which will be addressed in the next release)
• Stabilize API of agrpc::CancelSafe. Compared to the previous release it now takes a completion signature as template argument, example: Change agrpc::CancelSafe<bool> to agrpc::CancelSafe<void(bool)>
• (experimental) Add agrpc::GrpcStream, an IoObject-like class for handling RPCs in a cancellation safe manner. See the new handle_topic_subscription example on how it can be used to write Golang/Rust select-style code.
• (experimental) Replace agrpc::PollContext with a more optimized free function agrpc::run that can be used to run an asio::io_context and agrpc::GrpcContext in the same thread.
• (experimental) Add utility function to manually process gRPC tags, useful for writing mocked stubs.

Style

• Use C++20 concepts when available to potentially improve compile times.
• Implement several small compile time improvements.

Documentation

• Move doxygen documentation to the gh-pages branch.

Chore

• Add pipeline for gRPC 1.16.1.
• Use CMake version 3.16.3 for the CMake install test.
• Add CMake option to fallback to pkg-config when a dependency cannot be found. This option is for maintainers.
• Add GTest to vcpkg dependencies.

Features

• (experimental) Add agrpc::CancelSafe, a utility to make RPC step functions compatible with Asio's cancellation mechanism.
• agrpc::PollContext now uses a configurable backoff to avoid wasting CPU resources during GrpcContext idle time.
• agrpc::GrpcContext::run and poll now return a boolean indicating whether at least one operation has been processed.
• Add .natvis file. It is automatically added to the interface sources of asio-grpc when using the Visual Studio generator. In VSCode it should be added manually to the "visualizerFile" field in launch.json.
• Defining (BOOST_)ASIO_NO_TS_EXECUTORS now hides members functions of the agrpc::GrpcExecutor related to Networking TS executors: context(), on_work_started(), on_work_finished(), dispatch(), defer() and post().
• Deprecated: If a completion handler does not have an associated allocator then asio-grpc retrieves one from the associated executor's allocator property. This behavior will be removed in v1.8.0. Please use agrpc::bind_allocator(allocator, completion_token) or asio::bind_allocator instead.

Fixes

• Defining (BOOST_)ASIO_HAS_DEDUCED_XXX_TRAIT macros is no longer required when compiling with MSVC in C++17.
• Using polymorphic_allocator as the associated allocator of the completion handler passed to agrpc::repeatedly_request did not compile in C++20. Likewise, using std::allocator_traits<polymorphic_allocator>::construct would propagate the allocator to the constructor of agrpc::GrpcContext, agrpc::GrpcExecutor and agrpc::AllocatorBinder which was rather unexpected.
• The comparison operator of agrpc::GrpcExecutor would not compile on older compilers if the allocator is not comparable, e.g. because it is std::allocator<void>.
• Always return relationship::fork when querying a agrpc::GrpcExecutor for its relationship since that is the only supported setting. Preferring a different relationship property from the executor now returns the executor unchanged.

Performance

• The client-side request convenience overloads now also perform unbinding of associated characteristics to reduce memory allocation size.
• Also unbind asio::allocator_binder when using Boost.Asio 1.79.0 or Asio 1.22.1.

Style

• Including agrpc/grpcContext.hpp now only provides forward declarations of the GrpcContext and its member functions. If you experience use of undefined function issues then add an include to agrpc/grpcExecutor.hpp.
• No longer open the Asio namespace to specialize class templates.
• Remove unused header <variant>.

Documentation

• Document Per-Operation Cancellation properties of all asynchronous functions.
• Document differences in the behavior of asynchronous operations compared to Asio.
• Make examples more readable by visually separating individual sub-examples.

Chore

• Asio-grpc is now available through the Hunter package manager!
• Add GCC 8.4.0 to Github Actions.
• Add CMake target to run -fsyntax-only//Zs on public header files and build that target as part of Github Actions.
• Update Boost to 1.79.0.

Fixes

• Incorrect work counting of agrpc::repeatedly_request with awaitable which could lead to an early stop of an agrpc::GrpcContext or crash during destruction.

Features

• Add agrpc::bind_allocator which associates an allocator to a completion token's completion handler. Similar to the new asio::bind_allocator except that it also works in older versions of Asio and provides empty class optimization on the allocator.
• Add agrpc::GrpcContext.poll() which processes only completed handler.
• Adjust the behavior of a stopped agrpc::GrpcContext to mimic that of asio::io_context. Operations submitted to a stopped context will no longer be discarded and instead processed the next time run() or poll() is called.
• (experimental) Add agrpc::PollContext which repeatedly polls a agrpc::GrpcContext within a different execution context. An example showing how this can be used to run an asio::io_context and agrpc::GrpcContext on the same thread has been added as well.

Fixes

• Certain headers did not work without also including other headers.

Performance

• Executor binder, allocator binder and cancellation slot binder are now unbound from completion handlers in RPC functions, thereby reducing the memory allocation size.
• Avoid one dynamic memory allocation per request in agrpc::repeatedly_request with awaitable.

Style

• Remove deprecated agrpc::use_scheduler.

Documentation

• Add example that shows how to process a bidirectional stream by dispatching work to a thread_pool.
• Add example that performs double-buffered, allocation-free file transfer using gRPC and io_uring.
• Update doxygen-awesome to 2.0.2.

Chore

• Run msvc-code-analysis alongside CodeQL every week.
• Update vcpkg and use manifest mode and CMake presets in github actions. Also compile dependencies in release only.
• Add several /Zc flags when compiling with MSVC to make it more C++-standard compliant.

Features

• Upcoming breaking change: agrpc::use_scheduler has been renamed to agrpc::use_sender. The old version will be removed in v1.5.0.
• Stabilize agrpc::repeatedly_request's API. It now supports CancellationSlot/StopToken, asio::awaitable, Sender and a final CompletionToken. Also reduced the memory needed per request. See documentation and examples for more details.
• Add agrpc::write_last which coalesces write and finish for server-side streaming RPCs and combines write and writes_done for client-side streaming RPCs.
• Add StopToken support to agrpc::wait.
• asio_grpc_protobuf_generate can now handle .proto files that are nested within the import directory.
• Turn get_completion_queue into a function object.
• Split public header files. They may now be included individually instead of only through the asioGrpc.hpp file.

Fixes

• agrpc::wait was incorrectly using the cancellation slot of the CompletionToken instead of the CompletionHandler, leading to broken cancellation propagation.

Performance

• Enable likely/unlikely attribute equivalents for C++17.

Style

• Issue a static assertion when asio-grpc is used without passing it to a target_link_libraries call in CMake which can lead to hard to decipher errors: https://github.com/Tradias/asio-grpc/issues/12.
• Move .ipp headers out of the public include directory.
• Mark RPC functions noexcept when agrpc::use_sender is the CompletionToken.

Documentation

• Complete API reference documentation is now available online and in code!
• Provide an example on how to cancel individual RPC steps based on a deadline.
• Provide documentation on how to use callbacks and stackless coroutines.
• Fix compilation of the unifex server-streaming documentation snippets.
• Mention that calls to find_package are needed in the As a subdirectory section of the README.
• Update the Using vcpkg section of the README to reflect the automatic interface link library setup performed by asio-grpcConfig,cmake.

Chore

• Avoid duplicate compilation of generated protobuf files in tests.
• Use libc++ for Ubuntu Clang builds.
• Enable coroutines and unifex for Clang builds.
• Use minimum supported standalone Asio version for CI and during development.
• Use asio separate compilation in tests.
• Update unifex to December release.

Fixes

• Add inline namespace so that libraries using different backends (Boost.Asio, standalone Asio or libunifex) can be linked together (as long as asio-grpc is not part of their public headers)

Style

• Move GrpcSender and ScheduleSender into the detail namespace
• Remove template parameter from UseScheduler
• Remove unused arguments in streaming-server.cpp example

Features

• Initial support for the Unified Executors proposal through libunifex and Asio
• New special completion token created by agrpc::use_scheduler that causes an RPC step function to return a TypedSender
• Support for standalone Asio
• New targets: asio-grpc::asio-grpc-standalone-asio and asio-grpc::asio-grpc-unifex for the standalone Asio and libunifex based versions of this library respectively
• The CMake package now finds and sets up linkage with dependencies. Can be disabled by setting ASIO_GRPC_DISABLE_AUTOLINK before the call to find_package(asio-grpc)
• No longer depend on Boost.Intrusive and Boost.Lockfree

Fixes

• Add several missing agrpc::write with grpc::WriteOptions overloads

Performance

• Faster interaction with the GrpcContext from the thread that called .run() and even more so from other threads
• Improved GrpcContext::run implementation

Style

• Avoid additional, identical instantiations of RPC initiating functions for different completion tokens
• Turn several functions into niebloids

Chore

• Add several more examples
• Add tests for examples
• Reduce minimum required CMake version to 3.14 when only installing the project

Features

• Provide CMake function: asio_grpc_protobuf_generate.
• Add work tracking to all operations. This makes the behavior of GrpcContext similar to boost::asio::io_context. E.g. instead of writing

auto guard = boost::asio::make_work_guard(grpc_context);
boost::asio::post(grpc_context,
            []
            {
                guard.reset();
            });
grpc_context.run();

it is now sufficient to write:

boost::asio::post(grpc_context, [] {});
grpc_context.run();

Fixes

• A GrpcContext is now stopped after returning from run() if there were no outstanding operations when the call was made.
• GrpcExecutor::operator== would fail to compare executors with different execution properties.

Chore

• Add CI pipelines for GCC 9.3.0, 11.1.0 and Clang 10.0.0, 11.0.0, 12.0.0.
• Enable code coverage on sonarcloud.
• Document how to shut down a gRPC server properly.

Chore

• Generate ASIO_GRPC_USE_BOOST_CONTAINER related header files in the build directory instead of the source directory as required by vcpkg_cmake_configure.

Fixes

• Small breaking change: Remove the optional second argument from the agrpc::GrpcContext constructor which would incorrectly turn a completion handler with an associated std::allocator into a completion handler that uses the specified argument for allocations. If control over the allocator is needed then resort to Boost.Asio's standard mechanisms: Associate the allocator with the completion handler or boost::asio::require the allocator from the executor.
• Bake the choice of ASIO_GRPC_USE_BOOST_CONTAINER into the installed header files to avoid accidental mixing of libraries compiled with and without it. This behavior is also required by vcpkg.

Chore

• Add CMake-based pre-commit hooks and CONTRIBUTING guidelines.

Features

• Use Boost.Container instead of <memory_resource> by setting the CMake variable ASIO_GRPC_USE_BOOST_CONTAINER
• agrpc::wait can now be cancelled by associating a cancellation slot to the CompletionToken (Boost 1.77.0)
• (experimental) New function agrpc::repeatedly_request. Can be used by servers to ensure that there are enough outstanding calls to request a new RPC. It takes a function object which should define how to handle an incoming RPC, it could e.g. be co_spawning a new coroutine to process it.

Fixes

• boost::asio::require(grpc_executor, boost::asio::execution::allocator) would not compile due to calling a constructor that is explicit

Performance

• Reduce memory allocation size of asynchronous operations that use the default allocator or where submitted from the thread that is calling agrpc::GrpcContext::run
• Remove redundant if-condition when deallocating an asynchronous operation

Style

• Provide better error message when attempting to use the DefaultCompletionToken without coroutines being available
• Remove [[nodiscard]] from agrpc::request functions

Chore

• Do not attempt to find_package or link with gRPC::grpc++ and Boost::headers when only installing the CMake project
• Add Github build and test actions for MacOS-11 (AppleClang 12) and Windows-2022
• Add Github action for automatically running MarkdownSnippets
• Fix CMake unity build by excluding protobuf generated source files from it

• Fix compatibility with older versions of Boost that do not support awaitables when compiling with C++20

• ExecutionContext compatible agrpc::GrpcContext
• Executor and Networking TS compatible agrpc::GrpcExecutor
• Support for all types of RPC, both client-side and server-side. Including support for all (non-experimental) CompletionTokens that Boost.Asio comes with.
• Support for waiting for a grpc::Alarm