Struct ExBox

Source

pub struct ExBox<'a, T> { /* private fields */ }

Expand description

A pointer type for a single heap-allocated value with an explicit allocator.

§Ownership and Dropping

ExBox uniquely owns the value it points to. On drop:

T’s destructor is called via drop_in_place.
The backing memory is returned to the allocator.

§Zero-Sized Types

For ZSTs (size_of::<T>() == 0) no allocation is performed; ptr is set to NonNull::dangling() and dealloc is not called on drop.

§Lifetime

The allocator reference 'a must outlive the ExBox.

Implementations§

Source §

impl<'a, T> ExBox<'a, T>

Source

pub fn new(value: T, alloc: &'a dyn Allocator) -> Option<Self>

Allocates memory for T and moves value into it.

Returns None if the allocator fails.

§Example

let b = ExBox::new(42u64, &sys).unwrap();
assert_eq!(*b, 42);

Examples found in repository ?

examples/box.rs (line 7)

4fn main() {
5    let alloc = SystemAllocator;
6
7    let boxed_int = ExBox::new(1337, &alloc).expect("Out of memory");
8
9    println!("Value: {}", *boxed_int);
10    
11    let val = ExBox::unbox(boxed_int);
12    println!("Unboxed: {}", val);
13}

More examples

Hide additional examples

examples/full.rs (line 14)

9fn main() {
10    let sys = CountingAllocator::new(SystemAllocator);
11    
12    println!("=== ExBox & SystemAllocator ===");
13    {
14        let b = ExBox::new(42, &sys).expect("Failed to alloc Box");
15        println!("Box value: {}", *b);
16    }
17    
18    let stats = sys.stats();
19    println!("Allocated: {} bytes", stats.bytes_allocated);
20    println!("Deallocated: {} bytes", stats.bytes_freed);
21    println!("Live bytes: {}\n", stats.bytes_live);
22
23    println!("=== ExVec & Arena (Linear Allocation) ===");
24    {
25        let arena = ArenaAllocator::new(&sys);
26        
27        let mut v = ExVec::new(&arena);
28        for i in 0..5 {
29            v.push(i * 10);
30        }
31        println!("Vec: {:?}", v.as_slice());
32        
33        arena.reset();
34        println!("Arena reset performed");
35    }
36
37    println!("\n=== ExString & Pool (Fixed Size Blocks) ===");
38    {
39        let pool = PoolAllocator::typed::<[u8; 64]>(&sys, 10)
40            .expect("Failed to create Pool");
41        
42        let mut s = ExString::new(&pool);
43        s.push_str("Hello from ZigZag!");
44        
45        println!("String in Pool: {}", s.as_str());
46        println!("Pool free slots: {}", pool.free_count());
47    }
48
49    println!("\n=== Final Global Stats ===");
50    let final_stats = sys.stats();
51    println!("Total count of alloc() calls: {}", final_stats.allocs);
52    println!("Total count of dealloc() calls: {}", final_stats.deallocs);
53    println!("Total bytes allocated: {}", final_stats.bytes_allocated);
54    println!("Total bytes freed: {}", final_stats.bytes_freed);
55    println!("Current leak/live size: {} bytes", final_stats.bytes_live);
56}

Source

pub fn new_zeroed(value: T, alloc: &'a dyn Allocator) -> Option<Self>

Allocates zero-filled memory for T, then moves value into it.

The allocation is zeroed before value is written, which may be useful for types with padding bytes that should be deterministic.

Returns None if the allocator fails.

Source

pub fn unbox(b: Self) -> T

Consumes the box, returns the inner value, and deallocates the backing memory.

§Implementation Note

We read the value out of the pointer and then call mem::forget on the ExBox to prevent the Drop implementation from running a second destructor or freeing the (already freed) memory.

Examples found in repository ?

examples/box.rs (line 11)

4fn main() {
5    let alloc = SystemAllocator;
6
7    let boxed_int = ExBox::new(1337, &alloc).expect("Out of memory");
8
9    println!("Value: {}", *boxed_int);
10    
11    let val = ExBox::unbox(boxed_int);
12    println!("Unboxed: {}", val);
13}

Source

pub unsafe fn wipe(b: &mut Self)

Zeroes all bytes of the allocation in-place (without moving or dropping T).

§Safety

After this call, the memory backing *b contains all zeros. If T has any validity invariants (e.g. non-null pointers, non-zero discriminants) those invariants will be violated. Accessing *b after calling wipe is undefined behaviour unless T is a type for which all-zeros is a valid representation.

Source