Features

• Prevent AGRPC_ macros from leaking into user code.
• Add operator bool and swap to agrpc::ServerRPCPtr.

Chore

• Update vcpkg (includes Boost 1.83->1.84 update)

v3 migration guide

Features

• De-experimentalize agrpc::ServerRPC, agrpc::ClientRPC and agrpc::register_x functions.
• Remove several functions and classes. See migration guide for details.
• asio-grpcConfig.cmake no longer calls find_package for all possible backends.
• Remove support for deprecated asio::execution functions.
• Remove deprecated ASIO_GRPC_USE_BOOST_CONTAINER and ASIO_GRPC_USE_RECYCLING_ALLOCATOR cmake options.

The agrpc::Server/ClientRPC API is not understood by Microsoft's Intellisense. If that bothers you then please react to this bug ticket.

Fixes

• InvokeHandler::YES/NO conflicts with Objective-C/C++ define YES/NO on Apple platforms.

Features

• Add support for stdexec::schedule(grpc_executor).

Fixes

• Fix deadlock when the rpc handler passed to agrpc::register_sender_rpc_handler in stdexec returns exec::task.
• Add missing includes for grpc::ServerAsyncX types in several places. This only lead to compilation errors in certain gRPC versions (~1.30-1.40).
• Fix compilation of tests with Boost 1.84 due to removed header file.

Performance

• No longer perform writes_done during finish if a previous write or read_initial_metadata ended in false in the streaming ClientRPCs.

Documentation

• Add v2 to v3 migration guide.
• Adjust some wording in the ServerRPC::finish documentation.

Chore

• Use file(GLOB) to create check-header-syntax target to avoid forgetting to add a new header to the list.
• Unify common parts of stdexec und unifex tests into one file.
• Build asio-grpc-check-header-syntax target in the Ubuntu/20.04/Default pipeline.

Fixes

• Add workaround for https://gcc.gnu.org/bugzilla/show_bug.cgi?id=102229 (affects GCC 11.1-11.2)

This will likely be the last release before v3.

Features

• Breaking change: When using sender/receiver, agrpc::Alarm will now use the set_done/set_stopped channel when cancelled, instead of sending a bool through the set_value channel.
• Breaking change: When using asio::execution the StopToken was obtained by calling asio::get_associated_cancellation_slot on the receiver. An unstoppable token is now used instead. Note that asio::execution is deprecated and should no longer be used.
• Asio and execution may now be used within the same application. Simply link with asio-grpc::asio-grpc(-standalone-asio) and asio-grpc::asio-grpc-(unifex|stdexec).
• Add execution::get_scheduler support to I/O objects.
• Mark senders [[nodiscard]].
• Fix and improve asio-grpc.natvis. Also add support for stdexec. To learn how natvis files can improve your debugging experience check out the Visual Studio or Visual Studio Code documentation.

Fixes

• Partially fix agrpc::Waiter.initiate for sender/receiver. Currently only the set_value channel is forwarded to the waiting operation.
• Make agrpc::process_grpc_tag work properly with unifex/stdexec instead of silently be a no-op.
• Use of register_yield_rpc_handler with standalone Asio 1.24.0+.
• Conditional detection of asio::execution with Asio 1.30.0+ / Boost 1.84+.

Chore

• Change the Boost.Asio+stdexec test to now use standalone Asio.
• Update Boost to 1.83.0.
• Update doxygen-awesome to 2.3.1.

Features

• Add agrpc::register_callback_rpc_handler for setting up request handling with agrpc::ServerRPCPtr, a dynamically allocated ServerRPC which can be used to implement non-coroutine based gRPC servers.
• Add experimental support for P2300R7 (std::execution) in the form of a new CMake target asio-grpc::asio-grpc-stdexec.
• Breaking change: Certain completion token like asio::experimental::use_promise might now return a different type due to the implementation of Asio's optional requirement on asynchronous operations: The operation's associated I/O executor may be exposed via the Initiation function object's executor_type type alias and get_executor() member function.

Fixes

• Removed all usage of pointer tagging. Although Asio uses it, it is technically undefined behavior.

Performance

• Use Asio's immediate_executor in ServerRPC::wait_for_done and Waiter::wait.

Documentation

• Use Asio's default completion token mechanism in examples.
• Avoid using asio::detached in examples since it swallows exceptions.
• Document how register_awaitable_rpc_handler and register_yield_rpc_handler obtain the executor used to spawn the coroutine.
• Removed documentation of deprecated CMake options.

Chore

• Remove codeql pipeline

This release prepares asio-grpc for a large trim down in the next major release by adding an API that follows Asio's I/O object model more closely, avoids the pitfalls of the current API and provides more customization options.

The following headers should be considered deprecated:
bind_allocator.hpp, cancel_safe.hpp, default_completion_token.hpp, get_completion_queue.hpp, grpc_initiate.hpp, grpc_stream.hpp, notify_when_done.hpp, repeatedly_request_context.hpp, repeatedly_request.hpp, rpc.hpp, use_awaitable.hpp, wait.hpp

Features

• Add agrpc::ServerRPC, new API for asynchronous servers.
• Add agrpc::register_awaitable_request_handler, agrpc::register_yield_request_handler and agrpc::register_sender_request_handler functions for setting up request handling with agrpc::ServerRPC.
• Breaking change in experimental agrpc::ClientRPC API:
  • Rename agrpc::ClientRPCGenericUnary to agrpc::GenericUnaryClientRPC.
  • Rename agrpc::ClientRPCGenericStreaming to agrpc::GenericStreamingClientRPC.
• Make unary ClientRPCs constructible and add start, read_initial_metadata and finish member functions.

Fixes

• Avoid UB from casting function pointer to void* in ClientRPC, BasicAlarm and notify_one_state_change asynchronous operations.
• Consistently take CompletionToken by forwarding-reference.

Performance

• Improve compile times of ClientRPC, BasicAlarm and notify_one_state_change asynchronous operations.

Documentation

• Remove documentation of old API.

Chore

• Run sonarscanner on Ubuntu 22.04 with GCC 11 and Java 17.
• Use vcpkg binarycaching with Github Caches.

Features

• Breaking change in experimental agrpc::RPC API:
  • Rename to agrpc::ClientRPC and agrpc::ClientRPCType.
  • Header name changed to client_rpc.hpp.
  • asio::use_awaitable is no longer the default completion token.
  • Remove third template parameter.
  • For streaming specializations:
    • ClientRPC now creates and owns the grpc::ClientContext, it can be customized during construction or later access using context().
    • Must now be started by calling start(), request() has been removed.
    • finish() and writes_done() no longer guard against being called multiple times.
  • For generic specializations:
    • Replace marker values agrpc::CLIENT_GENERIC_X_RPC with agrpc::ClientRPCType::GENERIC_X.
    • Add type aliases agrpc::ClientRPCGenericUnary<Executor> and agrpc::ClientRPCGenericStreaming<Executor>.
• De-experimentalize agrpc::HealthCheckService.
• Add cancel() to agrpc::Alarm.
• Add support for libunifex v0.2.0 to agrpc::repeatedly_request.

Fixes

• Typo in NotfiyWhenDoneFn

Documentation

• Simplify file-transfer example.

Chore

• Update libunifex to v0.2.0. Version 0.3.0 is also supported by held back due to an ICE in clang 10.

Fixes

• Remove Intellisense workaround from agrpc::RPC's RPCType deduction because it causes ICE since Visual Studio 17.5 (C++20 only). See bug report.
• Bump asio-grpc version in CMakeLists file.

Features

• Implement a pool memory resource based on Boost.Container's unsynchronized_pool_resource. This makes selecting between <memory_resource>, Boost.Container and asio::recycling_allocator obsolete. All related CMake options have been marked deprecated and only affect uses_allocator specializations now. They will be removed in version 3 which will always use std::uses_allocator.
• Deprecated: Due to the above, all typedefs in the agrpc::pmr namespace are deprecated and will be removed in v3.
• Add a new CMake option called ASIO_GRPC_BUILD_EXAMPLES which enables compilation of just examples without tests. Also, libunifex is now treated as an optional dependency.

Fixes

• agrpc::run* consumes a high amount of CPU resources when the GrpcContext had already stopped while the second argument (typically an io_context) had work left to do. To resolve that, agrpc::run* will now end when both contexts are stopped using new functions that were added to the RunTraits.

Documentation

• Create an article on the use of asio::io_context.

Chore

• Treat compiler warnings as error in CI.

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.