Struct typed_arena::Arena

pub struct Arena<T> { /* fields omitted */ }

An arena of objects of type T.

Example

use typed_arena::Arena;

struct Monster {
    level: u32,
}

let monsters = Arena::new();

let vegeta = monsters.alloc(Monster { level: 9001 });
assert!(vegeta.level > 9000);

Methods

impl<T> Arena<T>

pub fn new() -> Arena<T>

Construct a new arena.

Example

use typed_arena::Arena;

let arena = Arena::new();

pub fn with_capacity(n: usize) -> Arena<T>

Construct a new arena with capacity for n values pre-allocated.

Example

use typed_arena::Arena;

let arena = Arena::with_capacity(1337);

pub fn len(&self) -> usize

Return the size of the arena

This is useful for using the size of previous typed arenas to build new typed arenas with large enough spaces.

Example

 use typed_arena::Arena;

 let arena = Arena::with_capacity(0);
 let a = arena.alloc(1);
 let b = arena.alloc(2);

 assert_eq!(arena.len(), 2);

pub fn alloc(&self, value: T) -> &mut T

Allocates a value in the arena, and returns a mutable reference to that value.

Example

use typed_arena::Arena;

let arena = Arena::new();
let x = arena.alloc(42);
assert_eq!(*x, 42);

pub fn alloc_extend<I>(&self, iterable: I) -> &mut [T] where
    I: IntoIterator<Item = T>, 

Uses the contents of an iterator to allocate values in the arena. Returns a mutable slice that contains these values.

Example

use typed_arena::Arena;

let arena = Arena::new();
let abc = arena.alloc_extend("abcdefg".chars().take(3));
assert_eq!(abc, ['a', 'b', 'c']);

pub unsafe fn alloc_uninitialized(&self, num: usize) -> &mut [MaybeUninit<T>]

Allocates space for a given number of values, but doesn't initialize it.

Safety

After calling this method, the arena considers the elements initialized. If you fail to initialize them (which includes because of panicking during the initialization), the arena will run destructors on the uninitialized memory. Therefore, you must initialize them.

Considering how easy it is to cause undefined behaviour using this, you're advised to prefer the other (safe) methods, like alloc_extend.

Example

use std::mem::{self, MaybeUninit};
use std::ptr;
use typed_arena::Arena;

// Transmute from MaybeUninit slice to slice of initialized T.
// It is a separate function to preserve the lifetime of the reference.
unsafe fn transmute_uninit<A>(r: &mut [MaybeUninit<A>]) -> &mut [A] {
    mem::transmute(r)
}

let arena: Arena<bool> = Arena::new();
let slice: &mut [bool];
unsafe {
    let uninitialized = arena.alloc_uninitialized(10);
    for elem in uninitialized.iter_mut() {
        ptr::write(elem.as_mut_ptr(), true);
    }
    slice = transmute_uninit(uninitialized);
}

Alternative allocation pattern

To avoid the problem of dropping assumed to be initialized elements on panic, it is also possible to combine the reserve_extend with uninitialized_array, initialize the elements and confirm them by this method. In such case, when there's a panic during initialization, the already initialized elements would leak but it wouldn't cause UB.

use std::mem::{self, MaybeUninit};
use std::ptr;
use typed_arena::Arena;

unsafe fn transmute_uninit<A>(r: &mut [MaybeUninit<A>]) -> &mut [A] {
    mem::transmute(r)
}

const COUNT: usize = 2;

let arena: Arena<String> = Arena::new();

arena.reserve_extend(COUNT);
let slice: &mut [String];
unsafe {
    // Perform initialization before we claim the memory.
    let uninitialized = arena.uninitialized_array();
    assert!((*uninitialized).len() >= COUNT); // Ensured by the reserve_extend
    for elem in &mut (*uninitialized)[..COUNT] {
        ptr::write(elem.as_mut_ptr(), "Hello".to_owned());
    }
    let addr = (*uninitialized).as_ptr() as usize;

    // The alloc_uninitialized returns the same memory, but "confirms" its allocation.
    slice = transmute_uninit(arena.alloc_uninitialized(COUNT));
    assert_eq!(addr, slice.as_ptr() as usize);
    assert_eq!(slice, &["Hello".to_owned(), "Hello".to_owned()]);
}

pub fn reserve_extend(&self, num: usize)

Makes sure there's enough continuous space for at least num elements.

This may save some work if called before alloc_extend. It also allows somewhat safer use pattern of alloc_uninitialized. On the other hand this might waste up to n - 1 elements of space. In case new allocation is needed, the unused ones in current chunk are never used.

pub fn uninitialized_array(&self) -> *mut [MaybeUninit<T>]

Returns unused space.

This unused space is still not considered "allocated". Therefore, it won't be dropped unless there are further calls to alloc, alloc_uninitialized, or alloc_extend which is why the method is safe.

It returns a raw pointer to avoid creating multiple mutable references to the same place. It is up to the caller not to dereference it after any of the alloc_ methods are called.

pub fn into_vec(self) -> Vec<T>

Convert this Arena into a Vec<T>.

Items in the resulting Vec<T> appear in the order that they were allocated in.

Example

use typed_arena::Arena;

let arena = Arena::new();

arena.alloc("a");
arena.alloc("b");
arena.alloc("c");

let easy_as_123 = arena.into_vec();

assert_eq!(easy_as_123, vec!["a", "b", "c"]);

Important traits for IterMut<'a, T>

impl<'a, T> Iterator for IterMut<'a, T> type Item = &'a mut T;

pub fn iter_mut(&mut self) -> IterMut<T>

Returns an iterator that allows modifying each value.

Items are yielded in the order that they were allocated.

Example

use typed_arena::Arena;

#[derive(Debug, PartialEq, Eq)]
struct Point { x: i32, y: i32 };

let mut arena = Arena::new();

arena.alloc(Point { x: 0, y: 0 });
arena.alloc(Point { x: 1, y: 1 });

for point in arena.iter_mut() {
    point.x += 10;
}

let points = arena.into_vec();

assert_eq!(points, vec![Point { x: 10, y: 0 }, Point { x: 11, y: 1 }]);

Immutable Iteration

Note that there is no corresponding iter method. Access to the arena's contents requries mutable access to the arena itself.

use typed_arena::Arena;

let mut arena = Arena::new();
let x = arena.alloc(1);

// borrow error!
for i in arena.iter_mut() {
    println!("i: {}", i);
}

// borrow error!
*x = 2;

impl Arena<u8>

pub fn alloc_str(&self, s: &str) -> &mut str

Allocates a string slice and returns a mutable reference to it.

This is on Arena<u8>, because string slices use byte slices ([u8]) as their backing storage.

Example

use typed_arena::Arena;

let arena: Arena<u8> = Arena::new();
let hello = arena.alloc_str("Hello world");
assert_eq!("Hello world", hello);

Trait Implementations

impl<T> Default for Arena<T>

fn default() -> Self

Returns the "default value" for a type.