Lifecycle
-
enum lace_pin_mode
Pinning modes for lace_set_pinning().
Values:
-
enumerator LACE_PIN_OFF
-
enumerator LACE_PIN_AUTO
-
enumerator LACE_PIN_ALL
-
enumerator LACE_PIN_CPU
-
enumerator LACE_PIN_L3
-
enumerator LACE_PIN_NUMA
-
enumerator LACE_PIN_CORE
-
enumerator LACE_PIN_L2
-
enumerator LACE_PIN_OFF
-
enum lace_idle_mode
Idle modes for lace_set_idle_mode().
Values:
-
enumerator LACE_IDLE_BALANCED
-
enumerator LACE_IDLE_ENERGY
-
enumerator LACE_IDLE_PERFORMANCE
-
enumerator LACE_IDLE_BALANCED
-
void lace_start(unsigned int n_workers, size_t dqsize, size_t stacksize)
Start Lace and spawn worker threads.
Allocates per-worker deques and launches
n_workersthreads. Workers look for tasks immediately. With LACE_BACKOFF (the default), idle workers soon sleep, and an idle Lace uses almost no CPU; lace_set_idle_mode() chooses how soon.Deques are allocated as virtual memory and physical pages are committed lazily, so a large
dqsizehas no upfront memory cost.On Linux, FreeBSD and Windows, workers are pinned as lace_set_pinning() chooses (by default LACE_PIN_AUTO).
See also
- Parameters:
n_workers – Number of worker threads. Pass 0 to auto-detect available cores.
dqsize – Task deque size per worker (number of task slots). Pass 0 for a default of 100 000. Each live SPAWN that has not yet been SYNCed occupies one slot.
stacksize – Worker thread stack size in bytes, at least 16 MB. Pass 0 for the default: a 1 GB reservation on 64-bit systems where stack pages are committed on first touch (not with LACE_DONT_OVERCOMMIT, not on Windows except MSVC), otherwise the calling thread’s stack limit clamped to 16-64 MB. If the 1 GB stacks cannot be reserved (for example under ulimit -v), Lace falls back to the latter.
-
void lace_start_external(unsigned int n_workers, size_t dqsize)
Start Lace on threads that the program creates itself.
Like lace_start, but Lace creates no threads: the program brings
n_workersthreads, for example from a runtime that creates its threads itself, and each becomes a worker with lace_worker_enter. The threads may already run, but each enters only after this call has returned, for example after a barrier of the program, or by creating the threads afterwards. A thread that only works then calls lace_worker_loop; a thread that generates the tasks runs them directly after lace_worker_enter, and only steals while it waits at a SYNC (leapfrogging). Every thread ends with lace_worker_leave, and then one of them, or another thread, calls lace_stop.The threads use their own stacks, so deep task trees need large thread stacks. Lace pins them only when the program asks, with lace_set_pinning, lace_set_pin_cpus or the LACE_PIN environment variable, before this call; LACE_DEFAULT_PIN does not apply. lace_worker_leave gives a thread its affinity back.
See also
lace_worker_enter, lace_worker_loop, lace_worker_leave, lace_stop
- Parameters:
n_workers – Number of threads that will enter. Pass 0 for one per available CPU (see lace_worker_count).
dqsize – Task deque size per worker. Pass 0 for the default.
-
void lace_worker_enter(unsigned int worker)
Make the calling thread Lace worker
worker, after lace_start_external has returned (the calling thread must be synchronised with that call, for example by a barrier, or created after it).Returns once all n_workers threads have entered: the workers start together.
Each worker id from 0 to n_workers-1 is entered by one thread per run. A worker that does not call lace_worker_loop runs tasks directly, for example the root of the computation. Until it leaves, every worker takes part in TOGETHER and NEWFRAME, which wait for all workers, so between tasks such a thread should not do long work outside Lace; while it is a worker, idle workers also stay ready to steal its tasks.
-
void lace_worker_loop(void)
Steal and run tasks until lace_stop.
Called by a worker (lace_worker_enter) that only works; returns when Lace stops.
-
void lace_worker_leave(void)
The calling thread stops being a Lace worker; it gets its affinity back.
Not from inside a task. Every worker leaves before lace_stop returns.
-
void lace_stop(void)
Stop all workers and free resources.
Must be called from a thread that is not a Lace worker (or has left with lace_worker_leave), never from inside a task. With lace_start_external, it makes every lace_worker_loop return and waits until all workers have left; the program then joins its own threads. Afterwards Lace can be started again, also with other threads as the workers. Do not call from a signal handler.
See also
-
void lace_release_memory(void)
Give the memory that idle workers hold back to the operating system.
A deep computation leaves physical pages behind in the worker stacks, task deques and scratch arenas, and they stay resident until lace_stop(). This makes every worker, at its next idle moment, release the pages of its stack below its idle loop, of its deque past the first page, and of its scratch arena past the first band. The reservations stay, so later work just faults pages in again. Returns when all workers are done, so it waits for running tasks to finish.
Must be called from a thread that is not a Lace worker; it returns at once otherwise. On Windows only the scratch arenas are released.
-
int lace_is_running(void)
Check whether the Lace runtime is currently active.
- Returns:
1 if Lace is running, 0 otherwise
-
void lace_set_verbosity(int level)
Set the verbosity level for Lace startup messages.
Call before lace_start(). Level 0 (default) suppresses output; level 1 prints startup diagnostics.
- Parameters:
level – Verbosity level (0 = silent, 1 = verbose)
-
void lace_set_pinning(lace_pin_mode mode)
Choose what each worker may run on, within the affinity mask of the thread that calls lace_start() (as taskset, cgroups or a job scheduler set it).
LACE_PIN_AUTO (the default): LACE_PIN_CPU if the workers fill the cores of the mask, else LACE_PIN_ALL. A program with as many workers as cores owns them, and one CPU per worker is fastest; one that leaves cores free may share the machine, and pinning to fixed CPUs would make two such programs share the same cores.
LACE_PIN_CPU: one hardware thread per worker, one of every physical core before any second hardware thread of a core.
LACE_PIN_CORE: one physical core per worker (its hardware threads).
LACE_PIN_L2, LACE_PIN_L3, LACE_PIN_NUMA: the cores that share an L2 cache, an L3 cache or a NUMA node. The workers are spread over these groups in proportion to their number of cores.
LACE_PIN_ALL: any physical core of the mask, one hardware thread each.
LACE_PIN_OFF: no pinning.
With more workers than places (hardware threads for LACE_PIN_CPU, cores otherwise) Lace does not pin. Without this call, the environment variable LACE_PIN chooses: off, auto, all, cpu, core, l2, l3, numa, or list:CPUS for worker i on the i-th CPU of a list such as list:0,2,4-7 (see lace_set_pin_cpus). Linux, FreeBSD and Windows only (macOS does not pin). Call before lace_start().
See also
- Parameters:
mode – The pinning mode (default LACE_PIN_AUTO)
-
void lace_set_pin_cpus(const int *cpus, unsigned int n)
Pin worker i to cpus[i % n] (manual pinning).
CPUs outside the affinity mask are left out. Overrides lace_set_pinning() and LACE_PIN; n = 0 undoes it. Call before lace_start().
See also
- Parameters:
cpus – CPU numbers
n – Number of entries in
cpus
-
void lace_set_idle_mode(lace_idle_mode mode)
Choose how long idle workers look for work before they sleep: CPU time (energy) against how fast work is picked up after a gap.
An idle worker searches while its search balance lasts: searching spends it, and work the worker finds earns it more. Then it sleeps until work appears. While some worker runs a task, a few idle workers (sentinels) stay awake at a small fraction of a core, to wake the others.
LACE_IDLE_BALANCED (the default): each microsecond of work earns 8 of search, so busy workers search through gaps of up to about 1 ms; two sentinels; for 20 ms after it worked, a sleeping worker wakes up every 100 us, so its core stays ready for the next parallel region.
LACE_IDLE_ENERGY: less CPU time for somewhat slower work after gaps. Work earns 4 times its time, up to 16 us of search per other worker (at most the balanced cap of 1 ms), about the cost of waking them all again; one sentinel; sleeping workers back off at once.
LACE_IDLE_PERFORMANCE: the fastest response, for more CPU time while there is little work. Work earns 64 times its time, so workers search through gaps of up to 10 ms and their cores stay warm; two sentinels and the 20 ms of short naps, as balanced.
Without this call, the environment variable LACE_IDLE chooses: energy, balanced or performance. Call before lace_start() or lace_start_external().
- Parameters:
mode – The idle mode (default LACE_IDLE_BALANCED)
-
void lace_set_scratch_size(size_t size)
Configure the per-worker scratch arena reservation size.
Call before lace_start(). Each worker reserves this many bytes of virtual address space for its private scratch arena. No physical memory is committed until the first allocation in the arena. The default is 1 GiB per worker on 64-bit systems and 16 MiB per worker on 32-bit systems, since on 32-bit user address space is limited. If the 64-bit default cannot be reserved (for example under ulimit -v), Lace falls back to 16 MiB. A size set here is used as given: if it cannot be reserved, lace_start() exits with an error.
Pass 0 to disable the scratch arena entirely.
See also
- Parameters:
size – Virtual reservation per worker in bytes
-
void lace_set_scratch_band(size_t size)
Configure the per-worker scratch committed band.
Call before lace_start(). The band is the number of extra bytes kept committed above the current allocation top, providing hysteresis so that small allocations and deallocations near the top do not trigger commit/decommit syscalls. Rounded up to a page-size multiple.
The default band is 1 MiB. A larger band absorbs more push/pop oscillation; a smaller band releases pages back to the OS sooner after a deep operation.
See also
- Parameters:
size – Committed band per worker in bytes (default 1 MiB)