Quickstart

Success is 0; every failure is negative, so status < 0 and status != fu_success_k agree. Values are fixed and portable, so a binding may hard-code them.

Some enumerators name failures the core never returns itself: a binding that rejects a call before it crosses reports the same status the core would if it could see the same thing.

Statuses fall into four categories, with no interruptions to report. Resources: fu_bad_alloc_k, fu_thread_refused_k, fu_topology_unavailable_k, fu_permission_denied_k, fu_library_missing_k and fu_symbol_missing_k. Input: fu_invalid_argument_k. State: fu_capacity_exhausted_k, fu_config_mismatch_k, fu_already_spawned_k, fu_not_spawned_k, fu_unsupported_k and fu_contended_k. Defects: fu_unknown_k. Any verb that allocates, binds a device or touches a file may also return a Resources status. A verb's own block lists only what its contract adds.

This enum affects how the join is performed. If the caller is inclusive, 1/Nth of the work runs on the calling thread, and the join happens in its own scope.

One bit per facility, and two accessors ask two questions of the same bit. fu_comptime_capabilities reports whether the code was built: a set fu_capability_place_huge_pages_on_domain_k means we compiled the path that asks for them. fu_runtime_capabilities reports whether the machine offers it now.

Neither implies the other. A binary that built fu_capability_place_memory_on_domain_k runs perfectly well on a single-node box, where the runtime accessor never sets that bit; and a machine with four NUMA nodes reports none of them to a build that left the topology out.

Every generation advances the pool's internal epoch by exactly two: once at dispatch and once when the last contributor finishes. Odd epochs are in-flight, even are idle.

Never returns NULL, never allocates.

The waiter, and whether a spawn spans domains, come from fu_runtime_capabilities() & allowed, so clearing bits forces a lesser waiter or the flat non-NUMA pool - handy for benchmarking. Creation takes no topology: placement is decided at spawn, where you hand over the fu_topology_t. The pool starts empty; call fu_pool_spawn before use.

Covers every compute domain. If a prior fu_pool_spawn_on left the pool pinned to a single domain, this rebuilds it as a whole-machine pool before spawning. The call returns once every worker has started.

Placement lives here, not in creation: fu_pool_new allocates the handle, and this binds it to a single compute domain, so its workers and their memory-domain-local allocations stay on that domain. Spawn one pool per compute domain and coordinate them with the generation-token API; fu_pool_spawn instead spans all compute domains. Without NUMA, only compute domain 0 is valid. It returns once every worker started pinned to compute_domain_index.

On inclusive pools the caller's slice runs only inside fu_pool_unsafe_join, so fu_pool_is_complete cannot be reached by polling alone.

The count is the one fu_pool_spawn received.

Workers stay on their cores and wake with no syscall of their own. Without a monitor they keep spinning on a hint. With enough privileges on Linux and FreeBSD they also drop to the idle scheduling class, and on Linux under schedutil to a lower frequency.

Workers leave their cores, at the price of syscalls in the next dispatch. Same as fu_pool_nap where the kernel can't wait on a word, which is Apple's case.

Joins every worker and releases their resources; call fu_pool_spawn again, e.g. to change the thread count. Use fu_pool_delete for permanent teardown.

The callback receives context, its thread index in [0, threads_count), and the compute_domain - the NUMA node and QoS level - it runs on.

void hello(void *ctx, size_t thread, size_t compute_domain) {
    printf("Hello from thread %zu on compute_domain %zu\n", thread, compute_domain);
}
if (fu_pool_for_threads(pool, hello, NULL) != fu_success_k) return; // ! Never spawned, or busy

One contiguous range per worker - ideal for vectorized or per-slice-setup work where sequential access matters, since each worker touches its data in order and only sets up once. Every worker is called exactly once, an idle one with count == 0. The callback receives context, the run's first index, count of tasks, thread index, and compute_domain.

void normalize(void *array, size_t first, size_t count, size_t thread, size_t compute_domain) {
    float *data = (float *)array;
    for (size_t i = first; i != first + count; ++i) data[i] = sqrtf(data[i]); // One sequential sweep
}
if (fu_pool_for_slices(pool, length, normalize, values) != fu_success_k) return; // ! Never spawned, or busy

Tasks split into equal contiguous chunks per worker, keeping coordination near zero - the right choice when tasks cost about the same, so a static split stays balanced. The callback receives context, the task index in [0, n), the thread index, and compute_domain.

void double_each(void *array, size_t i, size_t thread, size_t compute_domain) {
    int *data = (int *)array;
    data[i] = data[i] * 2; // Uniform O(1) work per index
}
if (fu_pool_for_n(pool, length, double_each, array) != fu_success_k) return; // ! Never spawned, or busy

Each worker starts with one task, then claims more from a shared cursor as it finishes, so fast workers absorb the slack and one slow task never stalls the rest - the right choice when task cost is unpredictable or data-dependent. Same callback shape as fu_pool_for_n, but task order is not deterministic.

void variable_work(void *ctx, size_t task, size_t thread, size_t compute_domain) {
    complex_computation(task); // May take 1us or 1ms
}
if (fu_pool_for_n_dynamic(pool, count, variable_work, ctx) != fu_success_k) return; // ! Never spawned, or busy

On inclusive pools the caller's own slice runs inside fu_pool_unsafe_join, so the pool cannot complete until the caller joins.

fu_generation_t generation;
if (fu_pool_unsafe_for_threads(pool, callback, context, &generation) != fu_success_k) return;
prepare_next_batch();
fu_pool_unsafe_join(pool, generation);

The synchronization point for the non-blocking API: on return every contributor is done, their writes are visible, and the pool is ready for the next dispatch. Idempotent on a stale or already-joined generation.

fu_generation_t generation;
fu_bool_t complete = 0;
if (fu_pool_unsafe_for_threads(pool, callback, context, &generation) != fu_success_k) return;
while (!complete && fu_pool_is_complete(pool, generation, &complete) == fu_success_k)
    do_other_work(); // ! Exclusive pools only
fu_pool_unsafe_join(pool, generation);