Struct Arena

pub struct Arena { /* private fields */ }

Arena allocator

Methods from Deref<Target = Bump>

pub fn allocation_limit(&self) -> Option<usize>

The allocation limit for this arena in bytes.

Example

let bump = bumpalo::Bump::with_capacity(0);

assert_eq!(bump.allocation_limit(), None);

bump.set_allocation_limit(Some(6));

assert_eq!(bump.allocation_limit(), Some(6));

bump.set_allocation_limit(None);

assert_eq!(bump.allocation_limit(), None);

pub fn set_allocation_limit(&self, limit: Option<usize>)

Set the allocation limit in bytes for this arena.

The allocation limit is only enforced when allocating new backing chunks for a Bump. Updating the allocation limit will not affect existing allocations or any future allocations within the Bump’s current chunk.

Example

let bump = bumpalo::Bump::with_capacity(0);

bump.set_allocation_limit(Some(0));

assert!(bump.try_alloc(5).is_err());

pub fn reset(&mut self)

Reset this bump allocator.

Performs mass deallocation on everything allocated in this arena by resetting the pointer into the underlying chunk of memory to the start of the chunk. Does not run any Drop implementations on deallocated objects; see the top-level documentation for details.

If this arena has allocated multiple chunks to bump allocate into, then the excess chunks are returned to the global allocator.

Example

let mut bump = bumpalo::Bump::new();

// Allocate a bunch of things.
{
    for i in 0..100 {
        bump.alloc(i);
    }
}

// Reset the arena.
bump.reset();

// Allocate some new things in the space previously occupied by the
// original things.
for j in 200..400 {
    bump.alloc(j);
}

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

Allocate an object in this Bump and return an exclusive reference to it.

Panics

Panics if reserving space for T fails.

Example

let bump = bumpalo::Bump::new();
let x = bump.alloc("hello");
assert_eq!(*x, "hello");

pub fn try_alloc<T>(&self, val: T) -> Result<&mut T, AllocErr>

Try to allocate an object in this Bump and return an exclusive reference to it.

Errors

Errors if reserving space for T fails.

Example

let bump = bumpalo::Bump::new();
let x = bump.try_alloc("hello");
assert_eq!(x, Ok(&mut "hello"));

pub fn alloc_with<F, T>(&self, f: F) -> &mut T

where F: FnOnce() -> T,

Pre-allocate space for an object in this Bump, initializes it using the closure, then returns an exclusive reference to it.

See The _with Method Suffix for a discussion on the differences between the _with suffixed methods and those methods without it, their performance characteristics, and when you might or might not choose a _with suffixed method.

Panics

Panics if reserving space for T fails.

Example

let bump = bumpalo::Bump::new();
let x = bump.alloc_with(|| "hello");
assert_eq!(*x, "hello");

pub fn try_alloc_with<F, T>(&self, f: F) -> Result<&mut T, AllocErr>

where F: FnOnce() -> T,

Tries to pre-allocate space for an object in this Bump, initializes it using the closure, then returns an exclusive reference to it.

See The _with Method Suffix for a discussion on the differences between the _with suffixed methods and those methods without it, their performance characteristics, and when you might or might not choose a _with suffixed method.

Errors

Errors if reserving space for T fails.

Example

let bump = bumpalo::Bump::new();
let x = bump.try_alloc_with(|| "hello");
assert_eq!(x, Ok(&mut "hello"));

pub fn alloc_try_with<F, T, E>(&self, f: F) -> Result<&mut T, E>

where F: FnOnce() -> Result<T, E>,

Pre-allocates space for a Result in this Bump, initializes it using the closure, then returns an exclusive reference to its T if Ok.

Iff the allocation fails, the closure is not run.

Iff Err, an allocator rewind is attempted and the E instance is moved out of the allocator to be consumed or dropped as normal.

See The _with Method Suffix for a discussion on the differences between the _with suffixed methods and those methods without it, their performance characteristics, and when you might or might not choose a _with suffixed method.

For caveats specific to fallible initialization, see The _try_with Method Suffix.

Errors

Iff the allocation succeeds but f fails, that error is forwarded by value.

Panics

Panics if reserving space for Result<T, E> fails.

Example

let bump = bumpalo::Bump::new();
let x = bump.alloc_try_with(|| Ok("hello"))?;
assert_eq!(*x, "hello");

pub fn try_alloc_try_with<F, T, E>( &self, f: F, ) -> Result<&mut T, AllocOrInitError<E>>

where F: FnOnce() -> Result<T, E>,

Tries to pre-allocates space for a Result in this Bump, initializes it using the closure, then returns an exclusive reference to its T if all Ok.

Iff the allocation fails, the closure is not run.

Iff the closure returns Err, an allocator rewind is attempted and the E instance is moved out of the allocator to be consumed or dropped as normal.

See The _with Method Suffix for a discussion on the differences between the _with suffixed methods and those methods without it, their performance characteristics, and when you might or might not choose a _with suffixed method.

For caveats specific to fallible initialization, see The _try_with Method Suffix.

Errors

Errors with the Alloc variant iff reserving space for Result<T, E> fails.

Iff the allocation succeeds but f fails, that error is forwarded by value inside the Init variant.

Example

let bump = bumpalo::Bump::new();
let x = bump.try_alloc_try_with(|| Ok("hello"))?;
assert_eq!(*x, "hello");

pub fn alloc_slice_copy<T>(&self, src: &[T]) -> &mut [T]

where T: Copy,

Copy a slice into this Bump and return an exclusive reference to the copy.

Panics

Panics if reserving space for the slice fails.

Example

let bump = bumpalo::Bump::new();
let x = bump.alloc_slice_copy(&[1, 2, 3]);
assert_eq!(x, &[1, 2, 3]);

pub fn try_alloc_slice_copy<T>(&self, src: &[T]) -> Result<&mut [T], AllocErr>

where T: Copy,

Like alloc_slice_copy, but does not panic in case of allocation failure.

Example

let bump = bumpalo::Bump::new();
let x = bump.try_alloc_slice_copy(&[1, 2, 3]);
assert_eq!(x, Ok(&mut[1, 2, 3] as &mut [_]));


let bump = bumpalo::Bump::new();
bump.set_allocation_limit(Some(4));
let x = bump.try_alloc_slice_copy(&[1, 2, 3, 4, 5, 6]);
assert_eq!(x, Err(bumpalo::AllocErr)); // too big

pub fn alloc_slice_clone<T>(&self, src: &[T]) -> &mut [T]

where T: Clone,

Clone a slice into this Bump and return an exclusive reference to the clone. Prefer alloc_slice_copy if T is Copy.

Panics

Panics if reserving space for the slice fails.

Example

#[derive(Clone, Debug, Eq, PartialEq)]
struct Sheep {
    name: String,
}

let originals = [
    Sheep { name: "Alice".into() },
    Sheep { name: "Bob".into() },
    Sheep { name: "Cathy".into() },
];

let bump = bumpalo::Bump::new();
let clones = bump.alloc_slice_clone(&originals);
assert_eq!(originals, clones);

pub fn try_alloc_slice_clone<T>(&self, src: &[T]) -> Result<&mut [T], AllocErr>

where T: Clone,

Like alloc_slice_clone but does not panic on failure.

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

Copy a string slice into this Bump and return an exclusive reference to it.

Panics

Panics if reserving space for the string fails.

Example

let bump = bumpalo::Bump::new();
let hello = bump.alloc_str("hello world");
assert_eq!("hello world", hello);

pub fn try_alloc_str(&self, src: &str) -> Result<&mut str, AllocErr>

Same as alloc_str but does not panic on failure.

Example

let bump = bumpalo::Bump::new();
let hello = bump.try_alloc_str("hello world").unwrap();
assert_eq!("hello world", hello);


let bump = bumpalo::Bump::new();
bump.set_allocation_limit(Some(5));
let hello = bump.try_alloc_str("hello world");
assert_eq!(Err(bumpalo::AllocErr), hello);

pub fn alloc_slice_fill_with<T, F>(&self, len: usize, f: F) -> &mut [T]

where F: FnMut(usize) -> T,

Allocates a new slice of size len into this Bump and returns an exclusive reference to the copy.

The elements of the slice are initialized using the supplied closure. The closure argument is the position in the slice.

Panics

Panics if reserving space for the slice fails.

Example

let bump = bumpalo::Bump::new();
let x = bump.alloc_slice_fill_with(5, |i| 5 * (i + 1));
assert_eq!(x, &[5, 10, 15, 20, 25]);

pub fn try_alloc_slice_fill_with<T, F>( &self, len: usize, f: F, ) -> Result<&mut [T], AllocErr>

where F: FnMut(usize) -> T,

Allocates a new slice of size len into this Bump and returns an exclusive reference to the copy.

The elements of the slice are initialized using the supplied closure. The closure argument is the position in the slice.

Example

let bump = bumpalo::Bump::new();
let x = bump.try_alloc_slice_fill_with(5, |i| 5 * (i + 1));
assert_eq!(x, Ok(&mut[5usize, 10, 15, 20, 25] as &mut [_]));


let bump = bumpalo::Bump::new();
bump.set_allocation_limit(Some(4));
let x = bump.try_alloc_slice_fill_with(10, |i| 5 * (i + 1));
assert_eq!(x, Err(bumpalo::AllocErr));

pub fn alloc_slice_fill_copy<T>(&self, len: usize, value: T) -> &mut [T]

where T: Copy,

Allocates a new slice of size len into this Bump and returns an exclusive reference to the copy.

All elements of the slice are initialized to value.

Panics

Panics if reserving space for the slice fails.

Example

let bump = bumpalo::Bump::new();
let x = bump.alloc_slice_fill_copy(5, 42);
assert_eq!(x, &[42, 42, 42, 42, 42]);

pub fn try_alloc_slice_fill_copy<T>( &self, len: usize, value: T, ) -> Result<&mut [T], AllocErr>

where T: Copy,

Same as alloc_slice_fill_copy but does not panic on failure.

pub fn alloc_slice_fill_clone<T>(&self, len: usize, value: &T) -> &mut [T]

where T: Clone,

Allocates a new slice of size len slice into this Bump and return an exclusive reference to the copy.

All elements of the slice are initialized to value.clone().

Panics

Panics if reserving space for the slice fails.

Example

let bump = bumpalo::Bump::new();
let s: String = "Hello Bump!".to_string();
let x: &[String] = bump.alloc_slice_fill_clone(2, &s);
assert_eq!(x.len(), 2);
assert_eq!(&x[0], &s);
assert_eq!(&x[1], &s);

pub fn try_alloc_slice_fill_clone<T>( &self, len: usize, value: &T, ) -> Result<&mut [T], AllocErr>

where T: Clone,

Like alloc_slice_fill_clone but does not panic on failure.

pub fn alloc_slice_fill_iter<T, I>(&self, iter: I) -> &mut [T]

where I: IntoIterator<Item = T>, <I as IntoIterator>::IntoIter: ExactSizeIterator,

Allocates a new slice of size len slice into this Bump and return an exclusive reference to the copy.

The elements are initialized using the supplied iterator.

Panics

Panics if reserving space for the slice fails, or if the supplied iterator returns fewer elements than it promised.

Example

let bump = bumpalo::Bump::new();
let x: &[i32] = bump.alloc_slice_fill_iter([2, 3, 5].iter().cloned().map(|i| i * i));
assert_eq!(x, [4, 9, 25]);

pub fn try_alloc_slice_fill_iter<T, I>( &self, iter: I, ) -> Result<&mut [T], AllocErr>

where I: IntoIterator<Item = T>, <I as IntoIterator>::IntoIter: ExactSizeIterator,

Allocates a new slice of size iter.len() slice into this Bump and return an exclusive reference to the copy. Does not panic on failure.

The elements are initialized using the supplied iterator.

Example

let bump = bumpalo::Bump::new();
let x: &[i32] = bump.try_alloc_slice_fill_iter([2, 3, 5]
    .iter().cloned().map(|i| i * i)).unwrap();
assert_eq!(x, [4, 9, 25]);

pub fn alloc_slice_fill_default<T>(&self, len: usize) -> &mut [T]

where T: Default,

Allocates a new slice of size len slice into this Bump and return an exclusive reference to the copy.

All elements of the slice are initialized to T::default().

Panics

Panics if reserving space for the slice fails.

Example

let bump = bumpalo::Bump::new();
let x = bump.alloc_slice_fill_default::<u32>(5);
assert_eq!(x, &[0, 0, 0, 0, 0]);

pub fn try_alloc_slice_fill_default<T>( &self, len: usize, ) -> Result<&mut [T], AllocErr>

where T: Default,

Like alloc_slice_fill_default but does not panic on failure.

pub fn alloc_layout(&self, layout: Layout) -> NonNull<u8>

Allocate space for an object with the given Layout.

The returned pointer points at uninitialized memory, and should be initialized with std::ptr::write.

Panics

Panics if reserving space matching layout fails.

pub fn try_alloc_layout(&self, layout: Layout) -> Result<NonNull<u8>, AllocErr>

Attempts to allocate space for an object with the given Layout or else returns an Err.

The returned pointer points at uninitialized memory, and should be initialized with std::ptr::write.

Errors

Errors if reserving space matching layout fails.

pub fn chunk_capacity(&self) -> usize

Gets the remaining capacity in the current chunk (in bytes).

Example

use bumpalo::Bump;

let bump = Bump::with_capacity(100);

let capacity = bump.chunk_capacity();
assert!(capacity >= 100);

pub fn iter_allocated_chunks(&mut self) -> ChunkIter<'_>

Returns an iterator over each chunk of allocated memory that this arena has bump allocated into.

The chunks are returned ordered by allocation time, with the most recently allocated chunk being returned first, and the least recently allocated chunk being returned last.

The values inside each chunk are also ordered by allocation time, with the most recent allocation being earlier in the slice, and the least recent allocation being towards the end of the slice.

Safety

Because this method takes &mut self, we know that the bump arena reference is unique and therefore there aren’t any active references to any of the objects we’ve allocated in it either. This potential aliasing of exclusive references is one common footgun for unsafe code that we don’t need to worry about here.

However, there could be regions of uninitialized memory used as padding between allocations, which is why this iterator has items of type [MaybeUninit<u8>], instead of simply [u8].

The only way to guarantee that there is no padding between allocations or within allocated objects is if all of these properties hold:

1. Every object allocated in this arena has the same alignment, and that alignment is at most 16.
2. Every object’s size is a multiple of its alignment.
3. None of the objects allocated in this arena contain any internal padding.

If you want to use this iter_allocated_chunks method, it is your responsibility to ensure that these properties hold before calling MaybeUninit::assume_init or otherwise reading the returned values.

Finally, you must also ensure that any values allocated into the bump arena have not had their Drop implementations called on them, e.g. after dropping a [bumpalo::boxed::Box<T>][crate::boxed::Box].

Example

let mut bump = bumpalo::Bump::new();

// Allocate a bunch of `i32`s in this bump arena, potentially causing
// additional memory chunks to be reserved.
for i in 0..10000 {
    bump.alloc(i);
}

// Iterate over each chunk we've bump allocated into. This is safe
// because we have only allocated `i32`s in this arena, which fulfills
// the above requirements.
for ch in bump.iter_allocated_chunks() {
    println!("Used a chunk that is {} bytes long", ch.len());
    println!("The first byte is {:?}", unsafe {
        ch[0].assume_init()
    });
}

// Within a chunk, allocations are ordered from most recent to least
// recent. If we allocated 'a', then 'b', then 'c', when we iterate
// through the chunk's data, we get them in the order 'c', then 'b',
// then 'a'.

bump.reset();
bump.alloc(b'a');
bump.alloc(b'b');
bump.alloc(b'c');

assert_eq!(bump.iter_allocated_chunks().count(), 1);
let chunk = bump.iter_allocated_chunks().nth(0).unwrap();
assert_eq!(chunk.len(), 3);

// Safe because we've only allocated `u8`s in this arena, which
// fulfills the above requirements.
unsafe {
    assert_eq!(chunk[0].assume_init(), b'c');
    assert_eq!(chunk[1].assume_init(), b'b');
    assert_eq!(chunk[2].assume_init(), b'a');
}

pub unsafe fn iter_allocated_chunks_raw(&self) -> ChunkRawIter<'_>

Returns an iterator over raw pointers to chunks of allocated memory that this arena has bump allocated into.

This is an unsafe version of iter_allocated_chunks(), with the caller responsible for safe usage of the returned pointers as well as ensuring that the iterator is not invalidated by new allocations.

Safety

Allocations from this arena must not be performed while the returned iterator is alive. If reading the chunk data (or casting to a reference) the caller must ensure that there exist no mutable references to previously allocated data.

In addition, all of the caveats when reading the chunk data from iter_allocated_chunks() still apply.

pub fn allocated_bytes(&self) -> usize

Calculates the number of bytes currently allocated across all chunks in this bump arena.

If you allocate types of different alignments or types with larger-than-typical alignment in the same arena, some padding bytes might get allocated in the bump arena. Note that those padding bytes will add to this method’s resulting sum, so you cannot rely on it only counting the sum of the sizes of the things you’ve allocated in the arena.

The allocated bytes do not include the size of bumpalo’s metadata, so the amount of memory requested from the Rust allocator is higher than the returned value.

Example

let bump = bumpalo::Bump::new();
let _x = bump.alloc_slice_fill_default::<u32>(5);
let bytes = bump.allocated_bytes();
assert!(bytes >= core::mem::size_of::<u32>() * 5);

pub fn allocated_bytes_including_metadata(&self) -> usize

Calculates the number of bytes requested from the Rust allocator for this Bump.

This number is equal to the allocated_bytes() plus the size of the bump metadata.

Trait Implementations

impl Allocator for &Arena

fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

Attempts to allocate a block of memory.

unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)

Deallocates the memory referenced by ptr.

fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

Behaves like allocate, but also ensures that the returned memory is zero-initialized.

unsafe fn grow( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

Attempts to extend the memory block.

unsafe fn grow_zeroed( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

Behaves like grow, but also ensures that the new contents are set to zero before being returned.

unsafe fn shrink( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

Attempts to shrink the memory block.

fn by_ref(&self) -> &Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Allocator.

impl Default for Arena

fn default() -> Arena

Returns the “default value” for a type.

impl Deref for Arena

type Target = Bump

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Arena

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl From<Bump> for Arena

fn from(inner: Bump) -> Self

Converts to this type from the input type.