pub struct Arena<T> { /* private fields */ }
Expand description
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);
Implementations§
Source§impl<T> Arena<T>
impl<T> Arena<T>
Sourcepub fn with_capacity(n: usize) -> Arena<T>
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);
Sourcepub fn len(&self) -> usize
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);
Sourcepub fn alloc(&self, value: T) -> &mut T
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);
Sourcepub fn alloc_extend<I>(&self, iterable: I) -> &mut [T]where
I: IntoIterator<Item = T>,
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']);
Sourcepub unsafe fn alloc_uninitialized(&self, num: usize) -> &mut [MaybeUninit<T>]
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()]);
}
Sourcepub fn reserve_extend(&self, num: usize)
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.
Sourcepub fn uninitialized_array(&self) -> *mut [MaybeUninit<T>]
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.
Sourcepub fn into_vec(self) -> Vec<T>
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"]);
Sourcepub fn iter_mut(&mut self) -> IterMut<'_, 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;
Source§impl Arena<u8>
impl Arena<u8>
Sourcepub fn alloc_str(&self, s: &str) -> &mut str
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);