Struct coca::arena::Arena

pub struct Arena<'src> { /* fields omitted */ }

A memory arena, also known as a region-based allocator, or bump allocator.

See the the module-level documentation for more.

Implementations

impl<'src> Arena<'src>

pub fn bytes_remaining(&self) -> usize

Calculates the size of the space remaining in the arena in bytes.

An allocation is not guaranteed to succeed even when the returned value is greater than or equal to the requested number of bytes, because proper alignment may require additional padding. Use the try_ methods to handle allocation failure.

pub fn make_sub_arena(&mut self) -> Arena<'_>

Constructs a new Arena allocating out of the free space remaining in self. self cannot be used for allocation until the new arena is dropped.

Examples

use core::mem::MaybeUninit;
use coca::Arena;

let mut backing_region = [MaybeUninit::uninit(); 1024];
let mut arena = Arena::from(&mut backing_region[..]);

{
    let mut tmp = arena.make_sub_arena();
    let arr = tmp.alloc([0u32; 200]);              // this takes up 800 / 1024 bytes...
    assert!(tmp.try_alloc([0u32; 100]).is_none()); // ...so this can't succeed
}

// tmp was dropped, so the memory can be reused:
assert!(arena.try_alloc([0u32; 200]).is_some());

pub fn alloc_default<T: Default + Sized>(&mut self) -> Box<'src, T>

Allocates memory in the arena and then places the Default value for T into it.

Panics

Panics if the remaining space in the arena is insufficient. See try_alloc_default for a checked version that never panics.

pub fn try_alloc_default<T: Default + Sized>(&mut self) -> Option<Box<'src, T>>

Allocates memory in the arena and then places the Default value for T into it.

Returns None if the remaining space in the arena is insufficient.

Examples

use core::mem::MaybeUninit;
use coca::Arena;

let mut backing_region = [MaybeUninit::uninit(); 1024];
let mut arena = Arena::from(&mut backing_region[..]);

loop {
    if let Some(ptr) = arena.try_alloc_default::<u128>() {
        assert_eq!(*ptr, 0);
    } else {
        break;
    }
}

assert!(arena.bytes_remaining() < 32);

pub fn alloc<T: Sized>(&mut self, x: T) -> Box<'src, T>

Allocates memory in the arena and then places x into it.

Panics

Panics if the remaining space in the arena is insufficient. See try_alloc for a checked version that never panics.

pub fn try_alloc<T: Sized>(&mut self, x: T) -> Option<Box<'src, T>>

Allocates memory in the arena and then places x into it.

Returns None if the remaining space in the arena is insufficient.

Examples

use core::mem::MaybeUninit;
use coca::Arena;

let mut backing_region = [MaybeUninit::uninit(); 1024];
let mut arena = Arena::from(&mut backing_region[..]);

loop {
    if let Some(ptr) = arena.try_alloc(0xDEAD_BEEFu32) {
        assert_eq!(*ptr, 0xDEAD_BEEF);
    } else {
        break;
    }
}

assert!(arena.bytes_remaining() < 8);

pub fn reserve<T: Sized>(&mut self) -> Box<'src, MaybeUninit<T>>

Allocates memory in the arena, leaving it uninitialized.

Panics

Panics if the remaining space in the arena is insufficient. See try_reserve for a checked version that never panics.

pub fn try_reserve<T: Sized>(&mut self) -> Option<Box<'src, MaybeUninit<T>>>

Allocates memory in the arena, leaving it uninitialized.

Returns None if the remaining space in the arena is insufficient.

Examples

use core::mem::MaybeUninit;
use coca::Arena;

let mut backing_region = [MaybeUninit::uninit(); 1024];
let mut arena = Arena::from(&mut backing_region[..]);

let total = {
    let reserved = arena.try_reserve::<i32>()?;
    let mut tmp = arena.make_sub_arena();
    let a = tmp.alloc(5);
    let b = tmp.alloc(7);
    reserved.init(*a + *b)
};

assert_eq!(*total, 12);

pub fn reserve_array<T: Sized>(
    &mut self,
    count: usize
) -> Box<'src, [MaybeUninit<T>]>

Allocates memory in the arena, leaving it uninitialized.

Panics

Panics if the remaining space in the arena is insufficient. See try_reserve_array for a checked version that never panics.

pub fn try_reserve_array<T: Sized>(
    &mut self,
    count: usize
) -> Option<Box<'src, [MaybeUninit<T>]>>

Allocates memory in the arena, leaving it uninitialized.

Returns None if the remaining space in the arena is insufficient.

Examples

use core::mem::MaybeUninit;
use coca::Arena;

let mut backing_region = [MaybeUninit::uninit(); 1024];
let mut arena = Arena::from(&mut backing_region[..]);

let sums = arena
    .try_reserve_array::<usize>(100)?
    .init_with(|n| (n * (n + 1)) / 2);
assert!(arena.try_reserve_array::<usize>(100).is_none());

assert_eq!(&sums[..10], [0, 1, 3, 6, 10, 15, 21, 28, 36, 45]);
assert_eq!(sums.last(), Some(&4950));

pub fn array_default<T>(&mut self, count: usize) -> Box<'src, [T]> where
    T: Default + Sized, 

Allocates memory in the arena and then places count copies of the Default value for T into it.

Consider using alloc_default<[T; count]> instead when count is known at compile time.

Panics

Panics if the remaining space in the arena is insufficient. See try_array_default for a checked version that never panics.

pub fn try_array_default<T>(&mut self, count: usize) -> Option<Box<'src, [T]>> where
    T: Default + Sized, 

Allocates memory in the arena and then places count copies of the Default value for T into it.

Returns None if the remaining space in the arena is insufficient.

Consider using try_alloc_default<[T; count]> instead when count is known at compile time.

Examples

use core::mem::MaybeUninit;
use coca::Arena;

let mut backing_region = [MaybeUninit::uninit(); 1024];
let mut arena = Arena::from(&mut backing_region[..]);
let array = arena.try_array_default::<u128>(16)?;
assert_eq!(&array[..], &[0; 16]);

pub fn array<T>(&mut self, x: T, count: usize) -> Box<'src, [T]> where
    T: Copy + Sized, 

Allocates memory in the arena and then places count copies of x into it.

Consider using alloc([x; count]) instead when count is known at compile time.

Panics

Panics if the remaining space in the arena is insufficient. See try_array for a checked version that never panics.

pub fn try_array<T>(&mut self, x: T, count: usize) -> Option<Box<'src, [T]>> where
    T: Copy + Sized, 

Allocates memory in the arena and then places count copies of x into it.

Returns None if the remaining space in the arena is insufficient.

Consider using try_alloc([x; count]) instead when count is known at compile time.

Examples

use core::mem::MaybeUninit;
use coca::Arena;

let mut backing_region = [MaybeUninit::uninit(); 1024];
let mut arena = Arena::from(&mut backing_region[..]);
let array = arena.try_array(0x12345678u32, 200)?;
assert_eq!(&array[..], &[0x12345678u32; 200]);

pub fn vec<T, I: Capacity>(&mut self, capacity: I) -> ArenaVec<'src, T, I>

Constructs a ArenaVec with the given capacity.

Panics

Panics if the specified capacity cannot be represented by a usize, or if the remaining space in the arena is insufficient. See try_vec for a checked version.

pub fn try_vec<T, I: Capacity>(
    &mut self,
    capacity: I
) -> Option<ArenaVec<'src, T, I>>

Constructs an ArenaVec with the given capacity.

Returns None if the remaining space in the arena is insufficient.

Panics

Panics if the specified capacity cannot be represented by a usize.

Examples

use coca::Arena;
use core::mem::MaybeUninit;

let mut backing_region = [MaybeUninit::uninit(); 1024];
let mut arena = Arena::from(&mut backing_region[..]);

let mut squares = arena.try_vec::<i64, usize>(100)?;
assert!(arena.try_vec::<i64, usize>(100).is_none());

assert_eq!(squares.len(), 0);
assert_eq!(squares.capacity(), 100);

for x in 1..=100 { squares.push(x * x) }
assert_eq!(&squares[..8], &[1, 4, 9, 16, 25, 36, 49, 64]);

pub fn heap<T: Ord, I: Capacity>(
    &mut self,
    capacity: I
) -> ArenaHeap<'src, T, I>

Constructs a ArenaHeap with the given capacity.

Panics

Panics if the specified capacity cannot be represented by a usize, or if the remaining space in the arena is insufficient. See try_heap for a checked version.

pub fn try_heap<T: Ord, I: Capacity>(
    &mut self,
    capacity: I
) -> Option<ArenaHeap<'src, T, I>>

Constructs an ArenaHeap with the given capacity.

Returns None if the remaining space in the arena is insufficient.

Panics

Panics if the specified capacity cannot be represented by a usize.

Examples

use coca::Arena;
use core::mem::MaybeUninit;

let mut backing_region = [MaybeUninit::uninit(); 1024];
let mut arena = Arena::from(&mut backing_region[..]);

let mut heap = arena.try_heap::<i64, usize>(100)?;
assert!(arena.try_heap::<i64, usize>(100).is_none());

assert_eq!(heap.len(), 0);
assert_eq!(heap.capacity(), 100);

for x in 1..=100 { heap.push(x) }
for x in (1..=100).rev() {
    assert_eq!(heap.pop(), Some(x));
}

pub fn deque<T, I: Capacity>(&mut self, capacity: I) -> ArenaDeque<'src, T, I>

Constructs a ArenaDeque with the given capacity.

Panics

Panics if the specified capacity cannot be represented by a usize, or if the remaining space in the arena is insufficient. See try_deque for a checked version.

pub fn try_deque<T, I: Capacity>(
    &mut self,
    capacity: I
) -> Option<ArenaDeque<'src, T, I>>

Constructs a new ArenaDeque with the given capacity.

Returns None if the remaining space in the arena is insufficient.

Panics

Panics if the specified capacity cannot be represented by a usize.

Examples

use coca::Arena;
use core::mem::MaybeUninit;

let mut backing_region = [MaybeUninit::uninit(); 1024];
let mut arena = Arena::from(&mut backing_region[..]);

let mut deque = arena.try_deque::<i64, usize>(100)?;
assert!(arena.try_deque::<i64, usize>(100).is_none());

assert_eq!(deque.len(), 0);
assert_eq!(deque.capacity(), 100);

for x in 1..=100 { deque.push_back(x) }
for x in 1..=100 {
    assert_eq!(deque.pop_front(), Some(x));
}

pub fn collect<T, I>(&mut self, iter: I) -> Box<'src, [T]> where
    T: Sized,
    I: IntoIterator<Item = T>, 

Transforms an iterator into a boxed slice in the arena.

Panics

Panics if the remaining space in the arena is insufficient to exhaust the iterator. See try_collect for a checked version that never panics.

pub fn try_collect<T, I>(&mut self, iter: I) -> Option<Box<'src, [T]>> where
    T: Sized,
    I: IntoIterator<Item = T>, 

Transforms an iterator into a boxed slice in the arena.

Returns None if the remaining space in the arena is insufficient to exhaust the iterator.

Examples

use core::mem::{MaybeUninit, size_of, size_of_val};
use coca::Arena;

let mut backing_region = [MaybeUninit::uninit(); 1024];
let mut arena = Arena::from(&mut backing_region[..]);

let a = [1, 2, 3];
let doubled = arena.try_collect(a.iter().map(|&x| x * 2))?;

assert_eq!(&doubled[..], &[2, 4, 6]);

pub fn make_writer<'a>(&'a mut self) -> Writer<'a, 'src>

Constructs a new Writer backed by the free space remaining in self.

The arena cannot be used for allocation until the writer is dropped.

Primarily intended for use in expansions of fmt!. This should only be used explicitly where format strings don't work as well.

Examples

use coca::{Arena, Box};
use core::{fmt::Write, mem::MaybeUninit};

let parts = ["Hello", ",", " ", "World", "!"];
let mut backing_region = [MaybeUninit::uninit(); 1024];
let mut arena = Arena::from(&mut backing_region[..]);

let mut writer = arena.make_writer();
for s in parts.iter() {
    writer.write_str(s)?;
}

let combined: Box::<'_, str> = writer.into();
assert_eq!(combined.as_ref(), "Hello, World!");

impl Arena<'_>

pub fn utilization(&self) -> UtilizationProfile

Returns a profile of all allocations from the arena and all sub-arenas created from it.

Examples

use core::mem::MaybeUninit;
use coca::Arena;

let mut backing_region = [MaybeUninit::uninit(); 256];
let mut arena = Arena::from(&mut backing_region[..]);

{
    let mut tmp = arena.make_sub_arena();
    let _ = tmp.array_default::<u8>(100);
}
{
    let mut tmp = arena.make_sub_arena();
    let _ = tmp.array_default::<u8>(50);
    let _ = tmp.try_array_default::<u8>(200);
}
{
    let mut tmp = arena.make_sub_arena();
    let _ = tmp.array_default::<u8>(200);
}

let profile = arena.utilization();
assert_eq!(profile.peak_utilization, 200);
assert_eq!(profile.allocation_count, 4);
assert_eq!(profile.failed_allocations, 1);

Trait Implementations

impl Debug for Arena<'_>

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'src> From<&'src mut [MaybeUninit<u8>]> for Arena<'src>

pub fn from(buf: &mut [MaybeUninit<u8>]) -> Self

Constructs a new Arena allocating out of buf.

Panics

When compiled with the profile feature, panics if buf is too small to fit the profiling meta data. The exact threshold depends on the size of usize on the target platform, and the alignment of buf, but this is guaranteed to succeed if buf.len() >= 40.

Examples

use core::mem::MaybeUninit;
use coca::Arena;

let mut backing_region = [MaybeUninit::uninit(); 1024];
let arena = Arena::from(&mut backing_region[..]);