Building
Requirements
A C11-capable compiler (GCC, Clang, or MSVC)
CMake 3.15 or newer
POSIX threads (pthreads) on Linux/macOS, or Windows threads on Windows
Building from source
cmake -B build
cmake --build build
For a Release build (the default when Lace is the top-level project):
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
Using Lace in your project
As a subdirectory or submodule:
add_subdirectory(external/lace)
target_link_libraries(my_app PRIVATE lace::lace)
With FetchContent:
include(FetchContent)
FetchContent_Declare(lace
GIT_REPOSITORY https://github.com/trolando/lace.git
GIT_TAG |tag|
GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(lace)
target_link_libraries(my_app PRIVATE lace::lace)
With find_package (after installing):
find_package(lace |version| REQUIRED CONFIG)
target_link_libraries(my_app PRIVATE lace::lace)
A robust pattern that handles all three cases:
if(NOT TARGET lace::lace)
find_package(lace |version| CONFIG QUIET)
if(NOT lace_FOUND)
include(FetchContent)
FetchContent_Declare(lace
GIT_REPOSITORY https://github.com/trolando/lace.git
GIT_TAG |tag|
GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(lace)
endif()
endif()
This first checks if Lace is already a target (e.g. added as a submodule by a parent project), then tries to find an installed version, and finally fetches it from GitHub as a last resort.
CMake options
Option |
Description |
Default |
|---|---|---|
|
The pinning mode (Linux, FreeBSD, Windows) when neither |
AUTO |
|
Workers sleep with exponential backoff when no work is available, reducing CPU usage without affecting throughput. |
ON |
|
Optimise for the host CPU architecture ( |
ON as the top-level project, OFF as a subproject |
|
Compile with position-independent code ( |
OFF |
|
Build shared libraries instead of static. Automatically enables
|
OFF |
|
Record precise overhead times per worker (startup, steal overhead, idle search time). |
OFF |
|
Record the number of tasks executed per worker. |
OFF |
|
Record the number of steals and leaps per worker, and leap strays. |
OFF |
|
Record the number of deque split-point adjustments per worker. |
OFF |
|
Keep the compiler’s default stack protector and stack clash
protection in Lace’s own code. When OFF, the library and the
benchmarks are built with |
OFF |
|
Default worker stacks to the calling thread’s stack limit, clamped
to 16-64 MB, instead of reserving 1 GB of address space per worker.
For systems with strict overcommit accounting
( |
OFF |
The following options are only available when Lace is the top-level project:
Option |
Description |
Default |
|---|---|---|
|
Build the test suite (disabled when used as a subproject) |
ON |
|
Build the benchmark programs (disabled when used as a subproject) |
ON |
|
Build the documentation (disabled when used as a subproject) |
OFF |
|
Build with AddressSanitizer to detect memory errors. For development and testing only. |
OFF |
|
Build with ThreadSanitizer to detect data races. For development and testing only. |
OFF |
|
Build with UndefinedBehaviorSanitizer to detect undefined behaviour. For development and testing only. |
OFF |
Configuration recommendations
Keep LACE_BACKOFF on. Benchmarks show that backoff does not affect throughput, but it prevents idle workers from consuming 100% CPU when there is no work. There is no reason to turn this off unless you are doing very precise micro-benchmarking of steal overhead.
Keep LACE_DEFAULT_PIN at AUTO. Pinned workers stay on their core and keep their caches warm; in benchmarks on Intel and AMD machines with one, two and four sockets, unpinned workers were 2-13% slower. The default mode leaves cores to other programs when Lace does not use all of them (see Worker pinning).
Use LACE_NATIVE_OPT for local benchmarking but not for portable or
distributed builds, since -march=native produces binaries tied to the
build machine’s CPU.
Compare timings only between builds with the same statistics options.
The LACE_PIE_TIMES, LACE_COUNT_TASKS, LACE_COUNT_STEALS, and
LACE_COUNT_SPLITS options cost about 1% or less in the benchmarks (see
Scheduling Experiments (2026)), but they change the code layout, which can
move a single program by several percent.
Hardening defaults cost time in task code. Many distributions configure
GCC to add a stack protector and stack clash protection by default. These
guard against attacks through untrusted input, which a work-stealing
scheduler does not handle, so Lace turns both off in its own targets
(LACE_HARDENING). Your program keeps its own flags, also for the code
that the task macros put in your functions; to turn them off there too, add
for example:
target_compile_options(myprog PRIVATE -fno-stack-protector -fno-stack-clash-protection)
-fcf-protection stays on: mixing objects with and without it drops the
CET marking of the whole program.
Sanitiser options are mutually exclusive. AddressSanitizer and ThreadSanitizer cannot be combined. Use them individually during development.
Worker pinning
On Linux, FreeBSD and Windows, Lace pins its workers within the affinity mask
of the thread that calls lace_start(), as taskset, cgroups or a job
scheduler such as SLURM set it; on Windows, within the processor group of that
thread. Lace never pins to CPUs outside that mask. The mode says what
each worker may run on:
Mode |
Each worker may run on |
|---|---|
|
The default: |
|
One hardware thread, taking one of every physical core before any second hardware thread of a core. |
|
One physical core (its hardware threads). |
|
The cores that share an L2 cache, an L3 cache (a chiplet, or a socket) or a NUMA node. The workers are spread over these groups in proportion to their number of cores. |
|
Any physical core of the mask, one hardware thread per core. |
|
Any CPU of the mask (no pinning). |
With more workers than places (hardware threads for LACE_PIN_CPU, cores
for the other modes), Lace does not pin.
A program chooses the mode with lace_set_pinning(), or pins worker i to
cpus[i % n] with lace_set_pin_cpus(cpus, n), before lace_start():
lace_set_pinning(LACE_PIN_L3);
lace_start(0, 0, 0);
If the program does not choose, the environment variable LACE_PIN does:
off, auto, cpu, core, l2, l3, numa, all, or a
CPU list such as list:0,2,4-7. LACE_PIN_PRINT=1 prints the CPUs of every
worker. On other systems (macOS) these calls have no effect.
With lace_start_external (Your own threads), Lace pins the program’s threads
only when the program chooses a mode or LACE_PIN is set; the default mode
is then off, whatever LACE_DEFAULT_PIN says.
Installing
cmake -B build -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build build
cmake --install build
This installs libraries, headers, CMake config files, and pkg-config
.pc files. After installation, other projects can use find_package(lace)
or pkg-config --cflags --libs lace.