# Quickstart

> ForkUnion for Mojo

__`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](https://www.unum.cloud/docs/forkunion/mojo/numa.md).
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 Mojo project, let Pixi build the package from source — there is no channel to add and no linker flag to pass:

```toml
[workspace]
preview = ["pixi-build"]

[dependencies]
forkunion = {git = "https://github.com/ashvardanian/ForkUnion", tag = "v4.0.0-rc.1"}
```

Vendoring works too and needs no manifest: Mojo resolves a source package ahead of a compiled one, so `mojo run -I <path-to>/mojo` is enough once `libforkunion.so` is on the loader path.

Then import and use in your code:

```mojo
from forkunion import ComputeDomain, Library, Pool, SyncMutPointer, TasksRange, ThreadInDomain, Topology

@fieldwise_init
struct Output(ImplicitlyCopyable, TrivialRegisterPassable):
    """The output array every kernel below writes into."""

    var values: SyncMutPointer[Int64]

def double(task: Int, at: ThreadInDomain, mut output: Output):
    output.values.at(task) = Int64(task * 2)

def announce(thread_index: Int, compute_domain_index: Int, mut output: Output):
    print(t"thread {thread_index} on compute domain {compute_domain_index}")

def sweep(tasks: TasksRange, at: ThreadInDomain, mut output: Output):
    for task in tasks:
        output.values.at(task) += 1

def main() raises:
    var library = Library()
    var topology = Topology(library)
    var pool = Pool(topology, threads=4, name="demo")

    var results = List[Int64](length=1000, fill=0)
    var output = Output(SyncMutPointer(results.unsafe_ptr().unsafe_origin_cast[MutUntrackedOrigin]()))

    pool.for_threads[announce](output)          # once per worker, OpenMP-style parallel
    pool.for_n[double](1000, output)            # evenly split, OpenMP-style parallel for
    pool.for_n_dynamic[double](1000, output)    # claimed as threads free up, for uneven work
    pool.for_slices[sweep](1000, output)        # one contiguous run per worker
    print(t"results[7] = {results[7]}")         # 15: doubled to 14, then swept once
```

The callback is a compile-time parameter and the state it needs is a separate runtime argument.
Mojo cannot hand a capturing closure to C at all, so a callback carries no captures — the scratch is the only channel, and its type and origin are inferred from the argument, leaving a call site to name only the work.
Fallible calls raise `Error` and nothing else, and a call raises if and only if it can fail - a refusal is never folded into an `Optional` the caller has to interpret.

The non-blocking dispatch is a context manager, so the join cannot be forgotten and the pool cannot be torn down while its workers are still running:

```mojo
with pool.unsafe_for_threads[work](scratch) as dispatch:
    while not dispatch.is_complete(): # exclusive pools only
        prepare_next_batch()
```

The `Topology` handle reports the [hardware topology](https://www.unum.cloud/docs/forkunion/mojo/topology.md), to size and place work:

```mojo
var topology = Topology(library)
for index in range(topology.compute_domains_count()):
    var domain = ComputeDomain(index)
    var cores = topology.logical_cores_count_in(domain)
    var level = topology.compute_level_in(domain)
    print(t"domain {index}: {cores} cores, level {level}, allocate on {topology.local_memory_of(domain)}")
```

Handles release themselves, so there is no `defer` to forget — though Mojo destroys a value after its __last use__ rather than at the end of the scope, which is earlier than a Zig `defer` fires.

Unlike `max.algorithm.parallelize`, which takes every hardware thread and offers no way to ask for fewer, ForkUnion's pool width is an argument.
On a machine you are sharing, that is the difference between a speedup and a slowdown.

`from forkunion import Library, Pool, BroadcastJoin, …`

## Library

A reference to the loaded core, cheap to copy and shared by everything it creates.

```mojo
struct Library
```

Every handle carries one, which is what keeps the symbols resolved for as long as anything can
still call into them. It is a loader reference, not a topology reference - the C API is
explicit that a pool never retains the topology it spawned from.

- `shared` `ArcPointer[_Loaded]`: The handle and its symbols, refcounted so the last holder closes the handle.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`

## __init__

Opens the shared object and resolves it, which every handle then shares.

```mojo
def __init__(out self)
```

Raises: With [`LIBRARY_MISSING`](#LIBRARY_MISSING), when nothing is on the loader path or its major version differs.

## symbols

The resolved entry points, borrowed rather than copied on every call.

```mojo
def symbols(self) -> ref[self.shared.symbols] Symbols
```

## version

The loaded library's own version, which is also the cheapest check that loading worked.

```mojo
def version(self) -> Tuple[Int, Int, Int]
```

## Pool

A spawned pool. Released when the last reference to it goes out of use.

```mojo
struct Pool
```

Every query re-asks the C core rather than caching, so the answers stay correct across a
[`terminate`](#terminate) followed by a fresh spawn with a different width or exclusivity.

- `library` `Library`: The loaded core, held so its symbol table outlives every call made through the handle.
- `handle` `Pointer[NoneType, MutUntrackedOrigin]`: The opaque `fu_pool_t` every call below hands back to the core.

Conforms to: `Deinitable`, `Movable`

## __init__

Spawns `threads` workers across the whole machine.

```mojo
def __init__(
    out self,
    topology: Topology,
    threads: Int,
    exclusivity: CallerExclusivity = CallerExclusivity.INCLUSIVE,
    name: StringSpan[ImmStaticOrigin] = StringSpan(""),
    allowed: Capabilities = Capabilities.ALL
)
```

```mojo
def __init__(out self, *, library: Library, handle: Pointer[NoneType, MutUntrackedOrigin])
```

Adopts a handle that is already spawned, which is how [`on`](#on) hands one back.

- `topology`: The machine description; read only during this call, and freeable afterwards.
- `threads`: Worker count above zero, counting the caller itself on an inclusive pool.
- `exclusivity`: Whether the dispatching thread runs a slice or only coordinates.
- `name`: What the workers answer to in a debugger; an empty name leaves them unnamed.
- `allowed`: The spin hints and placement facilities the spawn may pick from, before masking.
- `library`: The loaded core the handle was created through, and is deleted through.
- `handle`: An `fu_pool_t` whose lifetime this pool takes over.

Raises: [`Error`](#Error) if the pool cannot be allocated, is already spawned, or the OS refuses the threads.

## __deinit__

Stops the workers before freeing the pool, so nothing is still running at the delete.

```mojo
def __deinit__(deinit self)
```

## on

Spawns `threads` workers pinned to one compute domain.

```mojo
def on(
    topology: Topology,
    domain: ComputeDomain,
    threads: Int,
    exclusivity: CallerExclusivity = CallerExclusivity.INCLUSIVE,
    name: StringSpan[ImmStaticOrigin] = StringSpan(""),
    allowed: Capabilities = Capabilities.ALL
) -> Self
```

- `topology`: The machine description; read only during this call, and freeable afterwards.
- `domain`: The one domain the workers and their domain-local allocations stay on.
- `threads`: Worker count above zero, counting the caller itself on an inclusive pool.
- `exclusivity`: Whether the dispatching thread runs a slice or only coordinates.
- `name`: What the workers answer to in a debugger; an empty name leaves them unnamed.
- `allowed`: The spin hints and placement facilities the spawn may pick from, before masking.

Raises: [`Error`](#Error) if the domain is out of range, the pool is already spawned, or the OS refuses the threads.

## threads_count

Workers in the pool, including the caller on an inclusive pool.

```mojo
def threads_count(self) -> Int
```

Raises: [`Error`](#Error) if the pool was never spawned.

## threads_count_in

Workers the pool placed in one compute domain.

```mojo
def threads_count_in(self, domain: ComputeDomain) -> Int
```

- `domain`: A dense compute-domain index, below [`compute_domains_count`](https://www.unum.cloud/docs/forkunion/mojo/topology.md#compute_domains_count) and not bounds-checked.

Raises: [`Error`](#Error) if the pool was never spawned.

## compute_domains_count

Compute domains this pool spans, which may be fewer than the machine's.

```mojo
def compute_domains_count(self) -> Int
```

Raises: [`Error`](#Error) if the pool was never spawned.

## locate_thread_in

A global thread index expressed as a local one inside a compute domain.

```mojo
def locate_thread_in(self, global_thread_index: Int, domain: ComputeDomain) -> Int
```

- `global_thread_index`: A thread index as a dispatch reports it, spanning the whole pool.
- `domain`: The domain to rebase into, below [`compute_domains_count`](https://www.unum.cloud/docs/forkunion/mojo/topology.md#compute_domains_count) and not bounds-checked.

Raises: [`Error`](#Error) if the pool was never spawned.

## caller_exclusivity

Queried live, so it stays correct across a terminate and a re-spawn.

```mojo
def caller_exclusivity(self) -> CallerExclusivity
```

Raises: [`Error`](#Error) if the pool was never spawned.

## capabilities

The requested allow-mask narrowed by what the machine offers; masking never adds.

```mojo
def capabilities(self) -> Capabilities
```

Raises: [`Error`](#Error) if the pool was never spawned.

## nap

Parks the workers on the CPU's address monitor; the next dispatch wakes them.

```mojo
def nap(self)
```

Not thread-safe: call it between task batches, never during a dispatch.

## sleep

Blocks the workers in the kernel; the next dispatch wakes them.

```mojo
def sleep(self, microseconds: Int = Int(0))
```

Not thread-safe: call it between task batches, never during a dispatch.

- `microseconds`: The longest a worker stays blocked before re-checking; 0 means no limit.

## terminate

Stops the workers but keeps the handle, so the pool can be spawned again.

```mojo
def terminate(self)
```

Not thread-safe: call it only when no dispatch is in flight, never as a sync point.

## for_threads

One call per worker, which is where per-thread scratch is set up or torn down.

```mojo
def for_threads[Scratch: AnyType, scratch_origin: MutOrigin, //, work: def(Int, Int, mut Scratch) thin -> None](
    self,
    ref[scratch_origin] scratch: Scratch
)
```

The callback takes the thread and compute-domain indices; the C API supplies no task index
here, so none is invented.

- `Scratch` (comptime): The scratch type, inferred from the argument.
- `scratch_origin` (comptime): The scratch's origin, inferred with it.
- `work` (comptime): The callback, taking a pool-wide thread index, a compute-domain index, and the scratch.
- `scratch`: The state the callback reads and writes, borrowed for the whole call.

Raises: [`Error`](#Error) if the pool was never spawned, or the core refuses the dispatch.

## for_n

Splits `n` tasks into equal contiguous chunks and blocks until every one has finished.

```mojo
def for_n[Scratch: AnyType, scratch_origin: MutOrigin, //, work: def(Int, ThreadInDomain, mut Scratch) thin -> None](
    self,
    n: Int,
    ref[scratch_origin] scratch: Scratch
)
```

- `Scratch` (comptime): The scratch type, inferred from the argument.
- `scratch_origin` (comptime): The scratch's origin, inferred with it.
- `work` (comptime): The callback, taking a task index, a [`ThreadInDomain`](https://www.unum.cloud/docs/forkunion/mojo/topology.md#ThreadInDomain), and the scratch.
- `n`: How many tasks to split across the pool, one callback invocation each.
- `scratch`: The state the callback reads and writes, borrowed for the whole call.

Raises: [`Error`](#Error) if the pool was never spawned, or the core refuses the dispatch.

## for_n_dynamic

The same, but tasks are claimed as threads free up, for work of uneven cost.

```mojo
def for_n_dynamic[Scratch: AnyType, scratch_origin: MutOrigin, //, work: def(Int, ThreadInDomain, mut Scratch) thin -> None](
    self,
    n: Int,
    ref[scratch_origin] scratch: Scratch
)
```

- `Scratch` (comptime): The scratch type, inferred from the argument.
- `scratch_origin` (comptime): The scratch's origin, inferred with it.
- `work` (comptime): The callback, taking a task index, a [`ThreadInDomain`](https://www.unum.cloud/docs/forkunion/mojo/topology.md#ThreadInDomain), and the scratch.
- `n`: How many tasks to hand out, no worker taking a second before it finishes its first.
- `scratch`: The state the callback reads and writes, borrowed for the whole call.

Raises: [`Error`](#Error) if the pool was never spawned, or the core refuses the dispatch.

## for_slices

One contiguous run per worker, for vectorized or per-slice-setup work.

```mojo
def for_slices[Scratch: AnyType, scratch_origin: MutOrigin, //, work: def(TasksRange, ThreadInDomain, mut Scratch) thin -> None](
    self,
    n: Int,
    ref[scratch_origin] scratch: Scratch
)
```

Every worker is called exactly once; an idle one receives a range with `count == 0`.

- `Scratch` (comptime): The scratch type, inferred from the argument.
- `scratch_origin` (comptime): The scratch's origin, inferred with it.
- `work` (comptime): The callback, taking a [`TasksRange`](#TasksRange), a [`ThreadInDomain`](https://www.unum.cloud/docs/forkunion/mojo/topology.md#ThreadInDomain), and the scratch.
- `n`: How many tasks to divide into one run per worker, however few workers there are.
- `scratch`: The state the callback reads and writes, borrowed for the whole call.

Raises: [`Error`](#Error) if the pool was never spawned, or the core refuses the dispatch.

## unsafe_for_threads

Dispatches on every worker without blocking, returning a guard that joins on exit.

```mojo
def unsafe_for_threads[Scratch: AnyType, pool_origin: ImmOrigin, scratch_origin: MutOrigin, //, work: def(Int, Int, mut Scratch) thin -> None](
    ref[pool_origin] self,
    ref[scratch_origin] scratch: Scratch
) -> BroadcastJoin[pool_origin, scratch_origin]
```

Use it as a context manager. The workers start here; on an inclusive pool the caller owes
its own slice, which runs at the join, so only an exclusive pool can be polled before it.

- `Scratch` (comptime): The scratch type, inferred from the argument.
- `pool_origin` (comptime): This pool's borrow, inferred from `self` and carried on into the guard.
- `scratch_origin` (comptime): The scratch's origin, inferred with the scratch and carried on too.
- `work` (comptime): The callback, taking a pool-wide thread index, a compute-domain index, and the scratch.
- `scratch`: The state the callback reads and writes, borrowed until the join rather than the return.

Raises: [`Error`](#Error) if the pool was never spawned, or the core refuses the dispatch.

## BroadcastJoin

One in-flight generation, joined when the `with` block ends.

```mojo
struct BroadcastJoin[pool_origin: ImmOrigin, scratch_origin: MutOrigin]
```

Both origins are load-bearing, because Mojo destroys a value after its last named use and the
dispatch outlives that point.

- `pool_origin` (comptime): The pool's borrow, without which it would be torn down while its workers were still running - and a [`terminate`](#terminate) mid-flight trips an assertion inside the core.
- `scratch_origin` (comptime): The scratch's borrow, keeping the storage the workers write through alive until the join, which a raw context pointer cannot express.

- `pool` `Pointer[Pool, pool_origin]`: The dispatching pool, reached at the join and at every poll.
- `generation` `Int`: The token the core stamped on this dispatch, which the poll and the join both name.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`

## __enter__

Hands back the guard itself, so the block can poll as well as read the generation.

```mojo
def __enter__(self) -> Self
```

## __exit__

Joins the generation, running the caller's own slice first on an inclusive pool.

```mojo
def __exit__(mut self)
```

## is_complete

A non-blocking poll; meaningful on exclusive pools, where the caller owes no slice.

```mojo
def is_complete(self) -> Bool
```

Raises: [`Error`](#Error) if the pool was never spawned.

## ErrorKind

Why a call into the C core failed.

```mojo
struct ErrorKind
```

- `SUCCESS` = `ErrorKind(Int32(0))`: The call completed.
- `UNKNOWN` = `ErrorKind(Int32(-1))`: No reason was reported, or one this build does not name.
- `BAD_ALLOC` = `ErrorKind(Int32(-2))`: An allocation or mapping failed; a smaller request may succeed.
- `CAPACITY_EXHAUSTED` = `ErrorKind(Int32(-3))`: A fixed ceiling was reached, so a smaller request will not help either.
- `INVALID_ARGUMENT` = `ErrorKind(Int32(-4))`: An argument was malformed, out of range, or would overflow a byte count.
- `CONFIG_MISMATCH` = `ErrorKind(Int32(-5))`: The handles or the pool kind cannot serve this call together.
- `ALREADY_SPAWNED` = `ErrorKind(Int32(-6))`: The pool is already spawned; terminate it first.
- `NOT_SPAWNED` = `ErrorKind(Int32(-7))`: The pool was never spawned.
- `THREAD_REFUSED` = `ErrorKind(Int32(-8))`: The OS declined to create a thread - a resource limit, or permissions.
- `TOPOLOGY_UNAVAILABLE` = `ErrorKind(Int32(-9))`: The machine could not be described.
- `PERMISSION_DENIED` = `ErrorKind(Int32(-10))`: A privileged operation was declined.
- `UNSUPPORTED` = `ErrorKind(Int32(-11))`: This build or this machine has no such facility.
- `LIBRARY_MISSING` = `ErrorKind(Int32(-12))`: Nothing to `dlopen`, or what loaded is a different major version.
- `SYMBOL_MISSING` = `ErrorKind(Int32(-13))`: The library loaded but does not export a symbol the binding needs.
- `CONTENDED` = `ErrorKind(Int32(-14))`: The pool is running another dispatch: another caller's, or the one this call runs inside.
- `code` `Int32`: The raw `fu_status_t` value, kept even when this build does not name it.

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`, `Writable`

## write_to

Spells the failure out in prose, so a code this build does not name still reads.

```mojo
def write_to(self, mut writer: T)
```

- `writer` (mut): The sink the reason is appended to.

## of

Lifts a raw `fu_status_t`, keeping an unnamed one rather than guessing.

```mojo
def of(status: Int32) -> Self
```

- `status`: Whatever the C call returned, named by this build or not.

## Error

What went wrong reaching the C core, and which symbol or argument it was.

```mojo
struct Error
```

- `kind` `ErrorKind`: Which class of failure the C core reported.
- `detail` `StaticString`: The symbol or argument it was about, for a reader rather than for a branch.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`, `Writable`

## write_to

Writes the reason and the detail together, prefixed so the source is unambiguous.

```mojo
def write_to(self, mut writer: T)
```

- `writer` (mut): The sink the message is appended to.

## CallerExclusivity

Whether the thread that dispatches also executes, or only coordinates.

```mojo
struct CallerExclusivity
```

- `INCLUSIVE` = `CallerExclusivity(Int32(0))`: The calling thread owes one slice of the work, which runs inside the join.
- `EXCLUSIVE` = `CallerExclusivity(Int32(1))`: The calling thread only coordinates, so a dispatch can be polled before it is joined.
- `identifier` `c_int`: The raw `fu_caller_exclusivity_t` value the C API exchanges.

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`, `Writable`

## write_to

Names which of the two policies this is.

```mojo
def write_to(self, mut writer: T)
```

- `writer` (mut): The sink the name is appended to.

## Capabilities

The bit set of spin hints and placement facilities a build or a machine offers.

```mojo
struct Capabilities
```

One bit per facility, and two accessors ask two questions of the same bit. [`comptime_capabilities`](#comptime_capabilities)
reports whether the code was built with a path; [`runtime_capabilities`](#runtime_capabilities) reports whether the machine
offers it now. Neither implies the other.

- `NONE` = `Capabilities(UInt32(0))`: Nothing detected, or nothing compiled in.
- `X86_PAUSE` = `Capabilities(UInt32(1))`: The `PAUSE` spin hint, on every x86 since the Pentium 4.
- `X86_TPAUSE` = `Capabilities(UInt32(2))`: `TPAUSE` sleeps the core until a deadline. Needs the `WAITPKG` feature.
- `ARM64_YIELD` = `Capabilities(UInt32(4))`: The `YIELD` hint, on every AArch64.
- `ARM64_WFET` = `Capabilities(UInt32(8))`: `WFET` sleeps the core until a deadline or an event. Needs `FEAT_WFxT`.
- `RISCV64_PAUSE` = `Capabilities(UInt32(16))`: The `PAUSE` spin hint, from the `Zihintpause` extension.
- `RISCV64_WRS` = `Capabilities(UInt32(32))`: `WRS.STO` sleeps the hart until a reservation breaks. Needs the `Zawrs` extension.
- `OS_THREADS` = `Capabilities(UInt32(64))`: Own the raw OS thread handle instead of a `std::thread`.
- `TOPOLOGY` = `Capabilities(UInt32(128))`: Enumerate this machine's cores, compute domains, and memory domains.
- `PLACE_THREADS_BY_AFFINITY` = `Capabilities(UInt32(256))`: Bind a thread to a set of cores, choosing where it runs.
- `PLACE_THREADS_BY_CORE_CLASS` = `Capabilities(UInt32(512))`: Steer a thread onto a class of core at creation.
- `RESCHEDULE_THREADS_BY_CLASS` = `Capabilities(UInt32(1024))`: Reclass a thread's scheduler to sleep or wake it.
- `PLACE_MEMORY_ON_DOMAIN` = `Capabilities(UInt32(2048))`: Place a buffer's pages on a chosen memory domain.
- `PLACE_HUGE_PAGES_ON_DOMAIN` = `Capabilities(UInt32(4096))`: Place larger-than-base pages on a chosen memory domain.
- `HUGE_TRANSPARENT_PAGES` = `Capabilities(UInt32(8192))`: The kernel promotes base pages to huge pages on its own.
- `COLOCATE_POOLS_ON_DOMAIN` = `Capabilities(UInt32(16384))`: The domain-aware colocated and distributed pools are compiled.
- `X86_CLDEMOTE` = `Capabilities(UInt32(32768))`: `CLDEMOTE` moves a just-written line toward the shared LLC.
- `ARM64_DC_CVAC` = `Capabilities(UInt32(65536))`: `DC CVAC` cleans a dirty line to the coherency point.
- `RISCV64_ZICBOM` = `Capabilities(UInt32(131072))`: User-mode Zicbom cache-block management, attested through `hwprobe`.
- `X86_CMPCCXADD` = `Capabilities(UInt32(262144))`: `CMPCCXADD`, the conditional atomic add.
- `X86_RAOINT` = `Capabilities(UInt32(524288))`: RAO-INT `aadd` and its family, executed at the shared cache.
- `ARM64_LSE` = `Capabilities(UInt32(1048576))`: Armv8.1 `FEAT_LSE`: one instruction per read-modify-write.
- `ARM64_RCPC` = `Capabilities(UInt32(2097152))`: Armv8.3 `FEAT_LRCPC`: `LDAPR` acquires, cheaper than `LDAR`'s.
- `RISCV64_ZACAS` = `Capabilities(UInt32(4194304))`: RISC-V Zacas, the `amocas` compare-and-swap.
- `RISCV64_ATOMIC` = `Capabilities(UInt32(8388608))`: The RISC-V A extension's `lr`, `sc` and `amo` words.
- `ARM64_PRFM` = `Capabilities(UInt32(16777216))`: `PRFM`, AArch64's prefetch hint.
- `RISCV64_ZICBOP` = `Capabilities(UInt32(33554432))`: RISC-V Zicbop, the `prefetch.w` hint.
- `RISCV64_ZABHA` = `Capabilities(UInt32(67108864))`: RISC-V Zabha, byte and halfword atomics.
- `ANY_YIELD` = `Capabilities(UInt32(63))`: Every busy-wait waiter bit, to enumerate the ones a machine offers.
- `ALL` = `Capabilities(UInt32(4294967295))`: All-ones allow-mask: hand to a pool to disable capability filtering.
- `bits` `UInt32`: One bit per facility, laid out as the C `fu_capability_t` enumerators are.

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`

## __contains__

Whether every bit of `other` is set here.

```mojo
def __contains__(self, other: Self) -> Bool
```

- `other`: The facilities being asked about, one bit each.

## __and__

The intersection, to keep only what a build and a machine both offer.

```mojo
def __and__(self, other: Self) -> Self
```

- `other`: The facilities to keep.

## __or__

The union, to build an allow-mask out of the named facilities.

```mojo
def __or__(self, other: Self) -> Self
```

- `other`: The facilities to add.

## TasksRange

A half-open `[first, first + count)` run of task indices - the "what work" of a slice dispatch.

```mojo
struct TasksRange
```

Iterable, so a callback reads `for task in range` rather than rebuilding the bounds. An idle
thread receives a range with `count == 0`, which every dispatch still calls exactly once.

- `first` `Int`: The first task index in the run.
- `count` `Int`: How many tasks the run covers; zero means an idle thread.

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `SizedRaising`, `TrivialRegisterPassable`

## __len__

How many tasks the run covers.

```mojo
def __len__(self) -> Int
```

## __iter__

Walks the task indices, so a callback loops over the run rather than rebuilding it.

```mojo
def __iter__(self) -> _SequentialRange
```

## end

One past the last task index, so `first..end()` is the half-open span.

```mojo
def end(self) -> Int
```

## is_empty

Whether the run covers no tasks at all.

```mojo
def is_empty(self) -> Bool
```

## IndexedSplit

Splits a range of tasks into fair-sized runs, minimizing the spread across threads.

```mojo
struct IndexedSplit
```

The first `tasks % threads` runs get one extra task; the rest get the floor. Mirrors the C++
`indexed_split`. See https://lemire.me/blog/2025/05/22/dividing-an-array-into-fair-sized-chunks/

- `quotient` `Int`: The floor of tasks over threads, which every run is at least this long.
- `remainder` `Int`: How many of the leading runs take one task more than the floor.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`

## __init__

Precomputes the split once, leaving [`get`](#get) free of division.

```mojo
def __init__(tasks_count: Int, threads_count: Int) -> Self
```

- `tasks_count`: How many tasks are shared out; zero is allowed and leaves every run empty.
- `threads_count`: How many runs to cut, which must be positive.

## get

The run owned by `thread_index`.

```mojo
def get(self, thread_index: Int) -> TasksRange
```

- `thread_index`: Which of the runs to describe, counted from zero.

## SyncConstPointer

A read-only view letting one immutable buffer be read by every worker across a C callback.

```mojo
struct SyncConstPointer[T: AnyType]
```

The caller guarantees the pointee outlives the parallel region and is not mutated while shared.

- `T` (comptime): The element type, read unchanged by every worker for the whole region.

- `pointer` `Pointer[T, ImmUntrackedOrigin]`: The first element, its origin erased so the view survives the C callback boundary.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`

## at

The element at `index`; the caller owns bounds checking.

```mojo
def at(self, index: Int) -> ref[ImmUntrackedOrigin] T
```

- `index`: An offset in elements, not in bytes.

## SyncMutPointer

A writable view letting workers write disjoint slots of one buffer across a C callback.

```mojo
struct SyncMutPointer[T: AnyType]
```

The caller guarantees each worker touches disjoint indices and the pointee outlives the region.

- `T` (comptime): The element type, whose slots the workers write one apiece.

- `pointer` `Pointer[T, MutUntrackedOrigin]`: The first element, its origin erased so the view survives the C callback boundary.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`

## at

A reference to the element at `index`; the caller owns disjointness and bounds.

```mojo
def at(self, index: Int) -> ref[MutUntrackedOrigin] T
```

- `index`: An offset in elements, not in bytes.

## version

The loaded library's own version.

```mojo
def version(library: Library) -> Tuple[Int, Int, Int]
```

- `library`: The loaded core to report on, whose major version the loader already matched.

## comptime_capabilities

What this build of the library was compiled to be able to do.

```mojo
def comptime_capabilities(library: Library) -> Capabilities
```

- `library`: The loaded core whose build is being asked about.

## runtime_capabilities

What this machine actually offers, which is not implied by the above in either direction.

```mojo
def runtime_capabilities(library: Library) -> Capabilities
```

- `library`: Any loaded core; the answer describes the machine rather than the build.

## name_capabilities

Renders a mask as a comma-separated name list such as "arm64_yield,arm64_wfet".

```mojo
def name_capabilities(library: Library, capabilities: Capabilities) -> String
```

- `library`: The loaded core that holds the naming table.
- `capabilities`: A mask from either accessor; a bit this build cannot name is skipped.

Raises: [`Error`](#Error) if the core refuses the rendering, which a buffer it cannot write does with [`INVALID_ARGUMENT`](#INVALID_ARGUMENT).

## comptime_capabilities_string

The compiled-in capabilities, named.

```mojo
def comptime_capabilities_string(library: Library) -> String
```

- `library`: The loaded core whose build is being named.

Raises: [`Error`](#Error) if the core refuses the rendering, which a buffer it cannot write does with [`INVALID_ARGUMENT`](#INVALID_ARGUMENT).

## runtime_capabilities_string

The capabilities this machine offers, named.

```mojo
def runtime_capabilities_string(library: Library) -> String
```

- `library`: Any loaded core; the names describe the machine rather than the build.

Raises: [`Error`](#Error) if the core refuses the rendering, which a buffer it cannot write does with [`INVALID_ARGUMENT`](#INVALID_ARGUMENT).

## bytes_for_elements

Bytes occupied by `count` elements of `element_bytes` each, refusing a product that wraps.

```mojo
def bytes_for_elements(count: Int, element_bytes: Int) -> Int
```

- `count`: How many elements the buffer holds.
- `element_bytes`: The width of one element.

Raises: With [`INVALID_ARGUMENT`](#INVALID_ARGUMENT), when the product would exceed `Int.MAX`.

## DEFAULT_ALIGNMENT

Two cache lines, because most x86 parts prefetch in pairs, matching the C++ `default_alignment_k`.

```mojo
comptime DEFAULT_ALIGNMENT = 128
```