Struct Bump 

pub struct Bump<A = Global, S = BumpSettings>
where
    A: Allocator,
    S: BumpAllocatorSettings,
{ /* private fields */ }

The bump allocator.

Generic parameters

• A — the base allocator, defaults to Global when the alloc feature is enabled
• S — the bump allocator settings, see settings

Overview

All of the mentioned methods that do allocations panic if the base allocator returned an error. For every such panicking method, there is a corresponding try_-prefixed version that returns a Result instead.

Create a Bump …

• without allocating a chunk: new(_in) / default
• provide a size hint: with_size(_in)
• provide a minimum capacity: with_capacity(_in)

Allocate …

• sized values: alloc, alloc_with, alloc_default, alloc_zeroed

• strings: alloc_str, alloc_fmt(_mut)

• c strings: alloc_cstr, alloc_cstr_from_str, alloc_cstr_fmt(_mut)

• slices: alloc_slice_{copy, clone, move, fill, fill_with}, alloc_zeroed_slice

• slices from an iterator: alloc_iter, alloc_iter_exact, alloc_iter_mut, alloc_iter_mut_rev

• uninitialized values: alloc_uninit, alloc_uninit_slice, alloc_uninit_slice_for

  which can then be conveniently initialized by the init* methods of BumpBox.

• results: alloc_try_with, alloc_try_with_mut

• via clone (nightly only): alloc_clone

Free memory using …

• scopes: scoped, scoped_aligned, scope_guard
• checkpoints: checkpoint, reset_to
• reset: reset
• dealloc: dealloc

Configure allocator settings …

• with_settings, borrow_with_settings, borrow_mut_with_settings

Collections

A Bump (and BumpScope) can be used to allocate collections of this crate…

use bump_scope::{Bump, BumpString};
let bump: Bump = Bump::new();

let mut string = BumpString::new_in(&bump);
string.push_str("Hello,");
string.push_str(" world!");

… and collections from crates that use allocator_api2’s Allocator like hashbrown’s HashMap:

This requires the allocator-api2-02 feature OR the nightly-allocator-api feature along with hashbrown’s nightly feature.

use bump_scope::Bump;
use hashbrown::HashMap;

let bump: Bump = Bump::new();
let mut map = HashMap::new_in(&bump);
map.insert("tau", 6.283);

On nightly and with the feature nightly-allocator-api you can also allocate collections from std that have an allocator parameter:

#![feature(allocator_api, btreemap_alloc)]
use bump_scope::Bump;
use std::collections::{VecDeque, BTreeMap, LinkedList};

let bump: Bump = Bump::new();
let vec = Vec::new_in(&bump);
let queue = VecDeque::new_in(&bump);
let map = BTreeMap::new_in(&bump);
let list = LinkedList::new_in(&bump);

Gotcha

Having live allocations and entering bump scopes at the same time requires a BumpScope. This is due to the way lifetimes work, since Bump returns allocations with the lifetime of its own borrow instead of a separate lifetime like BumpScope does.

So you can’t do this:

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

let one = bump.alloc(1);

bump.scoped(|bump| {
    // whatever
});

But you can make the code work by converting the Bump it to a BumpScope first using as_mut_scope:

let mut bump: Bump = Bump::new();
let bump = bump.as_mut_scope();

let one = bump.alloc(1);

bump.scoped(|bump| {
    // whatever
});

Implementations

impl<A, S> Bump<A, S>

where A: Allocator + Default, S: BumpAllocatorSettings,

Methods for a Bump with a default base allocator.

pub fn new() -> Self

Constructs a new Bump without allocating.

Examples

use bump_scope::Bump;

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

pub fn with_size(size: usize) -> Self

Constructs a new Bump with a size hint for the first chunk.

If you want to ensure a specific capacity, use with_capacity instead.

An effort is made to ensure the size requested from the base allocator is friendly to an allocator that uses size classes and stores metadata alongside allocations. To achieve this, the requested size is rounded up to either the next power of two or the next multiple of 0x1000, whichever is smaller. After that, the size of [usize; 2] is subtracted.

If the base allocator returns a memory block that is larger than requested, then the chunk will use the extra space.

Disclaimer: The way in which the chunk layout is calculated might change. Such a change is not considered semver breaking.

Panics

Panics if the allocation fails.

Examples

use bump_scope::Bump;

// `Bump` with a roughly 1 Mebibyte sized chunk
let bump_1mib: Bump = Bump::with_size(1024 * 1024);

pub fn try_with_size(size: usize) -> Result<Self, AllocError>

Constructs a new Bump with a size hint for the first chunk.

If you want to ensure a specific capacity, use try_with_capacity instead.

An effort is made to ensure the size requested from the base allocator is friendly to an allocator that uses size classes and stores metadata alongside allocations. To achieve this, the requested size is rounded up to either the next power of two or the next multiple of 0x1000, whichever is smaller. After that, the size of [usize; 2] is subtracted.

If the base allocator returns a memory block that is larger than requested, then the chunk will use the extra space.

Disclaimer: The way in which the chunk layout is calculated might change. Such a change is not considered semver breaking.

Errors

Errors if the allocation fails.

Examples

use bump_scope::Bump;

// `Bump` with a roughly 1 Mebibyte sized chunk
let bump_1mib: Bump = Bump::try_with_size(1024 * 1024)?;

pub fn with_capacity(layout: Layout) -> Self

Constructs a new Bump with at least enough space for layout.

To construct a Bump with a size hint use with_size instead.

Panics

Panics if the allocation fails.

Examples

use bump_scope::Bump;
use core::alloc::Layout;

let layout = Layout::array::<u8>(1234).unwrap();
let bump: Bump = Bump::with_capacity(layout);
assert!(bump.stats().capacity() >= layout.size());

pub fn try_with_capacity(layout: Layout) -> Result<Self, AllocError>

Constructs a new Bump with at least enough space for layout.

To construct a Bump with a size hint use try_with_size instead.

Errors

Errors if the allocation fails.

Examples

use bump_scope::Bump;
use core::alloc::Layout;

let layout = Layout::array::<u8>(1234).unwrap();
let bump: Bump = Bump::try_with_capacity(layout)?;
assert!(bump.stats().capacity() >= layout.size());

impl<A, S> Bump<A, S>

where A: Allocator, S: BumpAllocatorSettings,

Methods that are always available.

pub const fn new_in(allocator: A) -> Self

Constructs a new Bump without allocating.

Examples

use bump_scope::Bump;
use bump_scope::alloc::Global;

let bump: Bump = Bump::new_in(Global);

pub fn with_size_in(size: usize, allocator: A) -> Self

Constructs a new Bump with a size hint for the first chunk.

If you want to ensure a specific capacity, use with_capacity_in instead.

An effort is made to ensure the size requested from the base allocator is friendly to an allocator that uses size classes and stores metadata alongside allocations. To achieve this, the requested size is rounded up to either the next power of two or the next multiple of 0x1000, whichever is smaller. After that, the size of [usize; 2] is subtracted.

If the base allocator returns a memory block that is larger than requested, then the chunk will use the extra space.

Disclaimer: The way in which the chunk layout is calculated might change. Such a change is not considered semver breaking.

Panics

Panics if the allocation fails.

Examples

use bump_scope::Bump;
use bump_scope::alloc::Global;

// `Bump` with a roughly 1 Mebibyte sized chunk
let bump_1mib: Bump = Bump::with_size_in(1024 * 1024, Global);

pub fn try_with_size_in(size: usize, allocator: A) -> Result<Self, AllocError>

Constructs a new Bump with a size hint for the first chunk.

If you want to ensure a specific capacity, use try_with_capacity instead.

An effort is made to ensure the size requested from the base allocator is friendly to an allocator that uses size classes and stores metadata alongside allocations. To achieve this, the requested size is rounded up to either the next power of two or the next multiple of 0x1000, whichever is smaller. After that, the size of [usize; 2] is subtracted.

If the base allocator returns a memory block that is larger than requested, then the chunk will use the extra space.

Disclaimer: The way in which the chunk layout is calculated might change. Such a change is not considered semver breaking.

Errors

Errors if the allocation fails.

Examples

use bump_scope::Bump;
use bump_scope::alloc::Global;

// `Bump` with a roughly 1 Mebibyte sized chunk
let bump_1mib: Bump = Bump::try_with_size_in(1024 * 1024, Global)?;

pub fn with_capacity_in(layout: Layout, allocator: A) -> Self

Constructs a new Bump with at least enough space for layout.

To construct a Bump with a size hint use with_size_in instead.

Panics

Panics if the allocation fails.

Examples

use bump_scope::Bump;
use bump_scope::alloc::Global;
use core::alloc::Layout;

let layout = Layout::array::<u8>(1234).unwrap();
let bump: Bump = Bump::with_capacity_in(layout, Global);
assert!(bump.stats().capacity() >= layout.size());

pub fn try_with_capacity_in( layout: Layout, allocator: A, ) -> Result<Self, AllocError>

Constructs a new Bump with at least enough space for layout.

To construct a Bump with a size hint use try_with_size_in instead.

Errors

Errors if the allocation fails.

Examples

use bump_scope::Bump;
use bump_scope::alloc::Global;
use core::alloc::Layout;

let layout = Layout::array::<u8>(1234).unwrap();
let bump: Bump = Bump::try_with_capacity_in(layout, Global)?;
assert!(bump.stats().capacity() >= layout.size());

pub fn reset(&mut self)

Deallocates every chunk but the newest, which is also the biggest.

use bump_scope::Bump;

let mut bump: Bump = Bump::with_size(512);

// won't fit in the first chunk
bump.alloc_uninit_slice::<u8>(600);

let chunks = bump.stats().small_to_big().collect::<Vec<_>>();
assert_eq!(chunks.len(), 2);
assert!(chunks[0].size() < chunks[1].size());
assert_eq!(chunks[0].allocated(), 0);
assert_eq!(chunks[1].allocated(), 600);
let last_chunk_size = chunks[1].size();

bump.reset();

let chunks = bump.stats().small_to_big().collect::<Vec<_>>();
assert_eq!(chunks.len(), 1);
assert_eq!(chunks[0].size(), last_chunk_size);
assert_eq!(chunks[0].allocated(), 0);

pub fn stats(&self) -> Stats<'_, S>

Returns a type which provides statistics about the memory usage of the bump allocator.

pub fn as_scope(&self) -> &BumpScope<'_, A, S>

Returns this &Bump as a &BumpScope.

pub fn as_mut_scope(&mut self) -> &mut BumpScope<'_, A, S>

Returns this &mut Bump as a &mut BumpScope.

pub fn with_settings<NewS>(self) -> Bump<A, NewS>

where NewS: BumpAllocatorSettings,

Converts this Bump into a Bump with new settings.

Not every setting can be converted to. This function will fail to compile if:

• NewS::UP != S::UP
• NewS::GUARANTEED_ALLOCATED > S::GUARANTEED_ALLOCATED
• NewS::CLAIMABLE < S::CLAIMABLE

pub fn borrow_with_settings<NewS>(&self) -> &Bump<A, NewS>

where NewS: BumpAllocatorSettings,

Borrows this Bump with new settings.

Not every settings can be converted to. This function will fail to compile if:

• NewS::MIN_ALIGN != S::MIN_ALIGN
• NewS::UP != S::UP
• NewS::GUARANTEED_ALLOCATED > S::GUARANTEED_ALLOCATED
• NewS::CLAIMABLE != S::CLAIMABLE

pub fn borrow_mut_with_settings<NewS>(&mut self) -> &mut Bump<A, NewS>

where NewS: BumpAllocatorSettings,

Borrows this Bump mutably with new settings.

Not every settings can be converted to. This function will fail to compile if:

• NewS::MIN_ALIGN < S::MIN_ALIGN
• NewS::UP != S::UP
• NewS::GUARANTEED_ALLOCATED != S::GUARANTEED_ALLOCATED
• NewS::CLAIMABLE != S::CLAIMABLE

impl<S> Bump<Global, S>

where S: BumpAllocatorSettings,

pub fn into_raw(self) -> NonNull<()>

Available on crate feature alloc only.

Converts this Bump into a raw pointer.

use bump_scope::Bump;

let bump: Bump = Bump::new();
let ptr = bump.into_raw();
let bump: Bump = unsafe { Bump::from_raw(ptr) };

bump.alloc_str("Why did i do this?");

pub unsafe fn from_raw(ptr: NonNull<()>) -> Self

Available on crate feature alloc only.

Converts the raw pointer that was created with into_raw back into a Bump.

Safety

• ptr must have been created with Self::into_raw.
• This function must only be called once with this ptr.
• The settings must match the original ones.

impl<A, S> Bump<A, S>

where A: Allocator, S: BumpAllocatorSettings,

Methods that forward to traits.

pub fn claim(&self) -> BumpClaimGuard<'_, '_, A, S>

Forwards to BumpAllocatorScope::claim.

pub fn is_claimed(&self) -> bool

Forwards to BumpAllocatorCore::is_claimed.

pub fn scope_guard(&mut self) -> BumpScopeGuard<'_, A, S>

Forwards to BumpAllocator::scope_guard.

pub fn scoped<R>(&mut self, f: impl FnOnce(&mut BumpScope<'_, A, S>) -> R) -> R

Forwards to BumpAllocator::scoped.

pub fn scoped_aligned<const NEW_MIN_ALIGN: usize, R>( &mut self, f: impl FnOnce(&mut BumpScope<'_, A, S::WithMinimumAlignment<NEW_MIN_ALIGN>>) -> R, ) -> R

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

Forwards to BumpAllocator::scoped_aligned.

pub fn aligned<const NEW_MIN_ALIGN: usize, R>( &mut self, f: impl FnOnce(&mut BumpScope<'_, A, S::WithMinimumAlignment<NEW_MIN_ALIGN>>) -> R, ) -> R

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

Forwards to BumpAllocatorScope::aligned.

pub fn checkpoint(&self) -> Checkpoint

Forwards to BumpAllocatorCore::checkpoint.

pub unsafe fn reset_to(&self, checkpoint: Checkpoint)

Forwards to BumpAllocatorCore::reset_to.

pub fn allocator(&self) -> &A

Forwards to BumpAllocatorScope::allocator.

pub fn alloc<T>(&self, value: T) -> BumpBox<'_, T>

Forwards to BumpAllocatorTypedScope::alloc.

pub fn try_alloc<T>(&self, value: T) -> Result<BumpBox<'_, T>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc.

pub fn alloc_with<T>(&self, f: impl FnOnce() -> T) -> BumpBox<'_, T>

Forwards to BumpAllocatorTypedScope::alloc_with.

pub fn try_alloc_with<T>( &self, f: impl FnOnce() -> T, ) -> Result<BumpBox<'_, T>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_with.

pub fn alloc_default<T: Default>(&self) -> BumpBox<'_, T>

Forwards to BumpAllocatorTypedScope::alloc_default.

pub fn try_alloc_default<T: Default>( &self, ) -> Result<BumpBox<'_, T>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_default.

pub fn alloc_clone<T: CloneToUninit + ?Sized>( &self, value: &T, ) -> BumpBox<'_, T>

Available on crate feature nightly-clone-to-uninit only.

Forwards to BumpAllocatorTypedScope::alloc_clone.

pub fn try_alloc_clone<T: CloneToUninit + ?Sized>( &self, value: &T, ) -> Result<BumpBox<'_, T>, AllocError>

Available on crate feature nightly-clone-to-uninit only.

Forwards to BumpAllocatorTypedScope::try_alloc_clone.

pub fn alloc_slice_move<T>( &self, slice: impl OwnedSlice<Item = T>, ) -> BumpBox<'_, [T]>

Forwards to BumpAllocatorTypedScope::alloc_slice_move.

pub fn try_alloc_slice_move<T>( &self, slice: impl OwnedSlice<Item = T>, ) -> Result<BumpBox<'_, [T]>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_slice_move.

pub fn alloc_slice_copy<T: Copy>(&self, slice: &[T]) -> BumpBox<'_, [T]>

Forwards to BumpAllocatorTypedScope::alloc_slice_copy.

pub fn try_alloc_slice_copy<T: Copy>( &self, slice: &[T], ) -> Result<BumpBox<'_, [T]>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_slice_copy.

pub fn alloc_slice_clone<T: Clone>(&self, slice: &[T]) -> BumpBox<'_, [T]>

Forwards to BumpAllocatorTypedScope::alloc_slice_clone.

pub fn try_alloc_slice_clone<T: Clone>( &self, slice: &[T], ) -> Result<BumpBox<'_, [T]>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_slice_clone.

pub fn alloc_slice_fill<T: Clone>( &self, len: usize, value: T, ) -> BumpBox<'_, [T]>

Forwards to BumpAllocatorTypedScope::alloc_slice_fill.

pub fn try_alloc_slice_fill<T: Clone>( &self, len: usize, value: T, ) -> Result<BumpBox<'_, [T]>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_slice_fill.

pub fn alloc_slice_fill_with<T>( &self, len: usize, f: impl FnMut() -> T, ) -> BumpBox<'_, [T]>

Forwards to BumpAllocatorTypedScope::alloc_slice_fill_with.

pub fn try_alloc_slice_fill_with<T>( &self, len: usize, f: impl FnMut() -> T, ) -> Result<BumpBox<'_, [T]>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_slice_fill_with.

pub fn alloc_str(&self, src: &str) -> BumpBox<'_, str>

Forwards to BumpAllocatorTypedScope::alloc_str.

pub fn try_alloc_str(&self, src: &str) -> Result<BumpBox<'_, str>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_str.

pub fn alloc_fmt(&self, args: Arguments<'_>) -> BumpBox<'_, str>

Forwards to BumpAllocatorTypedScope::alloc_fmt.

pub fn try_alloc_fmt( &self, args: Arguments<'_>, ) -> Result<BumpBox<'_, str>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_fmt.

pub fn alloc_fmt_mut(&mut self, args: Arguments<'_>) -> BumpBox<'_, str>

Forwards to MutBumpAllocatorTypedScope::alloc_fmt_mut.

pub fn try_alloc_fmt_mut( &mut self, args: Arguments<'_>, ) -> Result<BumpBox<'_, str>, AllocError>

Forwards to MutBumpAllocatorTypedScope::try_alloc_fmt_mut.

pub fn alloc_cstr(&self, src: &CStr) -> &CStr

Forwards to BumpAllocatorTypedScope::alloc_cstr.

pub fn try_alloc_cstr(&self, src: &CStr) -> Result<&CStr, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_cstr.

pub fn alloc_cstr_from_str(&self, src: &str) -> &CStr

Forwards to BumpAllocatorTypedScope::alloc_cstr_from_str.

pub fn try_alloc_cstr_from_str(&self, src: &str) -> Result<&CStr, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_cstr_from_str.

pub fn alloc_cstr_fmt(&self, args: Arguments<'_>) -> &CStr

Forwards to BumpAllocatorTypedScope::alloc_cstr_fmt.

pub fn try_alloc_cstr_fmt( &self, args: Arguments<'_>, ) -> Result<&CStr, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_cstr_fmt.

pub fn alloc_cstr_fmt_mut(&mut self, args: Arguments<'_>) -> &CStr

Forwards to MutBumpAllocatorTypedScope::alloc_cstr_fmt_mut.

pub fn try_alloc_cstr_fmt_mut( &mut self, args: Arguments<'_>, ) -> Result<&CStr, AllocError>

Forwards to MutBumpAllocatorTypedScope::try_alloc_cstr_fmt_mut.

pub fn alloc_iter<T>( &self, iter: impl IntoIterator<Item = T>, ) -> BumpBox<'_, [T]>

Forwards to BumpAllocatorTypedScope::alloc_iter.

pub fn try_alloc_iter<T>( &self, iter: impl IntoIterator<Item = T>, ) -> Result<BumpBox<'_, [T]>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_iter.

pub fn alloc_iter_exact<T, I>( &self, iter: impl IntoIterator<Item = T, IntoIter = I>, ) -> BumpBox<'_, [T]>

where I: ExactSizeIterator<Item = T>,

Forwards to BumpAllocatorTypedScope::alloc_iter_exact.

pub fn try_alloc_iter_exact<T, I>( &self, iter: impl IntoIterator<Item = T, IntoIter = I>, ) -> Result<BumpBox<'_, [T]>, AllocError>

where I: ExactSizeIterator<Item = T>,

Forwards to BumpAllocatorTypedScope::try_alloc_iter_exact.

pub fn alloc_iter_mut<T>( &mut self, iter: impl IntoIterator<Item = T>, ) -> BumpBox<'_, [T]>

Forwards to MutBumpAllocatorTypedScope::alloc_iter_mut.

pub fn try_alloc_iter_mut<T>( &mut self, iter: impl IntoIterator<Item = T>, ) -> Result<BumpBox<'_, [T]>, AllocError>

Forwards to MutBumpAllocatorTypedScope::try_alloc_iter_mut.

pub fn alloc_iter_mut_rev<T>( &mut self, iter: impl IntoIterator<Item = T>, ) -> BumpBox<'_, [T]>

Forwards to MutBumpAllocatorTypedScope::alloc_iter_mut_rev.

pub fn try_alloc_iter_mut_rev<T>( &mut self, iter: impl IntoIterator<Item = T>, ) -> Result<BumpBox<'_, [T]>, AllocError>

Forwards to MutBumpAllocatorTypedScope::try_alloc_iter_mut_rev.

pub fn alloc_uninit<T>(&self) -> BumpBox<'_, MaybeUninit<T>>

Forwards to BumpAllocatorTypedScope::alloc_uninit.

pub fn try_alloc_uninit<T>( &self, ) -> Result<BumpBox<'_, MaybeUninit<T>>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_uninit.

pub fn alloc_uninit_slice<T>(&self, len: usize) -> BumpBox<'_, [MaybeUninit<T>]>

Forwards to BumpAllocatorTypedScope::alloc_uninit_slice.

pub fn try_alloc_uninit_slice<T>( &self, len: usize, ) -> Result<BumpBox<'_, [MaybeUninit<T>]>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_uninit_slice.

pub fn alloc_uninit_slice_for<T>( &self, slice: &[T], ) -> BumpBox<'_, [MaybeUninit<T>]>

Forwards to BumpAllocatorTypedScope::alloc_uninit_slice_for.

pub fn try_alloc_uninit_slice_for<T>( &self, slice: &[T], ) -> Result<BumpBox<'_, [MaybeUninit<T>]>, AllocError>

Forwards to BumpAllocatorTypedScope::try_alloc_uninit_slice_for.

pub fn dealloc<T: ?Sized>(&self, boxed: BumpBox<'_, T>)

Forwards to BumpAllocatorTyped::dealloc.

pub fn reserve(&self, additional: usize)

Forwards to BumpAllocatorTyped::reserve.

pub fn try_reserve(&self, additional: usize) -> Result<(), AllocError>

Forwards to BumpAllocatorTyped::try_reserve.

impl<A, S> Bump<A, S>

where A: Allocator, S: BumpAllocatorSettings,

Additional alloc methods that are not available in traits.

pub fn alloc_try_with<T, E>( &self, f: impl FnOnce() -> Result<T, E>, ) -> Result<BumpBox<'_, T>, E>

Allocates the result of f in the bump allocator, then moves E out of it and deallocates the space it took up.

This can be more performant than allocating T after the fact, as Result<T, E> may be constructed in the bump allocators memory instead of on the stack and then copied over.

There is also alloc_try_with_mut, optimized for a mutable reference.

Panics

Panics if the allocation fails.

Examples

let result = bump.alloc_try_with(|| -> Result<i32, i32> { Ok(123) });
assert_eq!(result.unwrap(), 123);
assert_eq!(bump.stats().allocated(), offset_of!(Result<i32, i32>, Ok.0) + size_of::<i32>());

let result = bump.alloc_try_with(|| -> Result<i32, i32> { Err(123) });
assert_eq!(result.unwrap_err(), 123);
assert_eq!(bump.stats().allocated(), 0);

pub fn try_alloc_try_with<T, E>( &self, f: impl FnOnce() -> Result<T, E>, ) -> Result<Result<BumpBox<'_, T>, E>, AllocError>

Allocates the result of f in the bump allocator, then moves E out of it and deallocates the space it took up.

This can be more performant than allocating T after the fact, as Result<T, E> may be constructed in the bump allocators memory instead of on the stack and then copied over.

There is also try_alloc_try_with_mut, optimized for a mutable reference.

Errors

Errors if the allocation fails.

Examples

let result = bump.try_alloc_try_with(|| -> Result<i32, i32> { Ok(123) })?;
assert_eq!(result.unwrap(), 123);
assert_eq!(bump.stats().allocated(), offset_of!(Result<i32, i32>, Ok.0) + size_of::<i32>());

let result = bump.try_alloc_try_with(|| -> Result<i32, i32> { Err(123) })?;
assert_eq!(result.unwrap_err(), 123);
assert_eq!(bump.stats().allocated(), 0);

pub fn alloc_try_with_mut<T, E>( &mut self, f: impl FnOnce() -> Result<T, E>, ) -> Result<BumpBox<'_, T>, E>

Allocates the result of f in the bump allocator, then moves E out of it and deallocates the space it took up.

This can be more performant than allocating T after the fact, as Result<T, E> may be constructed in the bump allocators memory instead of on the stack and then copied over.

This is just like alloc_try_with, but optimized for a mutable reference.

Panics

Panics if the allocation fails.

Examples

let result = bump.alloc_try_with_mut(|| -> Result<i32, i32> { Ok(123) });
assert_eq!(result.unwrap(), 123);
assert_eq!(bump.stats().allocated(), offset_of!(Result<i32, i32>, Ok.0) + size_of::<i32>());

let result = bump.alloc_try_with_mut(|| -> Result<i32, i32> { Err(123) });
assert_eq!(result.unwrap_err(), 123);
assert_eq!(bump.stats().allocated(), 0);

pub fn try_alloc_try_with_mut<T, E>( &mut self, f: impl FnOnce() -> Result<T, E>, ) -> Result<Result<BumpBox<'_, T>, E>, AllocError>

Allocates the result of f in the bump allocator, then moves E out of it and deallocates the space it took up.

This can be more performant than allocating T after the fact, as Result<T, E> may be constructed in the bump allocators memory instead of on the stack and then copied over.

This is just like try_alloc_try_with, but optimized for a mutable reference.

Errors

Errors if the allocation fails.

Examples

let result = bump.try_alloc_try_with_mut(|| -> Result<i32, i32> { Ok(123) })?;
assert_eq!(result.unwrap(), 123);
assert_eq!(bump.stats().allocated(), offset_of!(Result<i32, i32>, Ok.0) + size_of::<i32>());

let result = bump.try_alloc_try_with_mut(|| -> Result<i32, i32> { Err(123) })?;
assert_eq!(result.unwrap_err(), 123);
assert_eq!(bump.stats().allocated(), 0);

Trait Implementations

impl<A, S> Allocator for &mut Bump<A, S>

where A: CrateAllocator, S: BumpAllocatorSettings,

Available on crate feature allocator-api2-03 only.

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

Attempts to allocate a block of memory.

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

Deallocates the memory referenced by ptr.

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

Attempts to extend the memory block.

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

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]>, TargetAllocError>

Attempts to shrink the memory block.

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

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

fn by_ref(&self) -> &Self

where Self: Sized,

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

impl<A, S> Allocator for Bump<A, S>

where A: Allocator, S: BumpAllocatorSettings,

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.

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 allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

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

fn by_ref(&self) -> &Self

where Self: Sized,

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

impl<A, S> Allocator for Bump<A, S>

where A: CrateAllocator, S: BumpAllocatorSettings,

Available on crate feature nightly-allocator-api only.

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

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to allocate a block of memory.

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

🔬This is a nightly-only experimental API. (allocator_api)

Deallocates the memory referenced by ptr.

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

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to extend the memory block.

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

🔬This is a nightly-only experimental API. (allocator_api)

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]>, TargetAllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to shrink the memory block.

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

🔬This is a nightly-only experimental API. (allocator_api)

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

fn by_ref(&self) -> &Self

where Self: Sized,

🔬This is a nightly-only experimental API. (allocator_api)

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

impl<A, S> Allocator for Bump<A, S>

where A: CrateAllocator, S: BumpAllocatorSettings,

Available on crate feature allocator-api2-03 only.

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

Attempts to allocate a block of memory.

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

Deallocates the memory referenced by ptr.

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

Attempts to extend the memory block.

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

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]>, TargetAllocError>

Attempts to shrink the memory block.

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

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

fn by_ref(&self) -> &Self

where Self: Sized,

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

impl<A, S> Allocator for Bump<A, S>

where A: CrateAllocator, S: BumpAllocatorSettings,

Available on crate feature allocator-api2-04 only.

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

Attempts to allocate a block of memory.

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

Deallocates the memory referenced by ptr.

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

Attempts to extend the memory block.

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

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]>, TargetAllocError>

Attempts to shrink the memory block.

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

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

fn by_ref(&self) -> &Self

where Self: Sized,

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

impl<A, S> BumpAllocator for Bump<A, S>

where A: Allocator, S: BumpAllocatorSettings,

type Allocator = A

The base allocator.

type Settings = S

The bump allocator settings.

fn as_scope(&self) -> &BumpScope<'_, Self::Allocator, Self::Settings>

Returns this bump allocator as a &BumpScope.

fn as_mut_scope( &mut self, ) -> &mut BumpScope<'_, Self::Allocator, Self::Settings>

Returns this bump allocator as a &mut BumpScope.

fn scope_guard(&mut self) -> BumpScopeGuard<'_, Self::Allocator, Self::Settings>

Creates a new BumpScopeGuard.

fn scoped<R>( &mut self, f: impl FnOnce(&mut BumpScope<'_, Self::Allocator, Self::Settings>) -> R, ) -> R

Calls f with a new child scope.

fn scoped_aligned<const NEW_MIN_ALIGN: usize, R>( &mut self, f: impl FnOnce(&mut BumpScope<'_, Self::Allocator, <Self::Settings as BumpAllocatorSettings>::WithMinimumAlignment<NEW_MIN_ALIGN>>) -> R, ) -> R

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

Calls f with a new child scope of a new minimum alignment.

impl<A, S> BumpAllocatorCore for Bump<A, S>

where A: Allocator, S: BumpAllocatorSettings,

fn any_stats(&self) -> AnyStats<'_>

Returns a type which provides statistics about the memory usage of the bump allocator.

fn checkpoint(&self) -> Checkpoint

Creates a checkpoint of the current bump position.

unsafe fn reset_to(&self, checkpoint: Checkpoint)

Resets the bump position to a previously created checkpoint. The memory that has been allocated since then will be reused by future allocations.

fn is_claimed(&self) -> bool

Returns true if the bump allocator is currently claimed.

fn prepare_allocation( &self, layout: Layout, ) -> Result<Range<NonNull<u8>>, AllocError>

Returns a pointer range of free space in the bump allocator with a size of at least layout.size().

unsafe fn allocate_prepared( &self, layout: Layout, range: Range<NonNull<u8>>, ) -> NonNull<u8>

Allocate part of the free space returned from a prepare_allocation call.

fn prepare_allocation_rev( &self, layout: Layout, ) -> Result<Range<NonNull<u8>>, AllocError>

Returns a pointer range of free space in the bump allocator with a size of at least layout.size().

unsafe fn allocate_prepared_rev( &self, layout: Layout, range: Range<NonNull<u8>>, ) -> NonNull<u8>

Allocate part of the free space returned from a prepare_allocation_rev call starting at the end.

impl<A, S> BumpAllocatorTyped for Bump<A, S>

where A: Allocator, S: BumpAllocatorSettings,

type TypedStats<'b> = Stats<'b, S> where Self: 'b

The type returned by the stats method.

fn typed_stats(&self) -> Self::TypedStats<'_>

Returns a type which provides statistics about the memory usage of the bump allocator.

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

A specialized version of allocate.

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

A specialized version of allocate.

fn allocate_sized<T>(&self) -> NonNull<T>

A specialized version of allocate.

fn try_allocate_sized<T>(&self) -> Result<NonNull<T>, AllocError>

A specialized version of allocate.

fn allocate_slice<T>(&self, len: usize) -> NonNull<T>

A specialized version of allocate.

fn try_allocate_slice<T>(&self, len: usize) -> Result<NonNull<T>, AllocError>

A specialized version of allocate.

fn allocate_slice_for<T>(&self, slice: &[T]) -> NonNull<T>

A specialized version of allocate.

fn try_allocate_slice_for<T>( &self, slice: &[T], ) -> Result<NonNull<T>, AllocError>

A specialized version of allocate.

unsafe fn shrink_slice<T>( &self, ptr: NonNull<T>, old_len: usize, new_len: usize, ) -> Option<NonNull<T>>

A specialized version of shrink.

fn prepare_slice_allocation<T>(&self, len: usize) -> NonNull<[T]>

A specialized version of prepare_allocation.

fn try_prepare_slice_allocation<T>( &self, len: usize, ) -> Result<NonNull<[T]>, AllocError>

A specialized version of prepare_allocation.

unsafe fn allocate_prepared_slice<T>( &self, ptr: NonNull<T>, len: usize, cap: usize, ) -> NonNull<[T]>

A specialized version of allocate_prepared.

fn prepare_slice_allocation_rev<T>(&self, len: usize) -> (NonNull<T>, usize)

A specialized version of prepare_allocation_rev.

fn try_prepare_slice_allocation_rev<T>( &self, len: usize, ) -> Result<(NonNull<T>, usize), AllocError>

A specialized version of prepare_allocation_rev.

unsafe fn allocate_prepared_slice_rev<T>( &self, ptr: NonNull<T>, len: usize, cap: usize, ) -> NonNull<[T]>

A specialized version of allocate_prepared_rev.

fn reserve(&self, additional: usize)

Reserves capacity for at least additional more bytes to be bump allocated. The bump allocator may reserve more space to avoid frequent reallocations. After calling reserve, self.stats().remaining() will be greater than or equal to additional. Does nothing if the capacity is already sufficient.

fn try_reserve(&self, additional: usize) -> Result<(), AllocError>

Reserves capacity for at least additional more bytes to be bump allocated. The bump allocator may reserve more space to avoid frequent reallocations. After calling reserve, self.stats().remaining() will be greater than or equal to additional. Does nothing if the capacity is already sufficient.

fn dealloc<T: ?Sized>(&self, boxed: BumpBox<'_, T>)

Drops an allocated value and attempts to free its memory.

impl<A, S> Debug for Bump<A, S>

where A: Allocator, S: BumpAllocatorSettings,

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

Formats the value using the given formatter.

impl<A, S> Default for Bump<A, S>

where A: Allocator + Default, S: BumpAllocatorSettings<GuaranteedAllocated = False>,

fn default() -> Self

Returns the “default value” for a type.

impl<A, S> Drop for Bump<A, S>

where A: Allocator, S: BumpAllocatorSettings,

fn drop(&mut self)

Executes the destructor for this type.

impl<'b, A, S> From<&'b Bump<A, S>> for &'b BumpScope<'b, A, S>

where A: Allocator, S: BumpAllocatorSettings,

fn from(value: &'b Bump<A, S>) -> Self

Converts to this type from the input type.

impl<'b, A, S> From<&'b mut Bump<A, S>> for &'b mut BumpScope<'b, A, S>

where A: Allocator, S: BumpAllocatorSettings,

fn from(value: &'b mut Bump<A, S>) -> Self

Converts to this type from the input type.

impl<'a, A, S> BumpAllocatorCoreScope<'a> for &'a Bump<A, S>

where A: Allocator, S: BumpAllocatorSettings,

impl<'a, A, S> BumpAllocatorCoreScope<'a> for &'a mut Bump<A, S>

where A: Allocator, S: BumpAllocatorSettings,

impl<A, S> MutBumpAllocatorCore for Bump<A, S>

where A: Allocator, S: BumpAllocatorSettings,

impl<A, S> RefUnwindSafe for Bump<A, S>

where A: Allocator + RefUnwindSafe, S: BumpAllocatorSettings,

impl<A, S> Send for Bump<A, S>

where A: Allocator, S: BumpAllocatorSettings,

impl<A, S> UnwindSafe for Bump<A, S>

where A: Allocator + UnwindSafe, S: BumpAllocatorSettings,