Corral is a C++ concurrency library that implements cooperative single-threaded multitasking using C++20 coroutines. Its design is based on our experience using coroutines to support asynchronous I/O in real-world production code. Users familiar with the Trio library for Python will find a lot here that looks familiar. A few of corral's design goals are:
-
Structured concurrency baked in: tasks are organized into a tree of parent-child relationships, where the parent is responsible for waiting for its children to finish and propagates any exceptions that the children raise. This allows certain crucial features like resource management, task cancellation, and error handling to Just Work™ the way people would expect them to.
-
I/O and event loop agnostic: like quite a few other companies with decades of history, we have our own homegrown implementations of asynchronous I/O and event loops. We wanted to be able to use coroutines with them, as well as pretty much any other existing solution for asynchronous I/O (such as Boost.Asio, libuv, or libevent).
-
Bridging with callbacks: the majority of existing code uses callbacks for asynchronous I/O; rewriting all of it from the ground up, while entertaining, tends not to be a realistic option. We needed a way to have coroutine "pockets" in the middle of legacy code, being able call or be called from older code that's still using callbacks — so people could onboard gradually, one small piece at a time, getting benefit from these small pieces immediately.
Corral focuses on single-threaded applications because this results in
a simpler design, less overhead, and easier reasoning about
concurrency hazards. (In a single-threaded environment with
cooperative multitasking, you know that you have exclusive access to
all state in between co_await points.) Multiple threads can each
run their own "corral universe", as long as tasks that belong to
different threads do not interact with each other.
The code snippet below establishes a TCP connection to one of two remote servers, whichever responds first, and returns the socket.
using tcp = boost::asio::tcp;
boost::asio::io_service io_service;
corral::Task<tcp::socket> myConnect(tcp::endpoint main, tcp::endpoint backup) {
tcp::socket mainSock(io_service), backupSock(io_service);
auto [mainErr, backupErr, timeout] = co_await corral::anyOf(
// Main connection attempt
mainSock.async_connect(main, corral::asio_nothrow_awaitable),
// Backup connection, with staggered startup
[&]() -> corral::Task<boost::system::error_code> {
co_await corral::sleepFor(io_service, 100ms);
co_return co_await backupSock.async_connect(
backup, corral::asio_nothrow_awaitable);
},
// Timeout on the whole thing
corral::sleepFor(io_service, 3s));
if (mainErr && !*mainErr) {
co_return mainSock;
} else if (backupErr && !*backupErr) {
co_return backupSock;
} else {
throw std::runtime_error("both connections failed");
}
}Corral is a header-only library, so you can just copy the corral
subdirectory into your project and start using it. It does not depend
on any external libraries on its own. If you want to build the tests,
you will need Catch2, and the examples require various other I/O libraries.
Obviously a recent C++ compiler is required. The library has been tested on gcc-11 and clang-15+, and was known to occasionally ICE gcc-10.2 back in the day.
To allow people to explore more easily and quickly get something running,
corral ships with support for Boost.Asio out of the box: pass
corral::asio_awaitable (or corral::asio_nothrow_awaitable) to any asio async
operation to make it return a corral-compatible awaitable. Other I/O frameworks
or event loops can also be adapted to corral relatively straightforwardly.
examples/qt_echo_server.cc shows bridging of corral and Qt.