corolib

corolib is a C++ coroutine library for writing asynchronous distributed applications using Boost ASIO, Qt, gRPC, ROS2, TAO, …, as communication frameworks.

Objectives

corolib has two main objectives:

• Demonstrate that it is possible to write asynchronous distributed applications in a synchronous style using various (open source) asynchronous communication frameworks.

  • Asynchronous operations can be completed on the same thread they are started on (completion functions are called from an event loop) or on another thread.
  • There is no need to make changes to these frameworks or to the corolib library, but sometimes an “adaptation layer” is useful. This layer contains functionality that would otherwise be replicated in the applications.

• Learning about and experimenting with coroutines.

  • Directory corolab (short for “coroutine laboratory”) contains simple stand-alone programs that also include a coroutine definition; the reader just has to open a single file to have access to all source code.
  • Directory tutorial contains many examples using one or more corolib classes (async_task, async_operation, …), but without using any communication framework.
  • Directory why-coroutines explains why you should consider the use of coroutines for writing (distributed) asynchronous applications, by comparing three programming styles: synchronous, asynchronous (with callbacks) and coroutines.
  • Directory why-coroutines2 contains examples that explain the advantages of C++ coroutines for writing asynchronous I/O-based applications.
  • Directory transform explains how coroutines are transformed or lowered to non-coroutine C++ code.

The reader is referred to studies for more examples and experiments.

In addition:

• corolib contains a dedicated print function, taking a print level as first argument; this allows following the control flow of a coroutine program at various levels: application level, corolib level, user-specific level, …
• corolib contains tracking functions that allow verifying whether all coroutine return type objects, operation objects, promise objects and final awaiter objects are released.
• Class async_task can be tailored, allowing to experiment with the three await_suspend return types (void, bool, std::coroutine_typs<>), so that the user can compare the pros and cons of these variants.

Installation and building

For its communication, corolib currently uses any of the following frameworks:

• Boost ASIO library
• Qt (QTcpSocket, QTcpServer)
• gRPC (Google Remote Procedure Call)
• cppcoro (source code included in corolib)
• libevent
• ROS2 (Humble) (ROS = Robot Operating System)
• TAO (The ACE (ADAPTIVE (A Dynamically Assembled Protocol Transformation, Integration and eValuation Environment)) ORB (Object Request Broker))
• curl

You do not have to install any of these frameworks/libraries on your computer before building corolib from the top-level CMakeLists.txt file.

Without any of these libraries, you can still build and run the tutorial examples illustrating the use of corolib.

You can install any of the mentioned communication libraries one by one and then include them in the build by setting a flag in the top-level CMakeLists.txt file.

Please read Installation and building on Windows for instructions on how to install and build corolib and its examples on Windows 10/11.

Please read Installation and building on Ubuntu for instructions on how to install and build corolib and its examples on Ubuntu 22.04/24.04/26.04.

After having built one or more communication frameworks, run scripts/copy.bat (on Windows) or scripts/copy.sh (on Ubuntu) to copy configuration and run files to the folders with the executables.

Organization of corolib

The GitHub repository contains the library itself and several examples and studies.

The README.md file in corolib gives more information on each of the classes of corolib. Folder lib contains the source (.cpp) files for the header files (.h) in include.

The examples folder contains a README.md file with more information on the examples.

The studies folder contains a README.md file with more information on the studies.

Why coroutines?

Reason 1: Coroutines allow writing (distributed) applications using a natural synchronous style, but with the efficiency benefits of asynchronous execution.

An application running on one processor can invoke an operation in an application on the same or another processor in a synchronous or asynchronous way.

• Using a synchronous operation, the application will block until the remote application has replied.

  In the meantime, the application cannot respond to new requests unless new requests are processed on a separate thread or the operation itself runs on a separate thread.

• Using an asynchronous operation, the application can start the operation by sending a request to the remote application, proceed with other tasks that do not depend on the response and then await the response either using polling or using a callback function that is called from a local or global event loop.

  The reader is referred to CORBA-AMI for more information on this approach.

• Using an asynchronous operation in combination with coroutines, the callback function can be hidden in the library (corolib in this case) and the response will be returned by the co_await statement. Usually this co_await statement will be placed in the coroutine in which the asynchronous operation was invoked.

  The callback function will pass the result of the remote operation invocation to the application and resume it. The application will then continue its flow and invoke new asynchronous operations. This is a more natural place than handling the response in the callback function from which new operations will be invoked.

File truncated at 100 lines see the full file