Libfork
A bleeding-edge, lock-free, wait-free, continuation-stealing tasking library built on C++20's coroutines
Install / Use
/learn @ConorWilliams/LibforkREADME
Libfork is primarily an abstraction for fully-portable, strict, fork-join parallelism. This is made possible without the use of any macros/inline assembly using C++20's coroutines. Ultra-fine grained parallelism (the ability to spawn tasks with very low overhead) is enabled by an innovative implementation of an (almost) non-allocating cactus-stack utilizing segmented stacks. Libfork presents a cross-platform API that decouples scheduling tasks (a customization point) from writing tasks. Additionally, libfork provides performant NUMA-aware work-stealing schedulers for general use. If you'd like to learn more check out the tour of libfork then try it on compiler explorer or, just grok the TLDR:
#include "libfork/core.hpp"
inline constexpr auto fib = [](auto fib, int n) -> lf::task<int> {
if (n < 2) {
co_return n;
}
int a, b;
co_await lf::fork[&a, fib](n - 1); // Spawn a child task.
co_await lf::call[&b, fib](n - 2); // Execute a child inline.
co_await lf::join; // Wait for children.
co_return a + b; // Safe to read after a join.
};
Performance
Libfork is engineered for performance and has a comprehensive benchmark suit. For a detailed review of libfork on 1-112 cores see the paper, the headline results are linear time/memory scaling, this translates to:
- Up to 7.5× faster and 19× less memory consumption than OneTBB.
- Up to 24× faster and 24× less memory consumption than openMP (libomp).
- Up to 100× faster and >100× less memory consumption than taskflow.
Scheduler overhead
For a quick comparison with other libraries, the average time to spawn/run a task during the recursive Fibonacci benchmark gives a good approximation to the tasking overhead and peak throughput:
<p align="center"> <img src="bench/basic/f40.svg" alt="Fibonacci task benchmark results" width=100%/> </p>Memory consumption
Libfork is competitive with other libraries in terms of memory consumption; below is the peak (physical) memory allocation during the T3L unbalanced tree search benchmark:
<details> <summary>View graph</summary> <p align="center"> <img src="bench/basic/mem.svg" alt="Fibonacci task benchmark results" width=100%/> </p> </details>Using libfork
Libfork is a header-only library with full CMake support and zero required-dependencies. Refer to the BUILDING document for full details on compiling the tests/benchmarks/docs, installation, optional dependencies and, tools for developers. See below for the easiest ways to consume libfork in your CMake projects.
Package managers
We recommend consuming libfork via a package manager, this streamlines the management of optional dependencies.
vcpkg
Libfork is available via vcpkg. Add the following to your vcpkg.json:
"dependencies": [
"libfork"
]
You may then use the library in your project's cmake:
find_package(libfork CONFIG REQUIRED)
target_link_libraries(
project_target PRIVATE libfork::libfork
)
NOTE: The libfork port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.
Conan2
Libfork is available in Conan Center Index, to install the latest version run (Please make sure that you use a c++20 ready conan profile!):
conan install --requires="libfork/[*]" --build=missing
Or add libfork/[*] to your conanfile recipe requirements.
You may then use the library in your project's cmake:
find_package(libfork CONFIG REQUIRED)
target_link_libraries(
project_target PRIVATE libfork::libfork
)
NOTE: The libfork recipe in Conan is kept up to date by Conan team members and community contributors. If the version is out of date, please create an issue or pull request on the Conan repository.
With CMake
If you have installed libfork from source, following the BUILDING document, then you can use the following CMake code to consume libfork in your project:
find_package(libfork CONFIG REQUIRED)
target_link_libraries(
project_target PRIVATE libfork::libfork
)
Using CMake's FetchContent
If you have not installed libfork you may use CMake's FetchContent to download and build libfork as part of your project:
include(FetchContent)
FetchContent_Declare(
libfork
GIT_REPOSITORY https://github.com/conorwilliams/libfork.git
GIT_TAG v3.7.2
GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(libfork)
target_link_libraries(
project_target PRIVATE libfork::libfork
)
Using git submodules
You can incorporate libfork into your project as a git submodule. In this case, assuming you cloned libfork as a submodule into "external/libfork":
add_subdirectory(external/libfork)
target_link_libraries(
project_target PRIVATE libfork::libfork
)
Single header
Although this is not recommend and primarily exist for easy integration with godbolt; libfork supplies a single header that you can copy-and-paste into your project. See the BUILDING document's note about hwloc integration and compiler flags.
<!-- TODO: godbolt with include. -->API reference
See the generated docs.
Contributing
- Read the CODE_OF_CONDUCT document.
- Read the BUILDING document.
- Have a snoop around the
implnamespace. - Ask as many questions as you can think of!
Changelog
See the ChangeLog document.
A tour of libfork
This section provides some background and highlights of the core API, for details on implementing your own schedulers on-top of libfork see the extension documentation. Don't forget you can play around with libfork on godbolt.
Contents
- Fork-join
- The cactus stack
- Restrictions on references
- Delaying construction with
lf::eventually<T> - Exception in libfork
- Immediate invocation
- Explicit scheduling
- Contexts and schedulers
Fork-join
Definitions:
- Task: A unit of work that can be executed concurrently with other tasks.
- Parent: A task that spawns other tasks.
- Child: A task that is spawned by another task.
The tasking/fork-join interface is designed to mirror Cilk and other fork-join frameworks. The best way to learn is by example, lets start with the canonical introduction to fork-join, the recursive Fibonacci function, in regular C++ it looks like this:
auto fib(int n) -> int {
if (n < 2) {
return n;
}
int a = fib(n - 1);
int b = fib(n - 2);
return a + b;
}
We've already seen how to implement this with libfork in the TLDR but, here it is again with line numbers:
1| #include "libfork/core.hpp"
2|
3| inline constexpr fib = [](auto fib, int n) -> lf::task<int> {
4|
5| if (n < 2) {
6| co_return n;
7| }
8|
9| int a, b;
10|
11| co_await lf::fork[&a, fib](n - 1);
12| co_await lf::call[&b, fib](n - 2);
13|
14| co_await lf::join;
15|
16| co_return a + b;
17| };
NOTE: If your compiler does not support the lf::fork[&a, fib] syntax then you can use lf::fork(&a, fib) and similarly for lf::call.
This looks almost like the regular recursive Fibonacci function. However, there are some important differences which we'll explain in a moment. First, the above fibonacci function can be launched on a scheduler, like lazy_pool, as follows:
#include "libfork/schedule.hpp"
int main() {
lf::lazy_pool pool(4); // 4 worker threads
int fib_10 = lf::sync_wait(pool, fib, 10);
}
The call to sync_wait will block the main thread (i.e. the thread that calls main()) until the pool has completed execution of the task. Let's break down what happens after that line by line:
- Line 3: First we define an async function. An async function is a function-object with a templated first argument that returns an `
Related Skills
node-connect
343.1kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
frontend-design
90.0kCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
openai-whisper-api
343.1kTranscribe audio via OpenAI Audio Transcriptions API (Whisper).
qqbot-media
343.1kQQBot 富媒体收发能力。使用 <qqmedia> 标签，系统根据文件扩展名自动识别类型（图片/语音/视频/文件）。
