Silk: Open-source cooperative fiber scheduler

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

,FairFiberMutex

docs/util.md

— utility library: lock-free data structures, TSC timing, memory pool, CPU topology, logging, assertionsdocs/perf.md

—net-perf

andfile-perf

benchmark 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 headers ( libboost-dev

) - libelf ( libelf-dev

) — optional, required only forsrc/profiler

; the profiler is silently skipped if absent.

GTest, Google Benchmark, libbacktrace, liburing, librseq, libbpf, bpftool, and cxxopts are bundled as submodules under contrib/

and do not need to be installed separately. The two Boost.Context asm sources used for fiber switching are vendored under contrib/fcontext/

, and systemtap's USDT headers (<sys/sdt.h>

• <sys/sdt-config.h>

) under contrib/systemtap-sdt/

(both vendored directly, no submodule). 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 (only for http-perf --nginx

; the default uses an internal Poco-based server built into the http-perf

binary), fio (for fio-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

HTTP/1.1 GET benchmark. Defaults to silk's internal HTTP server (Poco's HTTPServerConnection

over FiberSocketImpl

, one fiber per connection); pass --nginx

to run against nginx instead.

| 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 per-request delay (e.g. 1ms , 100us ); fiber server uses `silk::Fibe