A cooperative fiber scheduler for Linux with per-CPU scheduler threads, io_uring integration, and topology-aware work-stealing. Fibers are lightweight stackful coroutines that suspend rather than block their OS thread, enabling high concurrency with low overhead.
docs/scheduler.md— scheduler loop, context switching, suspension pattern, async IO, sleep cancellation, work-stealing design, and performance benchmarksdocs/sync.md— synchronization primitives:FiberFuture,FiberFutex,FiberMutex,FiberSequencer,FiberEvent,FairFiberMutexdocs/util.md— utility library: lock-free data structures, TSC timing, memory pool, CPU topology, logging, assertionsdocs/perf.md—net-perfandfile-perfbenchmark results and fio comparisondocs/coroutines.md— stackless coroutines vs stackful fibers: design differences and performance datasrc/fibers/tests/— usage examples: fiber lifecycle, futures, synchronization primitives, async IOsrc/gdb/fiber.py— GDB extension; load withsource src/gdb/fiber.py, then usefiber-list,fiber-savecontext,fiber-restorecontext,fiber-switchcontext
- CMake >= 3.28
- Ninja
- Clang 21
- ccache (optional)
- Boost (
libboost-dev,libboost-context-dev,libboost-program-options-dev) - libbpf (
libbpf-dev) — optional, required only forsrc/profiler; the profiler is silently skipped if absent
GTest, Google Benchmark, libbacktrace, liburing, and librseq are bundled as submodules under contrib/ and do not need to be installed separately. Poco, the AWS SDK, and jemalloc are built on demand via --build-poco, --build-aws, and --build-jemalloc passed to configure.
Runtime dependencies for optional benchmarks: nginx (for http-perf), fio (for fio-perf), sockperf (for sockperf-perf), and MinIO (for s3-perf). MinIO is downloaded automatically to .tools/ if not in PATH; the others must be installed separately.
./bb [options] [command]
| Option | Values | Default | Description |
|---|---|---|---|
-b, --build |
debug, release |
debug |
Build type |
-s, --sanitizer |
thread, address, memory, undefined |
Enable sanitizer | |
-v, --verbose |
Print every command before running it; also passes --verbose to perf binaries to enable their debug logging |
Configure (or reconfigure) the CMake build directory. Optional flags enable components that are off by default: --build-poco enables http-perf (requires Poco), --build-aws enables s3-perf (requires the AWS SDK), --build-jemalloc enables jemalloc (used by http-perf and s3-perf to improve allocator performance).
./bb configure
./bb configure --build-poco --build-aws
./bb -b release configure
Format all source files with clang-format-21. Pass --check to verify formatting without modifying files (exits non-zero if any file would be changed).
./bb fmt
./bb fmt --check
Remove the entire build/ directory.
./bb clean
Build the project. Configures automatically if the build directory does not exist. build is the default command when none is specified.
./bb # debug build
./bb -b release # release build
./bb -s thread # debug build with TSan
./bb -b release -s address # release build with ASan
./bb build fibers-test # build a specific target
Build and run tests. Runs in parallel using all available CPUs. Any extra flags are forwarded directly to ctest.
| Flag | Description |
|---|---|
-R <pattern> |
Run only tests matching the regex pattern |
-N |
List tests without running them |
--timeout SECONDS |
Per-test timeout in seconds (default: 180, 0=none) |
--coverage |
Instrument with coverage, run tests, and generate an HTML report, an lcov file, and a Cobertura XML report under build/debug-coverage/ |
--rerun-failed |
Rerun only tests that failed in the last run |
--repeat until-fail:<n> |
Repeat each test up to n times, stopping on first failure (useful for flaky test hunting) |
--output-on-failure |
Print test output when a test fails |
./bb test
./bb test -R FiberMutex
./bb -s thread test
./bb test --rerun-failed
./bb test --coverage
Build and run benchmarks.
| Flag | Description |
|---|---|
-R <pattern> |
Run only benchmarks matching the pattern |
-N |
List benchmarks without running them |
--timeout SECONDS |
Per-benchmark timeout in seconds (default: 180, 0=none) |
./bb -b release bench
./bb -b release bench -R LockFreeQueue
Each perf command builds the relevant binary and runs the benchmark, printing results as a Markdown table. Duration, warmup, and delay options accept a unit suffix (ns, us, ms, s, m); a bare number is interpreted as seconds. All perf commands accept --timeout SECONDS (per-run timeout; default: 180, 0=none).
Async file I/O benchmark using io_uring.
| Option | Default | Description |
|---|---|---|
--file PATH |
/dev/shm/file-perf.bin |
Test file path |
--bs SIZE |
4k |
Block size |
--size SIZE |
1g |
File size |
--duration DURATION |
10 |
Measurement duration |
--warmup DURATION |
2 |
Warmup duration |
--numjobs N [N ...] |
1 |
Number of parallel jobs |
--iodepth N [N ...] |
16 |
IO queue depth per job |
--rw MODE [MODE ...] |
randread |
Access mode(s): randread, randwrite, seqread |
--flamegraph |
Profile and generate flamegraph SVG | |
--print-counters |
Print perf counters after each run |
./bb -b release file-perf
./bb -b release file-perf --bs 64k --size 4g
./bb -b release file-perf --numjobs 1 16 --iodepth 1 16
./bb -b release file-perf --rw randread randwrite
./bb -b release file-perf --flamegraph
fio comparison using io_uring engine. Same options as file-perf (except --flamegraph and --print-counters). Does not build anything.
./bb fio-perf
./bb fio-perf --bs 64k
./bb fio-perf --numjobs 1 16 --iodepth 1 16
TCP echo benchmark. Starts a local server and runs the client against it. When --host points to a remote host, the server is not started locally.
| Option | Default | Description |
|---|---|---|
--host |
127.0.0.1 |
Server host |
--port |
17777 |
Server port |
--msg-size BYTES |
64 |
Echo message size |
--duration DURATION |
10 |
Measurement duration |
--warmup DURATION |
2 |
Warmup duration |
--connections N [N ...] |
1000 |
Connection counts to sweep |
--delay DURATION |
0 |
Server-side delay per message (e.g. 1ms, 100us) |
--flamegraph |
Profile client and generate flamegraph SVG | |
--print-counters |
Print perf counters after each run |
./bb -b release net-perf
./bb -b release net-perf --connections 1 64 256 1024
./bb -b release net-perf --delay 1ms
./bb -b release net-perf --host 10.0.0.2
./bb -b release net-perf --flamegraph
TCP echo benchmark using Boost.Asio C++20 coroutines. Same options as net-perf.
./bb -b release net-perf-asio
./bb -b release net-perf-asio --connections 1 64 256 1024
./bb -b release net-perf-asio --delay 1ms
./bb -b release net-perf-asio --flamegraph
sockperf comparison (ping-pong). Same options as net-perf (except --delay, --flamegraph, and --print-counters). Does not build anything.
./bb sockperf-perf
./bb sockperf-perf --connections 1 4 16
HTTP/1.1 GET benchmark. Uses nginx as the server.
| Option | Default | Description |
|---|---|---|
--host |
127.0.0.1 |
Server host |
--port |
18080 |
Server port |
--duration DURATION |
10 |
Measurement duration |
--warmup DURATION |
2 |
Warmup duration |
--connections N [N ...] |
1000 |
Connection counts to sweep |
--delay DURATION |
0 |
Server-side delay injected via nginx lua sleep (e.g. 1ms, 100us) |
--threads |
Use thread-per-connection mode instead of fibers | |
--flamegraph |
Profile client and generate flamegraph SVG | |
--print-counters |
Print perf counters after each run |
./bb -b release http-perf
./bb -b release http-perf --threads
./bb -b release http-perf --delay 5ms
./bb -b release http-perf --connections 1 512 1024 2048
./bb -b release http-perf --flamegraph
S3 object storage benchmark. Starts a local MinIO server (downloaded automatically to .tools/ if not in PATH) and runs the client against it.
| Option | Default | Description |
|---|---|---|
--endpoint URL |
http://127.0.0.1:9000 |
S3 endpoint |
--bucket NAME |
test-bucket |
S3 bucket |
--key NAME |
test-object |
S3 object key |
--region NAME |
us-east-1 |
S3 region |
--access-key KEY |
minioadmin |
S3 access key |
--secret-key KEY |
minioadmin |
S3 secret key |
--size SIZE |
4096 |
Object size; no units = bytes (e.g. 4096, 64k, 1g) |
--duration DURATION |
10 |
Measurement duration |
--warmup DURATION |
2 |
Warmup duration |
--numjobs N [N ...] |
1 |
Number of parallel jobs |
--iodepth N [N ...] |
16 |
IO queue depth per job |
--rw MODE [MODE ...] |
read |
Access mode(s): read, write, readwrite |
--threads |
Also run with thread executor | |
--flamegraph |
Profile first config and generate flamegraph SVG | |
--print-counters |
Print perf counters after each run | |
--data-dir PATH |
/dev/shm/minio-data |
MinIO data directory |
./bb -b release s3-perf
./bb -b release s3-perf --rw read write
./bb -b release s3-perf --numjobs 1 16 --iodepth 1 64
./bb -b release s3-perf --threads
./bb -b release s3-perf --flamegraph
Run multiple perf benchmarks in one shot.
| Flag | Description |
|---|---|
--file |
Run file-perf |
--fio |
Run fio comparison |
--net |
Run net-perf |
--net-asio |
Run net-perf-asio |
--sockperf |
Run sockperf comparison |
--http |
Run http-perf (fibers) |
--http-threads |
Run http-perf (threads) |
--s3 |
Run s3-perf (fibers) |
--s3-threads |
Run s3-perf (threads) |
--all |
Run everything |
./bb -b release perf --net --file
./bb -b release perf --all