Crate fork_union 

Low-latency OpenMP-style NUMA-aware cross-platform fine-grained parallelism library.

Fork Union 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.

Structs

AllocationResult

Result of a NUMA allocation containing both the allocated pointer and metadata.

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.

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.

ForThreadsOperation

Operation object for parallel thread execution with explicit broadcast/join control.

IndexedSplit

Splits a range of tasks into fair-sized chunks for parallel distribution.

PinnedAllocator

NUMA-aware memory allocator pinned to a specific NUMA node.

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” and “memory” location.

RoundRobinVec

A NUMA-aware distributed vector that manages an array of PinnedVecs, each pinned to a specific NUMA node. This structure enables data locality for parallel operations by distributing elements in a round-robin fashion across NUMA nodes, minimizing cross-node memory access penalties.

SafePtr

A thread-safe wrapper for raw pointers used in parallel operations.

SyncConstPtr

A thread-safe wrapper around raw pointers for sharing read-only data across threads.

ThreadPool

Minimalistic, fixed‑size thread‑pool for blocking scoped parallelism.

Enums

CallerExclusivity

Defines whether the calling thread participates in task execution.

Error

Error types that can occur during thread pool operations.

Functions

capabilities_string

Returns a string describing available platform capabilities.

capabilities_string_ptr

Returns a raw pointer to the capabilities string for no_std environments.

count_colocations

Returns the number of distinct thread colocations available.

count_logical_cores

Returns the number of logical CPU cores available on the system.

count_numa_nodes

Returns the number of NUMA nodes available on the system.

count_quality_levels

Returns the number of distinct Quality-of-Service levels.

default_numa_allocator

Creates an allocator for the first available NUMA node (typically node 0).

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.

named_spawn

Spawns a named pool with the specified number of threads.

numa_enabled

Returns true if NUMA support was compiled into the library.

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 Fork Union library.

version_minor

Returns the minor version number of the Fork Union library.

version_patch

Returns the patch version number of the Fork Union library.

volume_any_pages

Returns the total volume of any pages (huge or regular) available across all NUMA nodes.

Type Aliases

SpinMutex

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