The caller must ensure that:

• T has the correct alignment for the allocated memory
• The allocation is large enough to hold the requested number of T elements
• The memory is properly initialized before use

The caller must ensure that:

• T has the correct alignment for the allocated memory
• The allocation contains valid data of type T

• memory_domain_id - The OS memory-domain ID from Topology::memory_domain_id_at_index

Returns None if the ID is the -1 sentinel, i.e. it names no domain.

use forkunion::*;

let topology = Topology::new().unwrap();
// Bind an allocator to the first memory domain
let id = topology.memory_domain_id_at_index(MemoryDomain(0)).unwrap();
let allocator = DomainAllocator::new(id).expect("memory domain 0 should be available");

// Bind another to a second memory domain when the machine has one
let memory_domains = topology.memory_domains_count().unwrap();
if memory_domains > 1 {
    let id2 = topology.memory_domain_id_at_index(MemoryDomain(1)).unwrap();
    let allocator2 = DomainAllocator::new(id2).expect("memory domain 1 should be available");
    println!("Bound allocator to memory domain: {}", allocator2.memory_domain_id().get());
}

• minimum_bytes - The minimum number of bytes to allocate

Reports InvalidArgument for a zero request, and the core's own status otherwise.

use forkunion::*;

let topology = Topology::new().unwrap();
let allocator = DomainAllocator::new(topology.memory_domain_id_at_index(MemoryDomain(0)).unwrap()).unwrap();
let allocation = allocator.allocate_at_least(1024).expect("Failed to allocate memory");

println!("Requested 1024 bytes, got {} bytes on {} byte pages",
         allocation.allocated_bytes(), allocation.bytes_per_page());

// The allocation might be larger than requested due to page alignment
assert!(allocation.allocated_bytes() >= 1024);

// Access the memory as a byte slice
let memory = allocation.as_slice();
println!("Can access {} bytes of memory", memory.len());

• bytes - The exact number of bytes to allocate

Reports InvalidArgument for a zero request, and the core's own status otherwise.

use forkunion::*;

let topology = Topology::new().unwrap();
let id = topology.memory_domain_id_at_index(MemoryDomain(0)).unwrap();
let allocator = DomainAllocator::new(id).unwrap();
let allocation = allocator.allocate(1024).expect("Failed to allocate memory");
assert_eq!(allocation.allocated_bytes(), 1024);

// Write some data to the allocated memory
let mut allocation = allocation; // Make mutable
let memory = allocation.as_mut_slice();
memory[0] = 42;
memory[1023] = 255;

// Verify the data was written
assert_eq!(memory[0], 42);
assert_eq!(memory[1023], 255);

• count - The number of elements to allocate space for

use forkunion::*;

let topology = Topology::new().unwrap();
let allocator = DomainAllocator::new(topology.memory_domain_id_at_index(MemoryDomain(0)).unwrap()).unwrap();
let mut allocation = allocator.allocate_for::<u64>(100).expect("Failed to allocate");

// Verify the allocation size first
assert_eq!(allocation.allocated_bytes(), 100 * std::mem::size_of::<u64>());

// Access as typed slice
let slice = unsafe { allocation.as_mut_slice_of::<u64>() };
slice[0] = 42;
slice[99] = 12345;

// Read back the values
assert_eq!(slice[0], 42);
assert_eq!(slice[99], 12345);

• min_count - The minimum number of elements to allocate space for

use forkunion::*;

let topology = Topology::new().unwrap();
let allocator = DomainAllocator::new(topology.memory_domain_id_at_index(MemoryDomain(0)).unwrap()).unwrap();
let mut allocation = allocator.allocate_for_at_least::<u32>(1000).expect("Failed to allocate");
let actual_count = allocation.allocated_bytes() / std::mem::size_of::<u32>();
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::<u32>() };
for i in 0..1000 {
    slice[i] = i as u32;
}

// Verify initialization
assert_eq!(slice[0], 0);
assert_eq!(slice[999], 999);

• allocator - The DomainAllocator to use for memory allocation

use forkunion::*;

let topology = Topology::new().unwrap();
let allocator = DomainAllocator::new(topology.memory_domain_id_at_index(MemoryDomain(0)).unwrap()).expect("Failed to create alloc");
let vec = PinnedVec::<i32>::new_in(allocator);
assert_eq!(vec.len(), 0);
assert_eq!(vec.capacity(), 0);

• allocator - The DomainAllocator to use for memory allocation
• capacity - The initial capacity to allocate

Returns None if allocation fails.

use forkunion::*;

let topology = Topology::new().unwrap();
let allocator = DomainAllocator::new(topology.memory_domain_id_at_index(MemoryDomain(0)).unwrap()).expect("Failed to create alloc");
let vec = PinnedVec::<i32>::with_capacity_in(allocator, 100).expect("Failed to create vec");
assert_eq!(vec.len(), 0);
assert_eq!(vec.capacity(), 100);

• additional - The number of additional elements to reserve space for

Returns an error if allocation fails.

use forkunion::*;

let topology = Topology::new().unwrap();
let allocator = DomainAllocator::new(topology.memory_domain_id_at_index(MemoryDomain(0)).unwrap()).expect("Failed to create alloc");
let mut vec = PinnedVec::<i32>::new_in(allocator);
vec.reserve(10).expect("Failed to reserve");
assert!(vec.capacity() >= 10);

• value - The element to append

Returns an error if allocation fails when growing the vector.

use forkunion::*;

let topology = Topology::new().unwrap();
let allocator = DomainAllocator::new(topology.memory_domain_id_at_index(MemoryDomain(0)).unwrap()).expect("Failed to create alloc");
let mut vec = PinnedVec::<i32>::new_in(allocator);
vec.push(42).expect("Failed to push");
assert_eq!(vec.len(), 1);
assert_eq!(vec[0], 42);

use forkunion::*;

let topology = Topology::new().unwrap();
let allocator = DomainAllocator::new(topology.memory_domain_id_at_index(MemoryDomain(0)).unwrap()).expect("Failed to create alloc");
let mut vec = PinnedVec::<i32>::new_in(allocator);
vec.push(42).expect("Failed to push");
assert_eq!(vec.pop(), Some(42));
assert_eq!(vec.pop(), None);

use forkunion::*;

let topology = Topology::new().unwrap();
let allocator = DomainAllocator::new(topology.memory_domain_id_at_index(MemoryDomain(0)).unwrap()).expect("Failed to create alloc");
let mut vec = PinnedVec::<i32>::new_in(allocator);
vec.push(42).expect("Failed to push");
vec.clear();
assert_eq!(vec.len(), 0);

• index - The position to insert at
• element - The element to insert

Panics if index > len.

Returns an error if allocation fails when growing the vector.

• index - The position to remove from

Panics if index >= len.

• other - The slice to copy elements from

Returns an error if allocation fails when growing the vector.

• value - The value to fill the vector with

use forkunion::*;

let topology = Topology::new().unwrap();
let allocator = DomainAllocator::new(topology.memory_domain_id_at_index(MemoryDomain(0)).unwrap()).expect("Failed to create alloc");
let mut vec = PinnedVec::<i32>::with_capacity_in(allocator, 5).expect("Failed to create vec");
vec.resize(5, 0).expect("Failed to resize");
vec.fill(42);
assert_eq!(vec.as_slice(), &[42, 42, 42, 42, 42]);

• f - A closure that generates values to fill the vector with

use forkunion::*;

let topology = Topology::new().unwrap();
let allocator = DomainAllocator::new(topology.memory_domain_id_at_index(MemoryDomain(0)).unwrap()).expect("Failed to create alloc");
let mut vec = PinnedVec::<i32>::with_capacity_in(allocator, 5).expect("Failed to create vec");
vec.resize(5, 0).expect("Failed to resize");
vec.fill_with(|| 42);
assert_eq!(vec.as_slice(), &[42, 42, 42, 42, 42]);