Performance Settings

Performance Settings

The performance section controls parallelism and how Beez spends CPU and I/O during a run.

performance = {
    max_threads = 8,
    cache_write_strategy = "phase",
    cache_fs_metadata = true,
    use_mmap_for_hashing = true,
    mmap_hashing_min_bytes = 65536,
    optimize_gc_for_throughput = false,
    pin_threads_to_cores = false,
}

max_threads

Maximum worker threads for parallel step execution and parallel workflow invocations.

Type	integer, 1 to 1024
Default	CPU core count
CLI override	-j, --threads N

beez -j 4 build

Set to 1 to force sequential execution within each parallel level.

cache_write_strategy

When Beez flushes cache data to disk.

Value	Behavior
immediate	Write cache files as soon as each entry is ready
phase	Flush at the end of each phase+scope invocation
end	Flush once at the end of the run

phase is a good default: fewer small writes, still safe if a run stops mid-phase.

cache_fs_metadata

When true, Beez caches glob expansion metadata in memory for the current run. Speeds up repeated globbing of the same patterns within one invocation.

use_mmap_for_hashing

When true, large files may be memory-mapped when computing content hashes for cache keys.

mmap_hashing_min_bytes

Minimum file size (bytes) before mmap hashing is used. Default 65536 (64 KiB).

optimize_gc_for_throughput

When true, Beez reduces Lua garbage collection during a run for higher throughput. Useful for large build.lua files with many Lua callbacks. Can increase peak memory use.

pin_threads_to_cores

When true, worker threads may be pinned to CPU cores. Behavior depends on the host OS and thread pool implementation.

Tuning tips

Situation	Suggestion
Laptop thermal throttling	Lower max_threads
CI with 2 vCPUs	max_threads = 2 in project or CI command
Huge repo, many globs	Keep cache_fs_metadata = true
Debugging race issues	beez -j 1 ...
Many small cache writes on slow disk	Try cache_write_strategy = "end"

Next steps

• Cache Settings - on-disk cache layout and compression
• Parallel Execution and Dependencies - what actually runs in parallel
• Config Reference - all keys