Lifecycle

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_workers threads. Workers begin busy-waiting for tasks immediately. If LACE_BACKOFF is enabled (the default), CPU usage drops to near zero after roughly one second of inactivity.

Deques are allocated as virtual memory and physical pages are committed lazily, so a large dqsize has no upfront memory cost.

When LACE_USE_HWLOC is enabled, worker threads are pinned to CPU cores.

See also

lace_stop

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. Pass 0 for the minimum of 16 MB and the calling thread’s stack size.

void lace_stop(void)

Stop all workers and free resources.

Must be called from a thread that is not a Lace worker. Do not call from a signal handler.

See also

lace_start

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_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.

Pass 0 to disable the scratch arena entirely.

See also

lace_set_scratch_band, lace_scratch_alloc

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

lace_set_scratch_size, lace_scratch_alloc

Parameters:

size – Committed band per worker in bytes (default 1 MiB)