corolib

corolib is a C++ coroutine library for writing asynchronous distributed applications.

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 studies/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 examples/tutorial contains many examples using one or more corolib classes (async_task, async_operation, …), but without using any communication framework.
  • Directory studies/why-coroutines explains why you should consider the use of coroutines, by comparing three programming styles: synchronous, asynchronous (with callbacks) and coroutines.
  • Directory studies/transform explains how coroutines are transformed or lowered to non-coroutine C++ code.
  • 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
• libevent
• ROS2 (Humble)
• TAO (The ACE ORB)
• cppcoro (WIN32 API) (included in corolib)
• curl

You do not have to install Boost, Qt, gRPC, libevent, ROS2, TAO or curl on your computer before building corolib from the top-level CMakeLists.txt file. Without any of these libraries, you can still build and run many 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. The installation of these libraries is described below.

On Windows 10 or 11

corolib

Copy or clone corolib.git to your computer.

I originally developed corolib with Visual Studio 2019 and Qt Creator 4.12.0 on a Windows 10 laptop. Now I am using Visual Studio 2022 and Qt Creator 10.0.1 on a Windows 11 laptop.

Building the Visual Studio projects makes use of the CMake support of Visual Studio:

File -> Open -> CMake...

and select the CMakeLists.txt in the top-level folder.

Go to the examples/ subdirectories and start the executables. (See README.md files in the corresponding source directories.)

Boost

I originally used Boost 1.70 (now Boost 1.82), but many other versions will do.

Starting point: https://www.boost.org/

Download release 1.82 from https://boostorg.jfrog.io/artifactory/main/release/1.82.0/source/

I copied boost_1_82_0.zip to C:\local\boost and unzipped it into this directory.

In a Windows terminal (e.g. Command Prompt or PowerShell), go to C:\local\boost\boost_1_82_0

Follow the instructions in https://www.boost.org/doc/libs/1_82_0/more/getting_started/windows.html#simplified-build-from-source

Step 1: .\bootstrap.bat

This will generate b2.exe

Step 2: .\b2.exe

b2.exe generates the libraries we will need. Its execution takes a while.

The root directory for the include files is C:/local/boost/boost_1_82_0.

The root directory for the libraries is C:/local/boost/boost_1_82_0/stage/lib.

In the top-level CMakeLists.txt, adapt BOOST_ROOT to your own installation of the Boost library:

set(BOOST_ROOT C:/local/boost/boost_1_82_0/)

After installing Boost ASIO, set the BOOST_INSTALLED flag to TRUE in the top-level CMakelists.txt file if you want to build the Boost eaamples in examples/boost and examples/corolab.

Qt

Starting points: https://www.qt.io/download, https://www.qt.io/download-open-source

Download the Qt Online Installer for your operating system (macOS, Windows, Linux) (e.g., for Windows: qt-unified-windows-x64-4.5.2-online.exe).

File truncated at 100 lines see the full file