Crouton

Crouton is a C++20 coroutine runtime library that provides some general purpose concurrency utilities, as well as cross-platform event loops, I/O and networking that work the same way on Mac, Linux, Windows and ESP32 microcontrollers.

The cross-platform support is based on the widely-used libuv, mbedTLS and llhttp libraries. (On Apple platforms it can also use the system Network.framework. On ESP32, where libuv is not supported, it uses lwip and FreeRTOS APIs instead.)

A Coroutine is a function that can return partway through, and then later be resumed where it left off. Knuth wrote about them in the 1960s and they remained a curiosity for a long time, but they've since become widely used under the hood of the "async / await" concurrency model used in languages like JavaScript, C#, Rust, Nim, and Swift. Crouton brings this to C++.

Async/await gives you concurrency without the pitfalls of multithreading. You can write code in a linear fashion, "blocking" on slow operations like I/O (see the example below), but the thread doesn't really block: instead your (coroutine) function is suspended and some other function that's finished blocking can resume. When the I/O completes, your function is resumed transparently at the next opportunity.

How is that better than threads? It's safer and easier to reason about. The only places where concurrency happens are well-marked by the co_await and co_yield keywords. You don't need mutexes or atomic variables, and there are far fewer opportunities for race conditions or deadlocks. (There are performance benefits too: no expensive context switches, less stack usage.)

Detailed documentation is being written.

Features

• Coroutine library:

  • Useful base classes for implementing new coroutine types
  • Future, an asynchronous promise type
  • Generator, an iterator implementation based on co_yield-ing values
  • CoMutex, CoCondition, Blocker: cooperative equivalents of common sync primitives
  • AsyncQueue, a producer/consumer queue
  • Select, a way to await multiple things in parallel
  • Optional coroutine lifecycle tracking, with debugging utilities to dump all existing coroutines and their "call stacks".

• Event loops:

  • Scheduler, which manages multiple active coroutines on a thread
    • Round-robin scheduling of multiple active coroutines
    • Suspending a coroutine, then waking it when it's ready
    • Scheduling a function to run on the next event-loop iteration, even on a different thread
    • Scheduling a function to run on a background thread-pool
  • Task, an independently-running coroutine that can co_yield to give time to others
  • Timer, repeating or one-shot

• Reactive publish/subscribe framework

  • Enables building complex networked data flows out of modular components
  • Intrinsically supports backpressure to manage flow control on sockets
  • Loosely inspired by Apple's Combine framework
  • Double-plus experimental ⚗️

• Asynchronous I/O classes:

  • DNS lookup
  • File I/O
  • Filesystem APIs like mkdir and stat
  • Abstract asynchronous stream interface
  • In-process pipes
  • TCP sockets, with or without TLS
  • A TCP listener (no TLS support yet)
  • URL parser
  • HTTP client
  • HTTP server (very basic so far)
  • WebSocket client and server
  • BLIP RPC protocol (optional; under separate license.)

• Core classes & APIs:

  • General-purpose Error and Result<T> types
  • Logging, a very compact library with an API inspired by spdlog.
  • Type-safe string formatting, similar to std::format but with a much lower code footprint.

• Cross-Platform:

  • macOS (builds and passes tests)
    • iOS? ("It's still Darwin…")
  • Linux (builds and passes test)
    • Android? ("It's still Linux…")
  • ESP32 embedded CPUs (builds and passes tests. Networking works, but filesystem APIs aren't implemented yet.)
  • Windows (builds, but I don't have any Windows machines to test on. Help wanted!)

Example

// Simple HTTP client request:
HTTPConnection client("https://example.com");
HTTPRequest req;
HTTPResponse resp = co_await req.sendRequest(req);

cout << int(resp.status()) << " " << resp.statusMessage() << endl;

for (auto &header : resp.headers())
    cout << header.first << " = " << header.second << endl;

ConstBuf body;
do {
    body = co_await resp.readNoCopy();
    cout << string_view(body);
} while (body.len > 0);
cout << endl;

See also demo_server.cc, a simple HTTP and WebSocket server.

An example embedded app is at tests/ESP32.

Status: ☠️EXPERIMENTAL☠️

This is new code, under heavy development! So far, it builds with Clang (Xcode 15) on macOS, GCC 12 on Ubuntu, Visual Studio 17 2022 on Windows, and ESP-IDF 5.1.

The tests run regularly on macOS, and occasionally on Ubuntu (though not in CI.) Test coverage is very limited.

APIs are still in flux. Things get refactored a lot.

Building It

Important: Make sure you checked out the submodules! git submodule update --init --recursive

Prerequisites:

• CMake
• Clang 15, Xcode 15, or GCC 12
• zlib (aka libz)

on macOS:

• Install Xcode 15 or later, or at least the command-line tools.
• Install CMake; this is most easily done with HomeBrew, by running brew install cmake

on Ubuntu Linux

sudo apt-get install g++ cmake cmake-data zlib1g-dev

Building With CMake

make
make test

The library is libCrouton, in either the build_cmake/debug/ or build_cmake/release/ directory.

Building With Xcode 15+

Before first building with Xcode, you must use CMake to build libuv and mbedTLS:

make xcode_deps

You only need to do this on initial setup, or after those submodules are updated.

Then:

• open crouton.xcodeproj
• Select the Tests scheme and Run.
• To locate the binaries, choose Product > Show Build Folder In Finder

Building For ESP32 Embedded Systems

The ESP-IDF component is at src/io/esp32; please see the README for details. A demo app is at tests/ESP32.

License(s)

• Crouton itself is licensed under the Apache 2 license.
  • The files in the subdirectory src/io/blip, however, are under the Business Software License since they are adapted from existing BSL-licensed code. These source files are optional and are by default not compiled into the Crouton library. See their README for details and the full license.
  • The source file src/io/URL.cc contains some code adapted from tlsuv, which is Apache 2 licensed.
• Of the third party code in vendor/:
  • Catch2 is licensed under the Boost Software License (but is only linked into the tests)
  • libuv is licensed under the MIT license.
  • llhttp is licensed under the MIT license.
  • mbedtls is licensed under the Apache 2 license.
  • spdlog is licensed under the MIT license.

Credits

• Crouton code by Jens Alfke (@snej)
• Initial inspiration, coroutine knowledge, starting code: Simon Tatham's brilliant tutorial. Lewis Baker's blog posts have also been helpful.
• Event loops, I/O, networking: libuv
• TLS engine: mbedTLS
• HTTP parser: llhttp
• Logging: spdlog
• Unit tests: Catch2
• Extra inspiration and URL parser: tlsuv