What does `--test-load` do?

The documentation for --test-load in ctest currently reads:

--test-load <level>

While running tests in parallel (e.g. with -j), try not to start tests when they may cause the CPU load to pass above a given threshold.

This then links to other docs that also basically say the same thing.

But what does this actually mean? What does <level> mean? Is it in units of percent? So if I write --test-load 60 does that mean that it will wait to start a test until some available CPU drops below 60%?

1 Like

My recollection is that this is equivalent to the -l flag for make or ninja. Those tools explain it as something like “-l N → do not start new jobs if the load average is greater than N”. I haven’t checked the implementation of --test-load for ctest, but I believe it is the same.

FWIW, this flag on its own is typically useless. At the very start of the test run, ctest would launch many tests because there’s always a lag before the load average increases. So at the start, you end up hopelessly oversubscribing the CPU. You must use --test-load in conjunction with --parallel or an equivalent.

The “load” of a machine (in POSIX at least; I’m less familiar with how it works on Windows) is generally a count of how many processes are waiting to do work. If this rises above the number of cores, it means there is more work available than the CPU can perform concurrently. Generally, you can do something like ninja -j$((2 * $(nproc))) -l$(nproc) so that you can have more I/O-bound tasks but also don’t swamp the system with CPU-bound tasks.

See this LWN article for some more details.