### SpinMutex Usage Example Source: https://docs.rs/fork_union/latest/fork_union/type.SpinMutex.html Demonstrates basic usage of SpinMutex, including creation, locking, and modifying the protected data. ```rust use fork_union::*; let mutex = SpinMutex::new(42); let mut guard = mutex.lock(); *guard = 100; ``` -------------------------------- ### get Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Accesses an element at a global `index` using round-robin distribution. ```APIDOC ## get ### Description Accesses an element at a global `index` using round-robin distribution. The element at global `index` is located at `local_index = index / N` in the `PinnedVec` on `numa_node = index % N`, where `N` is the number of NUMA nodes. ### Method `pub fn get(&self, index: usize) -> Option<&T>` ### Parameters #### Path Parameters - **index** (usize) - Required - The global round-robin index of the element. ### Returns A reference to the element, or `None` if the index is out of bounds. ### Examples ```rust use fork_union::* let mut rr_vec = RoundRobinVec::::new().expect("Failed to create RoundRobinVec"); // Add some elements... if let Some(element) = rr_vec.get(5) { println!("Element at index 5: {}", element); } ``` ``` -------------------------------- ### PinnedVec Usage Example Source: https://docs.rs/fork_union/latest/fork_union/struct.PinnedVec.html Demonstrates creating a PinnedVec, adding elements, accessing them, and iterating. Ensure a PinnedAllocator is created for the desired NUMA node. ```rust use fork_union::*; // Create a vector on NUMA node 0 let allocator = PinnedAllocator::new(0).expect("Failed to create alloc"); let mut vec = PinnedVec::::new_in(allocator); // Add elements vec.push(42).expect("Failed to push"); vec.push(100).expect("Failed to push"); // Access elements assert_eq!(vec.len(), 2); assert_eq!(vec[0], 42); assert_eq!(vec[1], 100); // Iterate over elements for (i, &value) in vec.iter().enumerate() { println!("Element {}: {}", i, value); } ``` -------------------------------- ### BasicSpinMutex Usage Example Source: https://docs.rs/fork_union/latest/fork_union/struct.BasicSpinMutex.html Demonstrates creating, locking, modifying, and verifying data within a BasicSpinMutex. The lock is automatically released when the guard goes out of scope. ```rust use fork_union::*; // Create a spin mutex with pause instructions enabled let mutex = BasicSpinMutex::::new(42); // Lock, access data, and unlock { let mut guard = mutex.lock(); *guard = 100; } // Lock is automatically released when guard goes out of scope // Verify the value was changed assert_eq!(*mutex.lock(), 100); ``` -------------------------------- ### Using default_numa_allocator and specific NUMA allocators Source: https://docs.rs/fork_union/latest/fork_union/fn.default_numa_allocator.html Demonstrates how to get the default NUMA allocator, allocate memory, and verify the NUMA node. It also shows how to count NUMA nodes and create an allocator for a specific node. ```rust use fork_union::*; let allocator = default_numa_allocator().expect("No NUMA nodes available"); let allocation = allocator.allocate(1024).expect("Failed to allocate"); // The default allocator uses NUMA node 0 assert_eq!(allocation.numa_node(), 0); // For more control, create specific NUMA allocators let numa_count = count_numa_nodes(); println!("System has {} NUMA nodes available", numa_count); if numa_count > 1 { let allocator_node1 = PinnedAllocator::new(1).expect("NUMA node 1 available"); let allocation2 = allocator_node1.allocate(2048).expect("Failed to allocate on node 1"); assert_eq!(allocation2.numa_node(), 1); } ``` -------------------------------- ### Get Full Library Version Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns the library version as a tuple of (major, minor, patch). ```rust pub fn version() -> (usize, usize, usize) { (version_major(), version_minor(), version_patch()) } ``` -------------------------------- ### Creating and Using SyncConstPtr Source: https://docs.rs/fork_union/latest/fork_union/struct.SyncConstPtr.html Demonstrates how to create a SyncConstPtr from a vector's raw pointer and safely access an element using the `get` method. This is useful for sharing immutable data across threads or async tasks. ```rust use fork_union::*; let data = vec![1, 2, 3, 4, 5]; let sync_ptr = SyncConstPtr::new(data.as_ptr()); // Safe to use in async contexts let value = unsafe { sync_ptr.get(0) }; assert_eq!(*value, 1); ``` -------------------------------- ### Get Platform Capabilities String Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Retrieves a string describing available platform capabilities. Returns None if the pointer is null. Requires the "std" feature. ```rust pub fn capabilities_string() -> Option<&'static str> { unsafe { let ptr = fu_capabilities_string(); if ptr.is_null() { None } else { CStr::from_ptr(ptr).to_str().ok() } } } ``` -------------------------------- ### Example of for_n_dynamic task distribution Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Demonstrates distributing 100 tasks with varying work durations using `for_n_dynamic`. Some tasks are simulated to take longer to highlight work-stealing. ```rust let mut pool = spawn(4); pool.for_n_dynamic(100, |prong| { // Simulate variable work duration - some tasks take longer let iterations = if prong.task_index % 10 == 0 { 10000 } else { 100 }; for i in 0..iterations { std::hint::black_box(prong.task_index * i); } }); ``` -------------------------------- ### Get element from SyncConstPtr Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Safely gets a reference to an element at a given index. The caller must ensure the index is within bounds and data is initialized and valid. ```rust pub unsafe fn get(&self, index: usize) -> &T { &*self.ptr.add(index) } ``` -------------------------------- ### PinnedVec Example: Initialization and Element Access Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Demonstrates creating a PinnedVec on a specific NUMA node, adding elements, and accessing them. This vector uses NUMA-aware pinned memory allocation. ```rust /// let allocator = PinnedAllocator::new(0).expect("Failed to create alloc"); /// let mut vec = PinnedVec::::new_in(allocator); /// /// // Add elements /// vec.push(42).expect("Failed to push"); /// vec.push(100).expect("Failed to push"); /// /// // Access elements /// assert_eq!(vec.len(), 2); /// assert_eq!(vec[0], 42); /// assert_eq!(vec[1], 100); /// /// // Iterate over elements /// for (i, &value) in vec.iter().enumerate() { /// println!("Element {}: {}", i, value); /// } /// ``` ``` -------------------------------- ### Thread Pool Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Information and examples related to the Fork Union thread pool. ```APIDOC ## ThreadPool ### Description Minimalistic, fixed-size thread-pool for blocking scoped parallelism. This is a safe Rust wrapper around the precompiled C thread pool implementation. The current thread participates in the work, so for `N`-way parallelism the implementation actually spawns `N − 1` background workers and runs the last slice on the caller thread. ### Thread Safety `ThreadPool` is `Send + Sync` and can be safely shared between threads, though operations require a mutable reference to ensure exclusive access during execution. ### Performance Characteristics - Zero dynamic allocations during task execution - Leverages weak memory model for optimal ARM and PowerPC performance - NUMA-aware thread placement when available - Uses CPU-specific busy-waiting instructions for minimal latency ### Examples Basic usage with simple computations: ```rust use fork_union::* // Create a thread pool with 4 threads let mut pool = spawn(4); ``` ``` -------------------------------- ### Example of for_slices task distribution Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Illustrates distributing 1000 tasks in slices using `for_slices`. Each thread processes a contiguous range of tasks, and output shows the processed slice for each thread. ```rust let mut pool = spawn(4); pool.for_slices(1000, |prong, count| { let start_index = prong.task_index; // Process the slice - each thread gets a contiguous range for i in 0..count { let global_index = start_index + i; let result = global_index * global_index; std::hint::black_box(result); } println!("Thread {} processed slice [{}, {})", prong.thread_index, start_index, start_index + count); }); ``` -------------------------------- ### Get Quality of Service Level Count Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns the number of distinct Quality-of-Service levels available on the system. ```rust pub fn count_quality_levels() -> usize { unsafe { fu_count_quality_levels() } } ``` -------------------------------- ### Get First Element Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns a reference to the first element of the vector, or None if it is empty. ```rust pub fn first(&self) -> Option<&T> { self.as_slice().first() } ``` -------------------------------- ### Get Raw Capabilities String Pointer Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns a raw pointer to the capabilities string, suitable for no_std environments. ```rust pub fn capabilities_string_ptr() -> *const c_char { unsafe { fu_capabilities_string() } } ``` -------------------------------- ### Consuming SpinMutex to Get Inner Data Source: https://docs.rs/fork_union/latest/fork_union/type.SpinMutex.html Demonstrates consuming a BasicSpinMutex to retrieve the protected data, bypassing the locking mechanism due to exclusive ownership. ```rust use fork_union::*; let mutex = BasicSpinMutex::::new(42); let data = mutex.into_inner(); assert_eq!(data, 42); ``` -------------------------------- ### Get Total Available Pages Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns the total volume of any pages (huge or regular) available across all NUMA nodes. ```rust pub fn volume_any_pages() -> usize { unsafe { fu_volume_any_pages() } } ``` -------------------------------- ### C FFI: Library Version Functions Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Declares C FFI functions to retrieve the major, minor, and patch versions of the library, as well as check for enabled NUMA support and get capabilities as a string. ```c fn fu_version_major() -> c_int; fn fu_version_minor() -> c_int; fn fu_version_patch() -> c_int; fn fu_enabled_numa() -> c_int; fn fu_capabilities_string() -> *const c_char; ``` -------------------------------- ### Get Fork Union Minor Version Source: https://docs.rs/fork_union/latest/fork_union/fn.version_minor.html Call this function to retrieve the minor version number of the Fork Union library. No setup or imports are required. ```rust pub fn version_minor() -> usize ``` -------------------------------- ### Get Total Volume of Any Pages Source: https://docs.rs/fork_union/latest/fork_union/fn.volume_any_pages.html Call this function to retrieve the total volume of both huge and regular pages across all NUMA nodes. No setup or imports are required. ```rust pub fn volume_any_pages() -> usize ``` -------------------------------- ### BasicSpinMutex Creation Source: https://docs.rs/fork_union/latest/fork_union/type.SpinMutex.html Shows how to create a new BasicSpinMutex with a specific initial value and pause instruction enabled. ```rust use fork_union::*; let mutex = BasicSpinMutex::::new(0); ``` -------------------------------- ### get_colocation Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Gets a reference to the `PinnedVec` at the specified colocation. ```APIDOC ## get_colocation ### Description Gets a reference to the `PinnedVec` at the specified colocation. ### Method `pub fn get_colocation(&self, colocation_index: usize) -> Option<&PinnedVec>` ### Parameters #### Path Parameters - **colocation_index** (usize) - Required - The colocation index ### Returns A reference to the `PinnedVec` at the specified colocation, or `None` if the node doesn't exist. ``` -------------------------------- ### BasicSpinMutex::new Source: https://docs.rs/fork_union/latest/fork_union/struct.BasicSpinMutex.html Creates a new BasicSpinMutex in the unlocked state, initializing it with the provided data. ```APIDOC ## BasicSpinMutex::new ### Description Creates a new spin mutex in the unlocked state. ### Method `pub const fn new(data: T) -> Self` ### Arguments * `data` - The value to be protected by the mutex ### Example ```rust use fork_union::*; let mutex = BasicSpinMutex::::new(0); ``` ``` -------------------------------- ### get_colocation_mut Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Gets a mutable reference to the `PinnedVec` at the specified colocation. ```APIDOC ## get_colocation_mut ### Description Gets a mutable reference to the `PinnedVec` at the specified colocation. ### Method `pub fn get_colocation_mut(&mut self, colocation_index: usize) -> Option<&mut PinnedVec>` ### Parameters #### Path Parameters - **colocation_index** (usize) - Required - The colocation index ### Returns A mutable reference to the `PinnedVec` at the specified colocation, or `None` if the node doesn't exist. ``` -------------------------------- ### Any::type_id Source: https://docs.rs/fork_union/latest/fork_union/struct.PinnedVec.html Gets the `TypeId` of the type this method is called on. This is part of the `Any` trait implementation. ```APIDOC ## Any::type_id ### Description Gets the `TypeId` of `self`. ### Signature `fn type_id(&self) -> TypeId` ``` -------------------------------- ### Get Capabilities String Pointer Source: https://docs.rs/fork_union/latest/fork_union/fn.capabilities_string_ptr.html Returns a raw pointer to the capabilities string for no_std environments. This is useful when direct string manipulation is not possible or desired. ```rust pub fn capabilities_string_ptr() -> *const c_char ``` -------------------------------- ### Get raw pointer from SyncConstPtr Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns the raw pointer stored within SyncConstPtr. ```rust pub fn as_ptr(&self) -> *const T { self.ptr } ``` -------------------------------- ### Get Last Element Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns a reference to the last element of the vector, or None if it is empty. ```rust pub fn last(&self) -> Option<&T> { self.as_slice().last() } ``` -------------------------------- ### SyncConstPtr Usage Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Demonstrates the creation and usage of a SyncConstPtr to access data immutably through a pointer. ```rust #[test] fn sync_const_ptr() { let data = Vec::from([1, 2, 3, 4, 5]); let sync_ptr = SyncConstPtr::new(data.as_ptr()); unsafe { assert_eq!(*sync_ptr.get(0), 1); assert_eq!(*sync_ptr.get(2), 3); assert_eq!(*sync_ptr.get(4), 5); } assert_eq!(sync_ptr.as_ptr(), data.as_ptr()); } ``` -------------------------------- ### capabilities_string Source: https://docs.rs/fork_union/latest/fork_union/fn.capabilities_string.html Returns a string describing available platform capabilities. ```APIDOC ## capabilities_string ### Description Returns a string describing available platform capabilities. ### Signature ```rust pub fn capabilities_string() -> Option<&'static str> ``` ### Returns An `Option<&'static str>` which is `Some` containing the capabilities string if available, otherwise `None`. ``` -------------------------------- ### Get NUMA Node of PinnedAllocator Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns the NUMA node index to which this `PinnedAllocator` is pinned. ```rust pub fn numa_node(&self) -> usize { self.numa_node } ``` -------------------------------- ### Allocate and Initialize Memory with PinnedAllocator Source: https://docs.rs/fork_union/latest/fork_union/struct.PinnedAllocator.html Demonstrates how to create a PinnedAllocator, allocate memory for a specified number of elements of a given type, and then initialize that memory. This is useful when you need a contiguous block of memory that is guaranteed not to move. ```rust use fork_union::* let allocator = PinnedAllocator::new(0).unwrap(); let mut allocation = allocator.allocate_for_at_least::(1000).expect("Failed to allocate"); let actual_count = allocation.allocated_bytes() / std::mem::size_of::(); println!("Requested {} u32s, got space for {} u32s", 1000, actual_count); // The allocation provides at least the requested number of elements assert!(actual_count >= 1000); // Initialize the allocated memory let slice = unsafe { allocation.as_mut_slice_of::() }; for i in 0..1000 { slice[i] = i as u32; } // Verify initialization assert_eq!(slice[0], 0); assert_eq!(slice[999], 999); ``` -------------------------------- ### Get Mutable Reference to Element Source: https://docs.rs/fork_union/latest/fork_union/struct.SafePtr.html Provides mutable access to the element wrapped by the SafePtr. ```rust pub fn get_mut(&self) -> &mut T ``` -------------------------------- ### Get Library Version Patch Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns the patch version number of the Fork Union library. ```rust pub fn version_patch() -> usize { unsafe { fu_version_patch() as usize } } ``` -------------------------------- ### Basic ThreadPool Usage Source: https://docs.rs/fork_union/latest/fork_union/struct.ThreadPool.html Demonstrates creating a thread pool and executing work on its threads. Use this for general parallel task execution. ```rust use fork_union::* // Create a thread pool with 4 threads let mut pool = spawn(4); // Execute work on each thread pool.for_threads(|thread_index, colocation_index| { println!("Thread {} on colocation {}", thread_index, colocation_index); }); // Distribute 1000 tasks across threads pool.for_n(1000, |prong| { // Each task gets a unique index via prong.task_index let result = prong.task_index * prong.task_index; std::hint::black_box(result); // Prevent optimization }); ``` -------------------------------- ### Get Library Version Minor Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns the minor version number of the Fork Union library. ```rust pub fn version_minor() -> usize { unsafe { fu_version_minor() as usize } } ``` -------------------------------- ### BasicSpinMutexGuard::get Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns a reference to the data protected by the `BasicSpinMutexGuard`. ```APIDOC ## BasicSpinMutexGuard::get ### Description Returns a reference to the protected data. This method is rarely needed since the guard implements `Deref`. ### Signature ```rust pub fn get(&self) -> &T ``` ### Parameters None ### Returns A reference to the protected data. ### Examples ```rust // Example usage within the context of acquiring a lock ``` ``` -------------------------------- ### SyncConstPtr::new Source: https://docs.rs/fork_union/latest/fork_union/struct.SyncConstPtr.html Creates a new SyncConstPtr from a raw pointer. The caller must ensure the pointer is valid and the data remains unmodified. ```APIDOC ## pub fn new(ptr: *const T) -> Self Creates a new `SyncConstPtr` from a raw pointer. ### Safety The caller must ensure that: * The pointer is valid for the intended usage duration * The pointed-to data will not be modified during use * The pointer is properly aligned for type `T` ``` -------------------------------- ### Get Library Version Major Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns the major version number of the Fork Union library. ```rust pub fn version_major() -> usize { unsafe { fu_version_major() as usize } } ``` -------------------------------- ### Get Logical Core Count Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns the number of logical CPU cores available on the system. ```rust pub fn count_logical_cores() -> usize { unsafe { fu_count_logical_cores() } } ``` -------------------------------- ### BasicSpinMutexGuard Methods Source: https://docs.rs/fork_union/latest/fork_union/struct.BasicSpinMutexGuard.html Provides methods to access the data protected by the BasicSpinMutex. ```APIDOC ## pub fn get(&self) -> &T ### Description Returns a reference to the protected data. This method is rarely needed since the guard implements `Deref`. ### Method `get` ### Parameters None ### Returns `&T` - A reference to the protected data. ``` ```APIDOC ## pub fn get_mut(&mut self) -> &mut T ### Description Returns a mutable reference to the protected data. This method is rarely needed since the guard implements `DerefMut`. ### Method `get_mut` ### Parameters None ### Returns `&mut T` - A mutable reference to the protected data. ``` -------------------------------- ### Create SyncConstPtr Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Creates a new SyncConstPtr from a raw pointer. Ensure the pointer is valid and data is not modified during use. ```rust pub fn new(ptr: *const T) -> Self { Self { ptr } } ``` -------------------------------- ### Get raw mutable pointer from SyncMutPtr Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns the raw mutable pointer stored within SyncMutPtr. ```rust pub fn as_ptr(&self) -> *mut T { self.ptr } ``` -------------------------------- ### Get Mutable Last Element Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns a mutable reference to the last element of the vector, or None if it is empty. ```rust pub fn last_mut(&mut self) -> Option<&mut T> { self.as_mut_slice().last_mut() } ``` -------------------------------- ### Create and use PinnedAllocator Source: https://docs.rs/fork_union/latest/fork_union/struct.PinnedAllocator.html Demonstrates creating a PinnedAllocator for a NUMA node and allocating memory. Ensure the NUMA node is valid before creating the allocator. ```rust use fork_union::*; let allocator = PinnedAllocator::new(0).expect("Failed to create alloc for NUMA node 0"); let allocation = allocator.allocate(1024).expect("Failed to allocate 1024 bytes"); // Access the allocated memory let memory_slice = allocation.as_slice(); assert_eq!(memory_slice.len(), 1024); println!("Allocated {} bytes on NUMA node {}", allocation.allocated_bytes(), allocation.numa_node()); ``` -------------------------------- ### Provided Methods Source: https://docs.rs/fork_union/latest/fork_union/trait.ParallelIterator.html These methods are provided by default and can be used directly or overridden. ```APIDOC ## Provided Methods #### fn is_empty(&self) -> bool #### fn drive_static(self, pool: &mut ThreadPool, consumer: F) where F: Fn(Self::Item, Prong) + Sync, #### fn drive_dynamic(self, pool: &mut ThreadPool, consumer: F) where F: Fn(Self::Item, Prong) + Sync, #### fn map(self, mapper: M) -> Map where M: Fn(Self::Item) -> U + Sync, #### fn filter

(self, predicate: P) -> Filter where P: Fn(&Self::Item) -> bool + Sync, ``` -------------------------------- ### Get Mutable First Element Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns a mutable reference to the first element of the vector, or None if it is empty. ```rust pub fn first_mut(&mut self) -> Option<&mut T> { self.as_mut_slice().first_mut() } ``` -------------------------------- ### ParallelExactIter::new Source: https://docs.rs/fork_union/latest/fork_union/struct.ParallelExactIter.html Creates a new ParallelExactIter with a specified length and an indexer function. ```APIDOC ## ParallelExactIter::new ### Description Creates a new `ParallelExactIter` with a specified length and an indexer function. ### Signature ```rust pub fn new(len: usize, indexer: I) -> Self ``` ### Parameters * `len` (usize) - The total number of elements to iterate over. * `indexer` (I) - A function that takes an index (usize) and returns an element of type T. ``` -------------------------------- ### Get Mutable Reference to Element Source: https://docs.rs/fork_union/latest/fork_union/struct.SafePtr.html Provides mutable access to the element at a specific index within the SafePtr. ```rust pub fn get_mut_at(&self, index: usize) -> &mut T ``` -------------------------------- ### SyncMutPtr::new Source: https://docs.rs/fork_union/latest/fork_union/struct.SyncMutPtr.html Creates a new SyncMutPtr from a raw mutable pointer. ```APIDOC ## SyncMutPtr::new ### Description Creates a new `SyncMutPtr` from a raw mutable pointer. ### Signature ```rust pub const fn new(ptr: *mut T) -> Self ``` ``` -------------------------------- ### Get Task Range for a Thread Source: https://docs.rs/fork_union/latest/fork_union/struct.IndexedSplit.html Retrieves the specific range of tasks assigned to a given thread index. ```rust pub fn get(&self, thread_index: usize) -> Range ``` -------------------------------- ### Initialize and Fill RoundRobinVec Source: https://docs.rs/fork_union/latest/fork_union/struct.RoundRobinVec.html Demonstrates creating a new RoundRobinVec and filling all its distributed vectors with a specific value using a thread pool for parallel execution. ```rust use fork_union::*; let mut pool = ThreadPool::try_spawn(4).expect("Failed to create pool"); let mut rr_vec = RoundRobinVec::::new().expect("Failed to create RoundRobinVec"); // Fill all vectors across all NUMA nodes with the same value r_vec.fill(42, &mut pool); ``` -------------------------------- ### Create a new BasicSpinMutex Source: https://docs.rs/fork_union/latest/fork_union/struct.BasicSpinMutex.html Initializes a new BasicSpinMutex with the provided data. This method creates the mutex in an unlocked state. ```rust use fork_union::*; let mutex = BasicSpinMutex::::new(0); ``` -------------------------------- ### get Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns a reference to an element or subslice based on the provided index type. Returns `None` if the index is out of bounds. ```APIDOC ## get ### Description Returns a reference to an element or subslice depending on the type of index. ### Arguments * `index` - An index that implements `core::slice::SliceIndex`. ### Returns An `Option` containing a reference to the element or subslice if the index is valid, otherwise `None`. ### Signature pub fn get(&self, index: I) -> Option<&>::Output> where I: core::slice::SliceIndex<[T]> ``` -------------------------------- ### Generic CloneToUninit Implementation (Nightly Only) Source: https://docs.rs/fork_union/latest/fork_union/struct.Prong.html Provides the `clone_to_uninit` method for any type `T` that implements `Clone`. This is a nightly-only experimental API. ```rust unsafe fn clone_to_uninit(&self, dest: *mut u8) ``` -------------------------------- ### CloneToUninit::clone_to_uninit (Nightly) Source: https://docs.rs/fork_union/latest/fork_union/struct.ParallelRange.html Nightly-only experimental API for performing copy-assignment from `self` to an uninitialized destination. Requires `T: Clone`. ```rust unsafe fn clone_to_uninit(&self, dest: *mut u8)> ``` -------------------------------- ### RoundRobinVec::get_colocation_mut Source: https://docs.rs/fork_union/latest/fork_union/struct.RoundRobinVec.html Gets a mutable reference to the PinnedVec at the specified colocation index. Returns None if the node does not exist. ```APIDOC ## pub fn get_colocation_mut( &mut self, colocation_index: usize, ) -> Option<&mut PinnedVec> ### Description Gets a mutable reference to the `PinnedVec` at the specified colocation. ### Arguments * `colocation_index` - The colocation index ### Returns A mutable reference to the `PinnedVec` at the specified colocation, or `None` if the node doesn’t exist. ``` -------------------------------- ### SafePtr::new Source: https://docs.rs/fork_union/latest/fork_union/struct.SafePtr.html Creates a new SafePtr instance from a mutable raw pointer. ```APIDOC ## SafePtr::new ### Description Creates a new SafePtr from a raw pointer. ### Signature ```rust pub fn new(ptr: *mut T) -> Self ``` ``` -------------------------------- ### RoundRobinVec::get_colocation Source: https://docs.rs/fork_union/latest/fork_union/struct.RoundRobinVec.html Gets an immutable reference to the PinnedVec at the specified colocation index. Returns None if the node does not exist. ```APIDOC ## pub fn get_colocation(&self, colocation_index: usize) -> Option<&PinnedVec> ### Description Gets a reference to the `PinnedVec` at the specified colocation. ### Arguments * `colocation_index` - The colocation index ### Returns A reference to the `PinnedVec` at the specified colocation, or `None` if the node doesn’t exist. ``` -------------------------------- ### Experimental Provide Method Source: https://docs.rs/fork_union/latest/fork_union/enum.Error.html An experimental, nightly-only API for providing type-based access to error report context. Requires the `error_generic_member_access` feature. ```rust fn provide<'a>(&'a self, request: &mut Request<'a>) ``` -------------------------------- ### Get Major Version Number Source: https://docs.rs/fork_union/latest/fork_union/fn.version_major.html Call this function to retrieve the major version number of the Fork Union library. ```rust pub fn version_major() -> usize ``` -------------------------------- ### SpinMutex::new Source: https://docs.rs/fork_union/latest/fork_union/type.SpinMutex.html Creates a new SpinMutex in the unlocked state. ```APIDOC ## SpinMutex::new ### Description Creates a new spin mutex in the unlocked state. ### Method `SpinMutex::new(data: T) -> SpinMutex` ### Arguments * `data` - The value to be protected by the mutex ### Example ```rust use fork_union::SpinMutex; let mutex = SpinMutex::new(42); ``` ``` -------------------------------- ### PinnedAllocator::new Source: https://docs.rs/fork_union/latest/fork_union/struct.PinnedAllocator.html Creates a new PinnedAllocator. The initial capacity can be set. ```APIDOC ## PinnedAllocator::new ### Description Creates a new `PinnedAllocator` with a specified initial capacity. ### Arguments * `min_count` - The minimum number of elements to allocate space for. ### Returns A `Result` containing the new `PinnedAllocator` or an error if allocation fails. ### Example ```rust use fork_union::PinnedAllocator; let allocator = PinnedAllocator::new(0).unwrap(); ``` ``` -------------------------------- ### SpinMutex::get_mut Source: https://docs.rs/fork_union/latest/fork_union/type.SpinMutex.html Gets a mutable reference to the protected data. Since this requires a mutable reference to the mutex, no locking is needed. ```APIDOC ## SpinMutex::get_mut ### Description Gets a mutable reference to the protected data. Since this requires a mutable reference to the mutex, no locking is needed as we have exclusive access. ### Method `SpinMutex::get_mut(&mut self) -> &mut T` ### Example ```rust use fork_union::SpinMutex; let mut mutex = SpinMutex::new(0); *mutex.get_mut() = 42; assert_eq!(*mutex.lock(), 42); ``` ``` -------------------------------- ### Iterate Threads in Colocations Source: https://docs.rs/fork_union/latest/fork_union/struct.ThreadPool.html Demonstrates how to iterate through thread colocations and count the number of threads within each. This is useful for NUMA-aware load balancing. ```rust use fork_union::* let pool = spawn(8); let total_colocations = pool.colocations(); for colocation_index in 0..total_colocations { let thread_count = pool.count_threads_in(colocation_index); println!("Colocation {} has {} threads", colocation_index, thread_count); } ``` -------------------------------- ### SyncConstPtr::as_ptr Source: https://docs.rs/fork_union/latest/fork_union/struct.SyncConstPtr.html Returns the raw pointer stored within SyncConstPtr. ```APIDOC ## pub fn as_ptr(&self) -> *const T Returns the raw pointer. ``` -------------------------------- ### SyncMutPtr Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html A thread-safe, mutable pointer wrapper. It provides methods to create a new pointer and get a mutable pointer to an element by index. ```APIDOC ## struct SyncMutPtr ### Description A thread-safe, mutable pointer wrapper. ### Methods #### `new(ptr: *mut T) -> Self` Creates a new `SyncMutPtr` from a raw pointer. #### `get(&self, index: usize) -> *mut T` Returns a mutable pointer to the element at the given index. **Safety**: The caller must ensure: - The index is within the bounds of the original allocation - No overlapping mutable access occurs from multiple threads - Each thread accesses disjoint indices when used concurrently - The pointer remains valid for the duration of access #### `as_ptr(&self) -> *mut T` Returns the raw pointer. ``` -------------------------------- ### Get Element or Subslice by Index Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns a reference to an element or subslice based on the index type. Returns None if the index is out of bounds. ```rust pub fn get(&self, index: I) -> Option<&>::Output> where I: core::slice::SliceIndex<[T]>, { self.as_slice().get(index) } ``` -------------------------------- ### Acquiring SpinMutex Lock Source: https://docs.rs/fork_union/latest/fork_union/type.SpinMutex.html Demonstrates acquiring a lock on a BasicSpinMutex, which will spin until the lock is available and busy-wait if necessary. ```rust use fork_union::*; let mutex = BasicSpinMutex::::new(0); let mut guard = mutex.lock(); *guard = 42; ``` -------------------------------- ### SyncMutPtr::as_ptr - Get Raw Pointer Source: https://docs.rs/fork_union/latest/fork_union/struct.SyncMutPtr.html Returns the raw mutable pointer held by the SyncMutPtr instance. This method is safe to call. ```rust pub fn as_ptr(&self) -> *mut T ``` -------------------------------- ### version() Source: https://docs.rs/fork_union/latest/fork_union/fn.version.html Returns the library version as a tuple of (major, minor, patch). ```APIDOC ## version() ### Description Returns the library version as a tuple of (major, minor, patch). ### Signature ```rust pub fn version() -> (usize, usize, usize) ``` ### Returns A tuple `(major, minor, patch)` representing the library version. ``` -------------------------------- ### Sync for SyncMutPtr Source: https://docs.rs/fork_union/latest/fork_union/struct.SyncMutPtr.html Indicates that SyncMutPtr is Sync. ```APIDOC ## impl Sync for SyncMutPtr ### Description This implementation indicates that `SyncMutPtr` can be safely shared between threads. This means multiple threads can have references to the same `SyncMutPtr` concurrently. ``` -------------------------------- ### Get Page Size from AllocationResult Source: https://docs.rs/fork_union/latest/fork_union/struct.AllocationResult.html Returns the page size that was used for this specific memory allocation. This is relevant for NUMA-aware memory management. ```rust pub fn bytes_per_page(&self) -> usize ``` -------------------------------- ### Get Allocated Bytes from AllocationResult Source: https://docs.rs/fork_union/latest/fork_union/struct.AllocationResult.html Returns the number of bytes that were actually allocated. This may be larger than the number of bytes initially requested. ```rust pub fn allocated_bytes(&self) -> usize ``` -------------------------------- ### ThreadPool::try_spawn_with_exclusivity Source: https://docs.rs/fork_union/latest/fork_union/struct.ThreadPool.html Attempts to create a new thread pool with a specified number of threads and caller exclusivity. ```APIDOC ## ThreadPool::try_spawn_with_exclusivity ### Description Attempts to create a new thread pool with a specified number of threads and caller exclusivity. ### Method `pub fn try_spawn_with_exclusivity(threads: usize, exclusivity: CallerExclusivity) -> Result` ### Arguments * `threads` - Total number of threads including the caller thread. * `exclusivity` - Specifies whether the calling thread participates in work execution. ``` -------------------------------- ### Deprecated Description Method Source: https://docs.rs/fork_union/latest/fork_union/enum.Error.html A deprecated method for getting a string description of the error. It is recommended to use the Display implementation or `to_string()` instead. ```rust fn description(&self) -> &str ``` -------------------------------- ### Create a PinnedVec with Initial Capacity Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Creates a new PinnedVec with a specified initial capacity using the given allocator. Allocation may fail if the system cannot provide the requested memory. ```rust /// let allocator = PinnedAllocator::new(0).expect("Failed to create alloc"); /// let vec = PinnedVec::::with_capacity_in(allocator, 100).expect("Failed to create vec"); /// ``` ``` -------------------------------- ### Get reference to PinnedVec at colocation Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Provides an immutable reference to a `PinnedVec` at a specific NUMA node index. Returns `None` if the index is out of bounds. ```rust pub fn get_colocation(&self, colocation_index: usize) -> Option<&PinnedVec> { self.colocations.get(colocation_index) } ``` -------------------------------- ### Create a New SafePtr Source: https://docs.rs/fork_union/latest/fork_union/struct.SafePtr.html Initializes a new SafePtr instance from a given raw pointer. ```rust pub fn new(ptr: *mut T) -> Self ``` -------------------------------- ### Get Volume of Huge Pages on NUMA Node Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Retrieves the total volume of huge pages available on the NUMA node associated with this allocator. ```rust pub fn volume_huge_pages(&self) -> usize { unsafe { fu_volume_huge_pages_in(self.numa_node) } } ``` -------------------------------- ### Consume BasicSpinMutex to get inner data Source: https://docs.rs/fork_union/latest/fork_union/struct.BasicSpinMutex.html Consumes the mutex, returning the protected data. This bypasses the locking mechanism due to exclusive ownership. ```rust use fork_union::*; let mutex = BasicSpinMutex::::new(42); let data = mutex.into_inner(); assert_eq!(data, 42); ``` -------------------------------- ### capabilities_string_ptr Source: https://docs.rs/fork_union/latest/fork_union/fn.capabilities_string_ptr.html Returns a raw pointer to the capabilities string for no_std environments. ```APIDOC ## Function capabilities_string_ptr ### Description Returns a raw pointer to the capabilities string for no_std environments. ### Signature ```rust pub fn capabilities_string_ptr() -> *const c_char ``` ``` -------------------------------- ### Get NUMA Node from AllocationResult Source: https://docs.rs/fork_union/latest/fork_union/struct.AllocationResult.html Returns the NUMA node on which this memory was allocated. This is useful for optimizing memory access patterns in NUMA systems. ```rust pub fn numa_node(&self) -> usize ``` -------------------------------- ### CloneToUninit Trait Implementation (Nightly) Source: https://docs.rs/fork_union/latest/fork_union/struct.DynamicScheduler.html Nightly-only experimental API for performing copy-assignment to uninitialized memory. ```rust unsafe fn clone_to_uninit(&self, dest: *mut u8) ``` -------------------------------- ### Spawn a ThreadPool Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Creates a new thread pool with a specified number of threads. Panics if the pool cannot be spawned. ```rust pub fn spawn(threads: usize) -> ThreadPool { ThreadPool::try_spawn(threads).expect("Failed to spawn ThreadPool") } ``` -------------------------------- ### Get Mutable Byte Slice from AllocationResult Source: https://docs.rs/fork_union/latest/fork_union/struct.AllocationResult.html Returns the allocated memory as a mutable byte slice. Use this to modify the contents of the allocated memory. ```rust pub fn as_mut_slice(&mut self) -> &mut [u8] ``` -------------------------------- ### Create SyncMutPtr Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Creates a new SyncMutPtr from a mutable raw pointer. ```rust pub const fn new(ptr: *mut T) -> Self { Self { ptr, _marker: PhantomData, } } ``` -------------------------------- ### Get mutable reference to PinnedVec at colocation Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Provides a mutable reference to a `PinnedVec` at a specific NUMA node index. Returns `None` if the index is out of bounds. ```rust pub fn get_colocation_mut(&mut self, colocation_index: usize) -> Option<&mut PinnedVec> { self.colocations.get_mut(colocation_index) } ``` -------------------------------- ### Test PinnedVec Creation in Rust Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Initializes an empty `PinnedVec` using a `PinnedAllocator` and verifies its initial state, including length, capacity, and NUMA node. ```rust let allocator = PinnedAllocator::new(0).expect("Failed to create alloc"); let vec = PinnedVec::::new_in(allocator); assert_eq!(vec.len(), 0); assert_eq!(vec.capacity(), 0); assert_eq!(vec.numa_node(), 0); assert!(vec.is_empty()); ``` -------------------------------- ### Get total capacity across all NUMA nodes Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns the sum of capacities of all `PinnedVec` instances, representing the total memory allocated for the distributed vector. ```rust pub fn capacity(&self) -> usize { self.total_capacity } ``` -------------------------------- ### spawn Source: https://docs.rs/fork_union/latest/fork_union/fn.spawn.html Spawns a pool with the specified number of threads. ```APIDOC ## spawn ### Description Spawns a pool with the specified number of threads. ### Signature ```rust pub fn spawn(threads: usize) -> ThreadPool ``` ### Parameters #### Path Parameters - **threads** (usize) - Required - The number of threads to spawn in the pool. ``` -------------------------------- ### Get Mutable Element or Subslice by Index Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns a mutable reference to an element or subslice based on the index type. Returns None if the index is out of bounds. ```rust pub fn get_mut( &mut self, index: I, ) -> Option<&mut >::Output> where I: core::slice::SliceIndex<[T]>, { self.as_mut_slice().get_mut(index) } ``` -------------------------------- ### Get Volume of Any Pages on NUMA Node Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Retrieves the total volume of any type of pages (huge or regular) available on the NUMA node associated with this allocator. ```rust pub fn volume_any_pages(&self) -> usize { unsafe { fu_volume_any_pages_in(self.numa_node) } } ``` -------------------------------- ### Capabilities Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Functions to retrieve information about the system's capabilities and configuration. ```APIDOC ## capabilities_string ### Description Returns a string describing available platform capabilities. ### Returns - `Option<&'static str>`: A static string slice describing capabilities, or None if unavailable. ## capabilities_string_ptr ### Description Returns a raw pointer to the capabilities string for no_std environments. ### Returns - `*const c_char`: A raw pointer to the capabilities string. ``` -------------------------------- ### ParallelIterator Trait Definition Source: https://docs.rs/fork_union/latest/fork_union/trait.ParallelIterator.html Defines the core interface for parallel iteration, including methods for getting the length, driving parallel execution, and transforming/filtering elements. ```rust pub trait ParallelIterator: Sized { type Item; // Required methods fn len(&self) -> usize; fn drive(self, pool: &mut ThreadPool, schedule: S, consumer: &F) where S: ParallelSchedule, F: Fn(Self::Item, Prong) + Sync; // Provided methods fn is_empty(&self) -> bool { ... } fn drive_static(self, pool: &mut ThreadPool, consumer: F) where F: Fn(Self::Item, Prong) + Sync { ... } fn drive_dynamic(self, pool: &mut ThreadPool, consumer: F) where F: Fn(Self::Item, Prong) + Sync { ... } fn map(self, mapper: M) -> Map where M: Fn(Self::Item) -> U + Sync { ... } fn filter

(self, predicate: P) -> Filter where P: Fn(&Self::Item) -> bool + Sync { ... } } ``` -------------------------------- ### Clone for SyncMutPtr Source: https://docs.rs/fork_union/latest/fork_union/struct.SyncMutPtr.html Provides cloning functionality for SyncMutPtr. ```APIDOC ## impl Clone for SyncMutPtr ### Description Provides cloning functionality for `SyncMutPtr` when the inner type `T` implements `Clone`. ### Methods #### clone Returns a duplicate of the value. ```rust fn clone(&self) -> SyncMutPtr ``` #### clone_from Performs copy-assignment from `source`. ```rust fn clone_from(&mut self, source: &Self) ``` ``` -------------------------------- ### SyncConstPtr::get Source: https://docs.rs/fork_union/latest/fork_union/struct.SyncConstPtr.html Gets a reference to the element at the given index. This is an unsafe operation and requires the caller to ensure the index is within bounds and the data is valid. ```APIDOC ## pub unsafe fn get(&self, index: usize) -> &T Gets a reference to the element at the given index. ### Safety The caller must ensure that: * The index is within bounds of the allocated data * The data at the index is properly initialized * The data remains valid for the lifetime of the returned reference ### Arguments * `index` - The index of the element to access ### Returns A reference to the element at the given index. ``` -------------------------------- ### Clone Implementation for Prong Source: https://docs.rs/fork_union/latest/fork_union/struct.Prong.html Provides methods for cloning Prong instances. ```APIDOC ### impl Clone for Prong #### fn clone(&self) -> Prong Returns a duplicate of the value. #### fn clone_from(&mut self, source: &Self) Performs copy-assignment from `source`. ``` -------------------------------- ### ParallelIterator Implementations for ParallelSliceZip Source: https://docs.rs/fork_union/latest/fork_union/struct.ParallelSliceZip.html Details the implementations of the ParallelIterator trait for ParallelSliceZip, including methods for getting the item type, length, and driving parallel execution. ```APIDOC ### impl<'a, 'b, T, U> ParallelIterator for ParallelSliceZip<'a, 'b, T, U> #### type Item = (&'a T, &'b U) #### fn len(&self) -> usize #### fn drive(self, pool: &mut ThreadPool, schedule: S, consumer: &F) where S: ParallelSchedule, F: Fn(Self::Item, Prong) + Sync, #### fn is_empty(&self) -> bool #### fn drive_static(self, pool: &mut ThreadPool, consumer: F) where F: Fn(Self::Item, Prong) + Sync, #### fn drive_dynamic(self, pool: &mut ThreadPool, consumer: F) where F: Fn(Self::Item, Prong) + Sync, #### fn map(self, mapper: M) -> Map where M: Fn(Self::Item) -> U + Sync, #### fn filter

(self, predicate: P) -> Filter where P: Fn(&Self::Item) -> bool + Sync, ``` -------------------------------- ### From and Into Trait Implementations Source: https://docs.rs/fork_union/latest/fork_union/struct.ForNOperation.html Provides implementations for `From` and `Into` traits, facilitating type conversions. ```APIDOC ### impl From for T ```rust fn from(t: T) -> T ``` Returns the argument unchanged. ### impl Into for T ```rust fn into(self) -> U ``` Calls `U::from(self)`. ``` -------------------------------- ### Get Raw Pointer from AllocationResult Source: https://docs.rs/fork_union/latest/fork_union/struct.AllocationResult.html Returns the raw mutable pointer to the beginning of the allocated memory. Use with caution, as direct pointer manipulation can be unsafe. ```rust pub fn as_ptr(&self) -> *mut u8 ``` -------------------------------- ### Get Mutable Reference to Protected Data Source: https://docs.rs/fork_union/latest/fork_union/struct.BasicSpinMutexGuard.html Returns a mutable reference to the data protected by the mutex. This method is rarely needed as the guard implements DerefMut. ```rust pub fn get_mut(&mut self) -> &mut T ``` -------------------------------- ### Send for SyncMutPtr Source: https://docs.rs/fork_union/latest/fork_union/struct.SyncMutPtr.html Indicates that SyncMutPtr is Send. ```APIDOC ## impl Send for SyncMutPtr ### Description This implementation indicates that `SyncMutPtr` can be safely transferred between threads. This is a crucial trait for concurrent programming in Rust. ``` -------------------------------- ### SyncConstPtr Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html A thread-safe, immutable pointer wrapper. It provides methods to create a new pointer and safely access elements by index. ```APIDOC ## struct SyncConstPtr ### Description A thread-safe, immutable pointer wrapper. ### Methods #### `new(ptr: *const T) -> Self` Creates a new `SyncConstPtr` from a raw pointer. **Safety**: The caller must ensure that: - The pointer is valid for the intended usage duration - The pointed-to data will not be modified during use - The pointer is properly aligned for type `T` #### `get(&self, index: usize) -> &T` Gets a reference to the element at the given index. **Safety**: The caller must ensure that: - The index is within bounds of the allocated data - The data at the index is properly initialized - The data remains valid for the lifetime of the returned reference **Arguments**: - `index` - The index of the element to access **Returns**: A reference to the element at the given index. #### `as_ptr(&self) -> *const T` Returns the raw pointer. ``` -------------------------------- ### Get Immutable Reference to Protected Data Source: https://docs.rs/fork_union/latest/fork_union/struct.BasicSpinMutexGuard.html Returns an immutable reference to the data protected by the mutex. This method is rarely needed as the guard implements Deref. ```rust pub fn get(&self) -> &T ``` -------------------------------- ### BasicSpinMutexGuard::get_mut Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Returns a mutable reference to the data protected by the `BasicSpinMutexGuard`. ```APIDOC ## BasicSpinMutexGuard::get_mut ### Description Returns a mutable reference to the protected data. This method is rarely needed since the guard implements `DerefMut`. ### Signature ```rust pub fn get_mut(&mut self) -> &mut T ``` ### Parameters None ### Returns A mutable reference to the protected data. ### Examples ```rust // Example usage within the context of acquiring a lock ``` ``` -------------------------------- ### ParallelExactIter new constructor Source: https://docs.rs/fork_union/latest/src/fork_union/lib.rs.html Creates a new ParallelExactIter with a specified length and an indexing function. This iterator generates items based on their index. ```rust pub fn new(len: usize, indexer: I) -> Self { Self { len, indexer, _marker: PhantomData, } } ``` -------------------------------- ### Get NUMA Node Count Source: https://docs.rs/fork_union/latest/fork_union/fn.count_numa_nodes.html Call this function to determine the number of NUMA nodes present on the system. This can be useful for performance tuning and resource allocation. ```rust pub fn count_numa_nodes() -> usize ```