Quickstart

ForkUnion is dead-simple to use! There is no nested parallelism, exception handling, or “future promises”; they are banned. A pool runs one dispatch at a time and refuses any other with the contended status, including one from inside its own callbacks. The thread pool itself has a few core operations:

• spawn to initialize worker threads, and
• for_threads to launch a blocking callback on all threads.

Higher-level APIs for index-addressable tasks are also available:

• for_n - for individual evenly-sized tasks,
• for_n_dynamic - for individual unevenly-sized tasks,
• for_slices - for contiguous runs of evenly-sized tasks, one per worker.

For additional flow control and tuning, following helpers are available:

• nap - to park workers on the CPU’s address monitor, waking with no syscall,
• sleep(microseconds) - to block workers in the kernel for long idle periods, with 0 waiting for the next dispatch,
• terminate - to kill the threads before the destructor is called,
• unsafe_for_threads - to broadcast a callback without blocking, returning a generation token,
• unsafe_join - to block until the completion of a broadcasted generation,
• is_complete - to poll a generation token for completion without blocking.

Every dispatch is identified by a generation token. On caller_exclusive_k pools you can dispatch, overlap your own work, poll is_complete, and join - the classic poll-then-join pattern. On caller_inclusive_k pools the calling thread owes one slice of the work, which only runs inside unsafe_join, so completion can’t be reached by polling alone. The same rule shapes the RAII guard returned by for_threads and, in C++, the for_n family: the workers start at the guard’s construction on every pool, and on inclusive pools the caller’s own slice runs at join or destruction.

On caller_exclusive_k pools thread 0 may also fork from inside its own slice, at any depth: such a fork waits for every other slice of the one enclosing it, runs on all threads, and returns complete. So unsafe_for_threads can hand a whole multi-step call to thread 0, which forks the rest of the pool as it goes, while the caller only polls a status word the call stores at its end. That is how one manager thread keeps several exclusive pools busy with no queue and no extra thread. A join on such a pool waits for whatever dispatch runs, since the call may end before its submitter stores the token.

In C++ it provides NUMA extensions. That includes the colocated_pool analog of the flat_pool and the domain_allocator_t for allocating memory in a specific memory domain. Those are out-of-the-box compatible with the higher-level APIs. Most interestingly, for Big Data applications, a higher-level distributed_pool class addresses and balances the work across all compute domains.

domain_allocator_t is backed by linux_numa_allocator_t, freebsd_numa_allocator_t, or windows_numa_allocator_t.

To integrate into your Zig project, let zig fetch pin the dependency and its content hash into build.zig.zon:

zig fetch --save=forkunion https://github.com/ashvardanian/ForkUnion/archive/refs/tags/v4.0.0-rc.1.tar.gz

That records the dependency; build.zig still has to wire it, and the module carries the compiled artifact so a consumer does not relink it by hand:

const forkunion = b.dependency("forkunion", .{ .target = target, .optimize = optimize });
exe.root_module.addImport("forkunion", forkunion.module("forkunion"));

Then import and use in your code:

const std = @import("std");
const fu = @import("forkunion");

pub fn main() !void {
    const topology = try fu.Topology.init();
    defer topology.deinit();
    const pool = try fu.Pool.init(topology, .{ .threads = 4 });
    defer pool.deinit();

    // Execute work on each thread (OpenMP-style parallel)
    try pool.forThreads({}, struct {
        fn work(thread_index: usize, compute_domain: fu.ComputeDomain) void {
            _ = compute_domain;
            std.debug.print("Thread {}\n", .{thread_index});
        }
    }.work);

    // Distribute 1000 tasks across threads (OpenMP-style parallel for)
    var results = [_]i32{0} ** 1000;
    try pool.forN(1000, &results, struct {
        fn process(slots: *[1000]i32, task: usize, at: fu.ThreadInDomain) void {
            _ = at;
            slots[task] = @intCast(task * 2);
        }
    }.process);

    // Or let the pool hand each thread a disjoint sub-slice, with no index arithmetic
    try pool.forSlicesMut(i32, &results, {}, struct {
        fn scale(chunk: []i32, at: fu.ThreadInDomain) void {
            _ = at;
            for (chunk) |*slot| slot.* *= 2;
        }
    }.scale);
}

The context comes before the callback and travels as a caller-owned pointer, so the callback receives exactly the qualifiers the caller chose — the same shape std.sort uses, and the reason a std.atomic.Value in a context can never be silently copied per task. Pass {} when a kernel needs no state at all.

The Topology handle reports the hardware topology, to size and place work:

const topology = try fu.Topology.init();
defer topology.deinit();
for (0..try topology.computeDomainsCount()) |index| {
    const domain = fu.ComputeDomain.at(index);
    std.debug.print("domain {d}: {d} cores, level {d}, allocate on memory domain {d}\n", .{
        index, try topology.logicalCoresCountIn(domain), try topology.computeLevelIn(domain), (try topology.localMemoryOf(domain)).index(),
    });
}

A compute domain, a memory domain, and a memory domain’s OS id are three distinct types — ComputeDomain, MemoryDomain, and MemoryDomainId — exactly as in Rust and Mojo, so passing one where another belongs is a compile error rather than a silent read of the wrong node.

The Zig standard library no longer ships a fork-join pool at all; its replacement, std.Io.Group, allocates per task, grows its thread set lazily, runs work inline on the caller once saturated, and knows nothing about NUMA.