Expand description
Low-latency OpenMP-style NUMA-aware cross-platform fine-grained parallelism library.
ForkUnion provides a minimalistic cross-platform thread-pool implementation and Parallel Algorithms,
avoiding dynamic memory allocations, exceptions, system calls, and heavy Compare-And-Swap instructions.
The library leverages the “weak memory model” to allow Arm and IBM Power CPUs to aggressively optimize
execution at runtime. It also aggressively tests against overflows on smaller index types, and is safe
to use even with the maximal usize values.
This Rust wrapper provides a safe interface around the precompiled C library, maintaining zero-allocation principles while leveraging NUMA-aware optimizations and CPU-specific busy-waiting instructions.
The wrapper mirrors the C++ core’s header layout: [topology] for the hardware view, [types] for
portable building blocks, [allocators] for NUMA-aware allocation, [scheduling] for the thread pool,
its dispatch primitives, and the measured memory fabric, and [parallel] for the Rayon-style parallel
iterators. Every public symbol is re-exported here, so use forkunion::* resolves exactly as it did
before the split.
Modules§
Structs§
- Allocation
Result - Result of a memory-domain allocation; carries only the OS id, so it can outlive the topology.
- Basic
Spin Mutex - A generic spin mutex that uses CPU-specific pause instructions for efficient busy-waiting.
- Basic
Spin Mutex Guard - A guard providing access to the data protected by a
BasicSpinMutex. - Broadcast
Join - A synchronization guard that waits for all threads to finish the broadcasted closure.
- Cache
Aligned - Cache-line aligned wrapper to prevent false sharing between threads.
- Capabilities
- Everything the library can do, whether decided when it was compiled or found on this machine.
- Compute
Domain - A position in the topology’s array of compute domains, in
[0, compute_domains_count()). - Domain
Allocator - An allocator bound to a single memory domain, so every block it hands out is domain-local.
- Dynamic
Scheduler - Scheduler that enables dynamic work stealing.
- Fabric
- The measured memory fabric - what this process observed, as opposed to the structure a
Topologydeclares. Two query families: edge queries(initiator, target)describe one interconnect link; medium queries(target)describe the memory pool itself, independent of any initiator. - Filter
- ForN
Dynamic Operation - Operation object for parallel task execution with dynamic work-stealing.
- ForN
Operation - Operation object for parallel task execution with static load balancing.
- ForSlices
Operation - Operation object for parallel slice execution.
- Indexed
Split - Splits a range of tasks into fair-sized chunks for parallel distribution.
- Map
- Memory
Domain - A position in the topology’s array of memory domains, in
[0, memory_domains_count()). SeeComputeDomainfor why these are separate types. - Memory
Domain Id - An OS memory-domain id - a NUMA node - the allocators key off, obtained from
Topology::memory_domain_id_at_index;-1when there is none. - Parallel
Exact Iter - Parallel
Range - Parallel
Runner - Parallel
Slice - Parallel
Slice Mut - Parallel
Slice Zip - Pinned
Vec - A Vec-like container that uses NUMA-aware pinned memory allocation.
- Prong
- A “prong” - the tip of a “fork” - pinning a “task” to a “thread” within a “compute domain”.
- Replicated
Array - One full length-
ncopy of a sequence per memory domain, so every thread reads a node-local replica. - SafePtr
- A thread-safe wrapper for raw pointers used in parallel operations.
- Scope
- A borrow-scoped handle to a thread pool, yielded by
ThreadPool::scope. - Shard
Location - Where a logical element lives - which memory domain, and its index within that shard.
- Sharded
Array - A sequence partitioned across memory domains as contiguous segments, each element stored once.
- Static
Scheduler - Scheduler that uses static chunk assignment.
- Sync
Const Ptr - A thread-safe wrapper around raw pointers for sharing read-only data across threads.
- Sync
MutPtr - Thread
Pool - Minimalistic, fixed-size thread-pool for blocking scoped parallelism.
- Topology
- An explicit, owned handle to the machine’s compute and memory topology.
Enums§
- Caller
Exclusivity - Defines whether the calling thread participates in task execution.
- Error
- Error types that can occur during thread pool operations.
Constants§
- DEFAULT_
ALIGNMENT - Default alignment for preventing false sharing between threads.
Traits§
Functions§
- comptime_
capabilities - Which kernel facilities this build of ForkUnion was compiled to use.
- comptime_
capabilities_ string - The set
comptime_capabilitiesbits, comma-separated, like"threads,topology". - default_
pinned_ allocator - Creates an allocator for the first memory domain, index 0, when the specific domain does not matter.
- fold_
with_ scratch - for_
each_ prong_ mut - Helper function to visit every element exactly once with mutable access.
- for_
each_ prong_ mut_ dynamic - Helper function to visit every element exactly once with dynamic work-stealing.
- for_n
- Standalone function to distribute
nsimilar duration calls between threads. - for_
n_ dynamic - Standalone function to execute
nuneven tasks on all threads. - for_
slices - Standalone function to distribute
ntasks in slices. - name_
capabilities - Formats a capability bitset into a comma-separated name list, like
"threads,topology". - named_
spawn - Spawns a named pool with the specified number of threads.
- runtime_
capabilities - Which features this machine turned out to offer, probing the CPU and the memory system.
- runtime_
capabilities_ string - The set
runtime_capabilitiesbits, comma-separated, like"arm64_yield,numa_aware". - spawn
- Spawns a pool with the specified number of threads.
- version
- Returns the library version as a tuple of (major, minor, patch).
- version_
major - Returns the major version number of the ForkUnion library.
- version_
minor - Returns the minor version number of the ForkUnion library.
- version_
patch - Returns the patch version number of the ForkUnion library.
Type Aliases§
- Spin
Mutex - A type alias for the most commonly used spin mutex configuration.