Skip to main content

Crate forkunion

Crate forkunion 

Source
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§

prelude

Structs§

AllocationResult
Result of a memory-domain allocation; carries only the OS id, so it can outlive the topology.
BasicSpinMutex
A generic spin mutex that uses CPU-specific pause instructions for efficient busy-waiting.
BasicSpinMutexGuard
A guard providing access to the data protected by a BasicSpinMutex.
BroadcastJoin
A synchronization guard that waits for all threads to finish the broadcasted closure.
CacheAligned
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.
ComputeDomain
A position in the topology’s array of compute domains, in [0, compute_domains_count()).
DomainAllocator
An allocator bound to a single memory domain, so every block it hands out is domain-local.
DynamicScheduler
Scheduler that enables dynamic work stealing.
Fabric
The measured memory fabric - what this process observed, as opposed to the structure a Topology declares. Two query families: edge queries (initiator, target) describe one interconnect link; medium queries (target) describe the memory pool itself, independent of any initiator.
Filter
ForNDynamicOperation
Operation object for parallel task execution with dynamic work-stealing.
ForNOperation
Operation object for parallel task execution with static load balancing.
ForSlicesOperation
Operation object for parallel slice execution.
IndexedSplit
Splits a range of tasks into fair-sized chunks for parallel distribution.
Map
MemoryDomain
A position in the topology’s array of memory domains, in [0, memory_domains_count()). See ComputeDomain for why these are separate types.
MemoryDomainId
An OS memory-domain id - a NUMA node - the allocators key off, obtained from Topology::memory_domain_id_at_index; -1 when there is none.
ParallelExactIter
ParallelRange
ParallelRunner
ParallelSlice
ParallelSliceMut
ParallelSliceZip
PinnedVec
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”.
ReplicatedArray
One full length-n copy 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.
ShardLocation
Where a logical element lives - which memory domain, and its index within that shard.
ShardedArray
A sequence partitioned across memory domains as contiguous segments, each element stored once.
StaticScheduler
Scheduler that uses static chunk assignment.
SyncConstPtr
A thread-safe wrapper around raw pointers for sharing read-only data across threads.
SyncMutPtr
ThreadPool
Minimalistic, fixed-size thread-pool for blocking scoped parallelism.
Topology
An explicit, owned handle to the machine’s compute and memory topology.

Enums§

CallerExclusivity
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§

IntoParallelIterator
ParallelIterator
ParallelIteratorExt
ParallelSchedule

Functions§

comptime_capabilities
Which kernel facilities this build of ForkUnion was compiled to use.
comptime_capabilities_string
The set comptime_capabilities bits, 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 n similar duration calls between threads.
for_n_dynamic
Standalone function to execute n uneven tasks on all threads.
for_slices
Standalone function to distribute n tasks 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_capabilities bits, 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§

SpinMutex
A type alias for the most commonly used spin mutex configuration.