Struct BumpPoolGuard 

pub struct BumpPoolGuard<'a, A = Global, const MIN_ALIGN: usize = 1, const UP: bool = true>
where
    MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,
    A: Allocator,
{ /* private fields */ }

Available on crate feature std only.

This is a wrapper around Bump that mutably derefs to a BumpScope and returns its Bump back to the BumpPool on drop.

Implementations

impl<'a, A, const MIN_ALIGN: usize, const UP: bool> BumpPoolGuard<'a, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: Allocator,

pub fn pool(&self) -> &'a BumpPool<A, MIN_ALIGN, UP>

The BumpPool, this BumpPoolGuard was created from.

Methods from Deref<Target = BumpScope<'a, A, MIN_ALIGN, UP, true, true>>

pub fn allocator(&self) -> &'a A

Returns a reference to the base allocator.

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

Calls f with a new child scope.

Examples

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

bump.scoped(|bump| {
    bump.alloc_str("Hello, world!");
    assert_eq!(bump.stats().allocated(), 13);
});

assert_eq!(bump.stats().allocated(), 0);

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

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

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

Examples

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

// bump starts off by being aligned to 16
assert!(bump.stats().current_chunk().bump_position().is_aligned_to(16));

// allocate one byte
bump.alloc(1u8);

// now the bump is only aligned to 1
// (if our `MIN_ALIGN` was higher, it would be that)
assert!(bump.stats().current_chunk().bump_position().addr().get() % 2 == 1);
assert_eq!(bump.stats().allocated(), 1);

bump.scoped_aligned::<8, ()>(|bump| {
   // in here, the bump will have the specified minimum alignment of 8
   assert!(bump.stats().current_chunk().bump_position().is_aligned_to(8));
   assert_eq!(bump.stats().allocated(), 8);

   // allocating a value with its size being a multiple of 8 will no longer have
   // to align the bump pointer before allocation
   bump.alloc(1u64);
   assert!(bump.stats().current_chunk().bump_position().is_aligned_to(8));
   assert_eq!(bump.stats().allocated(), 16);
    
   // allocating a value smaller than the minimum alignment must align the bump pointer
   // after the allocation, resulting in some wasted space
   bump.alloc(1u8);
   assert!(bump.stats().current_chunk().bump_position().is_aligned_to(8));
   assert_eq!(bump.stats().allocated(), 24);
});

assert_eq!(bump.stats().allocated(), 1);

pub fn aligned<const NEW_MIN_ALIGN: usize, R>( &mut self, f: impl FnOnce(BumpScope<'a, A, NEW_MIN_ALIGN, UP, true, DEALLOCATES>) -> R, ) -> R

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

Calls f with this scope but with a new minimum alignment.

Examples

Increase the minimum alignment:

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

// here we're allocating with a `MIN_ALIGN` of `1`
let foo = bump.alloc_str("foo");
assert_eq!(bump.stats().allocated(), 3);

let bar = bump.aligned::<8, _>(|bump| {
    // in here the bump position has been aligned to `8`
    assert_eq!(bump.stats().allocated(), 8);
    assert!(bump.stats().current_chunk().bump_position().is_aligned_to(8));

    // make some allocations that benefit from the higher `MIN_ALIGN` of `8`
    let bar = bump.alloc(0u64);
    assert_eq!(bump.stats().allocated(), 16);
  
    // the bump position will stay aligned to `8`
    bump.alloc(0u8);
    assert_eq!(bump.stats().allocated(), 24);

    bar
});

assert_eq!(bump.stats().allocated(), 24);

// continue making allocations with a `MIN_ALIGN` of `1`
let baz = bump.alloc_str("baz");
assert_eq!(bump.stats().allocated(), 24 + 3);

dbg!(foo, bar, baz);

Decrease the minimum alignment:

let mut bump: Bump<Global, 8> = Bump::new();
let bump = bump.as_mut_scope();

// make some allocations that benefit from the `MIN_ALIGN` of `8`
let foo = bump.alloc(0u64);

let bar = bump.aligned::<1, _>(|bump| {
    // make some allocations that benefit from the lower `MIN_ALIGN` of `1`
    let bar = bump.alloc(0u8);

    // the bump position will not get aligned to `8` in here
    assert_eq!(bump.stats().allocated(), 8 + 1);

    bar
});

// after `aligned()`, the bump position will be aligned to `8` again
// to satisfy our `MIN_ALIGN`
assert!(bump.stats().current_chunk().bump_position().is_aligned_to(8));
assert_eq!(bump.stats().allocated(), 16);

// continue making allocations that benefit from the `MIN_ALIGN` of `8`
let baz = bump.alloc(0u64);

dbg!(foo, bar, baz);

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

Creates a new BumpScopeGuard.

This allows for creation of child scopes.

Examples

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

{
    let mut guard = bump.scope_guard();
    let bump = guard.scope();
    bump.alloc_str("Hello, world!");
    assert_eq!(bump.stats().allocated(), 13);
}

assert_eq!(bump.stats().allocated(), 0);

pub fn allocator(&self) -> Option<&'a A>

Returns a reference to the base allocator.

pub fn checkpoint(&self) -> Checkpoint

Creates a checkpoint of the current bump position.

The bump position can be reset to this checkpoint with reset_to.

Examples

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

{
    let hello = bump.alloc_str("hello");
    assert_eq!(bump.stats().allocated(), 5);
}

unsafe { bump.reset_to(checkpoint); }
assert_eq!(bump.stats().allocated(), 0);

pub 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.

Safety

• the checkpoint must have been created by this bump allocator
• the bump allocator must not have been reset since creation of this checkpoint
• there must be no references to allocations made since creation of this checkpoint
• the checkpoint must not have been created by an!GUARANTEED_ALLOCATED when self is GUARANTEED_ALLOCATED

Examples

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

{
    let hello = bump.alloc_str("hello");
    assert_eq!(bump.stats().allocated(), 5);
}

unsafe { bump.reset_to(checkpoint); }
assert_eq!(bump.stats().allocated(), 0);

pub fn stats(&self) -> Stats<'a, A, UP, GUARANTEED_ALLOCATED>

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

pub fn as_not_guaranteed_allocated( &self, ) -> &BumpScope<'a, A, MIN_ALIGN, UP, false, DEALLOCATES>

Borrows BumpScope as a not guaranteed allocated BumpScope.

Note that it’s not possible to mutably borrow as a not guaranteed allocated bump allocator. That’s because a user could mem::swap it with an actual unallocated bump allocator which in turn would make &mut self unallocated.

pub fn as_mut_aligned<const NEW_MIN_ALIGN: usize>( &mut self, ) -> &mut BumpScope<'a, A, NEW_MIN_ALIGN, UP, GUARANTEED_ALLOCATED, DEALLOCATES>

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

Mutably borrows BumpScope with a new minimum alignment.

This cannot decrease the alignment. Trying to decrease alignment will result in a compile error. You can use aligned or scoped_aligned to decrease the alignment.

When decreasing the alignment we need to make sure that the bump position is realigned to the original alignment. That can only be ensured by having a function that takes a closure, like the methods mentioned above do.

pub fn as_scope(&self) -> &Self

Returns &self as is. This is useful for macros that support both Bump and BumpScope.

pub fn as_mut_scope(&mut self) -> &mut Self

Returns &mut self as is. This is useful for macros that support both Bump and BumpScope.

pub fn as_without_dealloc( &self, ) -> &BumpScope<'a, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED, false>

Turns off deallocation and shrinking.

pub fn as_mut_without_dealloc( &mut self, ) -> &mut BumpScope<'a, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED, false>

Turns off deallocation and shrinking.

pub fn as_with_dealloc( &self, ) -> &BumpScope<'a, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED, true>

Turns on deallocation and shrinking.

pub fn as_mut_with_dealloc( &mut self, ) -> &mut BumpScope<'a, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED, true>

Turns on deallocation and shrinking.

pub fn as_guaranteed_allocated( &self, f: impl FnOnce() -> Bump<A, MIN_ALIGN, UP, true, DEALLOCATES>, ) -> &BumpScope<'a, A, MIN_ALIGN, UP, true, DEALLOCATES>

Borrows BumpScope as a guaranteed allocated BumpScope.

See Bump::as_guaranteed_allocated.

Panics

Panics if the closure panics.

pub fn try_as_guaranteed_allocated( &self, f: impl FnOnce() -> Result<Bump<A, MIN_ALIGN, UP, true, DEALLOCATES>, AllocError>, ) -> Result<&BumpScope<'a, A, MIN_ALIGN, UP, true, DEALLOCATES>, AllocError>

Borrows BumpScope as a guaranteed allocated BumpScope.

See Bump::try_as_guaranteed_allocated.

Errors

Errors if the closure fails.

pub fn as_mut_guaranteed_allocated( &mut self, f: impl FnOnce() -> Bump<A, MIN_ALIGN, UP, true, DEALLOCATES>, ) -> &mut BumpScope<'a, A, MIN_ALIGN, UP, true, DEALLOCATES>

Mutably borrows BumpScope as a guaranteed allocated BumpScope.

See Bump::as_mut_guaranteed_allocated.

Panics

Panics if the closure panics.

pub fn try_as_mut_guaranteed_allocated( &mut self, f: impl FnOnce() -> Result<Bump<A, MIN_ALIGN, UP, true, DEALLOCATES>, AllocError>, ) -> Result<&mut BumpScope<'a, A, MIN_ALIGN, UP, true, DEALLOCATES>, AllocError>

Mutably borrows BumpScope as a guaranteed allocated BumpScope.

See Bump::try_as_mut_guaranteed_allocated.

Errors

Errors if the closure fails.

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

Allocate an object.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc(123);
assert_eq!(allocated, 123);

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

Allocate an object.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc(123)?;
assert_eq!(allocated, 123);

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

Allocates space for an object, then calls f to produce the value to be put in that place.

In some cases this could be more performant than alloc(f()) because it permits the compiler to directly place T in the allocated memory instead of constructing it on the stack and copying it over.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_with(|| 123);
assert_eq!(allocated, 123);

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

Allocates space for an object, then calls f to produce the value to be put in that place.

In some cases this could be more performant than try_alloc(f()) because it permits the compiler to directly place T in the allocated memory instead of constructing it on the stack and copying it over.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_with(|| 123)?;
assert_eq!(allocated, 123);

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

Allocate an object with its default value.

This is equivalent to alloc_with(T::default).

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_default::<i32>();
assert_eq!(allocated, 0);

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

Allocate an object with its default value.

This is equivalent to try_alloc_with(T::default).

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_default()?;
assert_eq!(allocated, 0);

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

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

Allocate an object by cloning it.

Unlike alloc(value.clone()) this method also works for dynamically-sized types.

Panics

Panics if the allocation fails.

Examples

Allocate a slice, str, CStr, Path:

#![feature(clone_to_uninit)]

use std::path::Path;

let cloned = bump.alloc_clone(&[1, 2, 3]);
assert_eq!(cloned, &[1, 2, 3]);

let cloned = bump.alloc_clone("foo");
assert_eq!(cloned, "foo");

let cloned = bump.alloc_clone(c"foo");
assert_eq!(cloned, c"foo");

let cloned = bump.alloc_clone(Path::new("foo"));
assert_eq!(cloned, Path::new("foo"));

Allocate a trait object:

#![feature(clone_to_uninit)]

use core::clone::CloneToUninit;

trait FnClone: Fn() -> String + CloneToUninit {}
impl<T: ?Sized + Fn() -> String + CloneToUninit> FnClone for T {}

// the closure references a local variable
let reference = &String::from("Hello,");

// and owns a string that it will have to clone
let value = String::from("world!");

let closure = move || format!("{reference} {value}");
let object: &dyn FnClone = &closure;

assert_eq!(object(), "Hello, world!");

let bump: Bump = Bump::new();
let object_clone = bump.alloc_clone(object);

assert_eq!(object_clone(), "Hello, world!");

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

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

Allocate an object by cloning it.

Unlike alloc(value.clone()) this method also works for dynamically-sized types.

Errors

Errors if the allocation fails.

Examples

Allocate a slice, str, CStr, Path:

#![feature(clone_to_uninit)]

use std::path::Path;

let cloned = bump.try_alloc_clone(&[1, 2, 3])?;
assert_eq!(cloned, &[1, 2, 3]);

let cloned = bump.try_alloc_clone("foo")?;
assert_eq!(cloned, "foo");

let cloned = bump.try_alloc_clone(c"foo")?;
assert_eq!(cloned, c"foo");

let cloned = bump.try_alloc_clone(Path::new("foo"))?;
assert_eq!(cloned, Path::new("foo"));

Allocate a trait object:

#![feature(clone_to_uninit)]

use core::clone::CloneToUninit;

trait FnClone: Fn() -> String + CloneToUninit {}
impl<T: ?Sized + Fn() -> String + CloneToUninit> FnClone for T {}

// the closure references a local variable
let reference = &String::from("Hello,");

// and owns a string that it will have to clone
let value = String::from("world!");

let closure = move || format!("{reference} {value}");
let object: &dyn FnClone = &closure;

assert_eq!(object(), "Hello, world!");

let bump: Bump = Bump::try_new()?;
let object_clone = bump.try_alloc_clone(object)?;

assert_eq!(object_clone(), "Hello, world!");

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

Allocate a slice and fill it by moving elements from an existing slice.

Panics

Panics if the allocation fails.

Examples

// by value
let a = bump.alloc_slice_move([1, 2]);
let b = bump.alloc_slice_move(vec![3, 4]);
let c = bump.alloc_slice_move(bump.alloc_iter(5..=6));

// by mutable reference
let mut other = vec![7, 8];
let d = bump.alloc_slice_move(&mut other);
assert!(other.is_empty());

assert_eq!(a, [1, 2]);
assert_eq!(b, [3, 4]);
assert_eq!(c, [5, 6]);
assert_eq!(d, [7, 8]);

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

Allocate a slice and fill it by moving elements from an existing slice.

Errors

Errors if the allocation fails.

Examples

// by value
let a = bump.try_alloc_slice_move([1, 2])?;
let b = bump.try_alloc_slice_move(vec![3, 4])?;
let c = bump.try_alloc_slice_move(bump.alloc_iter(5..=6))?;

// by mutable reference
let mut other = vec![7, 8];
let d = bump.try_alloc_slice_move(&mut other)?;
assert!(other.is_empty());

assert_eq!(a, [1, 2]);
assert_eq!(b, [3, 4]);
assert_eq!(c, [5, 6]);
assert_eq!(d, [7, 8]);

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

Allocate a slice and fill it by Copying elements from an existing slice.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_slice_copy(&[1, 2, 3]);
assert_eq!(allocated, [1, 2, 3]);

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

Allocate a slice and fill it by Copying elements from an existing slice.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_slice_copy(&[1, 2, 3])?;
assert_eq!(allocated, [1, 2, 3]);

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

Allocate a slice and fill it by Cloneing elements from an existing slice.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_slice_clone(&[String::from("a"), String::from("b")]);
assert_eq!(allocated, [String::from("a"), String::from("b")]);

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

Allocate a slice and fill it by Cloneing elements from an existing slice.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_slice_clone(&[String::from("a"), String::from("b")])?;
assert_eq!(allocated, [String::from("a"), String::from("b")]);

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

Allocate a slice and fill it with elements by cloning value.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_slice_fill(3, "ho");
assert_eq!(allocated, ["ho", "ho", "ho"]);

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

Allocate a slice and fill it with elements by cloning value.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_slice_fill(3, "ho")?;
assert_eq!(allocated, ["ho", "ho", "ho"]);

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

Allocates a slice by fill it with elements returned by calling a closure repeatedly.

This method uses a closure to create new values. If you’d rather Clone a given value, use alloc_slice_fill. If you want to use the Default trait to generate values, you can pass Default::default as the argument.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_slice_fill_with::<i32>(3, Default::default);
assert_eq!(allocated, [0, 0, 0]);

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

Allocates a slice by fill it with elements returned by calling a closure repeatedly.

This method uses a closure to create new values. If you’d rather Clone a given value, use try_alloc_slice_fill. If you want to use the Default trait to generate values, you can pass Default::default as the argument.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_slice_fill_with::<i32>(3, Default::default)?;
assert_eq!(allocated, [0, 0, 0]);

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

Allocate a str.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_str("Hello, world!");
assert_eq!(allocated, "Hello, world!");

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

Allocate a str.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_str("Hello, world!")?;
assert_eq!(allocated, "Hello, world!");

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

Allocate a str from format arguments.

If you have a &mut self you can use alloc_fmt_mut instead for better performance.

Panics

Panics if the allocation fails.

This technically also panics if the fmt() implementation returned an Error, but since fmt() implementors should only error when writing to the stream fails, that should be equivalent to an allocation failure.

Examples

let one = 1;
let two = 2;
let string = bump.alloc_fmt(format_args!("{one} + {two} = {}", one + two));

assert_eq!(string, "1 + 2 = 3");

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

Allocate a str from format arguments.

If you have a &mut self you can use try_alloc_fmt_mut instead for better performance.

Errors

Errors if the allocation fails.

This technically also errors if the fmt() implementation returned an Error, but since fmt() implementors should only error when writing to the stream fails, that should be equivalent to an allocation failure.

Examples

let one = 1;
let two = 2;
let string = bump.try_alloc_fmt(format_args!("{one} + {two} = {}", one + two))?;

assert_eq!(string, "1 + 2 = 3");

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

Allocate a str from format arguments.

This function is designed as a performance improvement over alloc_fmt. By taking self as &mut, it can use the entire remaining chunk space as the capacity for the temporary string buffer used for the allocation. As a result, that string buffer rarely needs to grow.

Panics

Panics if the allocation fails.

This technically also panics if the fmt() implementation returned an Error, but since fmt() implementors should only error when writing to the stream fails, that should be equivalent to an allocation failure.

Examples

let one = 1;
let two = 2;
let string = bump.alloc_fmt_mut(format_args!("{one} + {two} = {}", one + two));

assert_eq!(string, "1 + 2 = 3");

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

Allocate a str from format arguments.

This function is designed as a performance improvement over try_alloc_fmt. By taking self as &mut, it can use the entire remaining chunk space as the capacity for the temporary string buffer used for the allocation. As a result, that string buffer rarely needs to grow.

Errors

Errors if the allocation fails.

This technically also errors if the fmt() implementation returned an Error, but since fmt() implementors should only error when writing to the stream fails, that should be equivalent to an allocation failure.

Examples

let one = 1;
let two = 2;
let string = bump.try_alloc_fmt_mut(format_args!("{one} + {two} = {}", one + two))?;

assert_eq!(string, "1 + 2 = 3");

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

Allocate a CStr.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_cstr(c"Hello, world!");
assert_eq!(allocated, c"Hello, world!");

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

Allocate a CStr.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_cstr(c"Hello, world!")?;
assert_eq!(allocated, c"Hello, world!");

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

Allocate a CStr from a str.

If src contains a '\0' then the CStr will stop at the first '\0'.

Panics

Panics if the allocation fails.

Examples

let allocated = bump.alloc_cstr_from_str("Hello, world!");
assert_eq!(allocated, c"Hello, world!");

let allocated = bump.alloc_cstr_from_str("abc\0def");
assert_eq!(allocated, c"abc");

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

Allocate a CStr from a str.

If src contains a '\0' then the CStr will stop at the first '\0'.

Errors

Errors if the allocation fails.

Examples

let allocated = bump.try_alloc_cstr_from_str("Hello, world!")?;
assert_eq!(allocated, c"Hello, world!");

let allocated = bump.try_alloc_cstr_from_str("abc\0def")?;
assert_eq!(allocated, c"abc");

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

Allocate a CStr from format arguments.

If the string contains a '\0' then the CStr will stop at the first '\0'.

If you have a &mut self you can use alloc_cstr_fmt_mut instead for better performance.

Panics

Panics if the allocation fails.

This technically also panics if the fmt() implementation returned an Error, but since fmt() implementors should only error when writing to the stream fails, that should be equivalent to an allocation failure.

Examples

let one = 1;
let two = 2;
let string = bump.alloc_cstr_fmt(format_args!("{one} + {two} = {}", one + two));
assert_eq!(string, c"1 + 2 = 3");

let one = bump.alloc_cstr_fmt(format_args!("{one}\0{two}"));
assert_eq!(one, c"1");

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

Allocate a CStr from format arguments.

If the string contains a '\0' then the CStr will stop at the first '\0'.

If you have a &mut self you can use try_alloc_cstr_fmt_mut instead for better performance.

Errors

Errors if the allocation fails.

This technically also errors if the fmt() implementation returned an Error, but since fmt() implementors should only error when writing to the stream fails, that should be equivalent to an allocation failure.

Examples

let one = 1;
let two = 2;
let string = bump.try_alloc_cstr_fmt(format_args!("{one} + {two} = {}", one + two))?;
assert_eq!(string, c"1 + 2 = 3");

let one = bump.try_alloc_cstr_fmt(format_args!("{one}\0{two}"))?;
assert_eq!(one, c"1");

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

Allocate a CStr from format arguments.

If the string contains a '\0' then the CStr will stop at the first '\0'.

This function is designed as a performance improvement over alloc_cstr_fmt. By taking self as &mut, it can use the entire remaining chunk space as the capacity for the temporary string buffer used for the allocation. As a result, that string buffer rarely needs to grow.

Panics

Panics if the allocation fails.

This technically also panics if the fmt() implementation returned an Error, but since fmt() implementors should only error when writing to the stream fails, that should be equivalent to an allocation failure.

Examples

let one = 1;
let two = 2;
let string = bump.alloc_cstr_fmt_mut(format_args!("{one} + {two} = {}", one + two));
assert_eq!(string, c"1 + 2 = 3");

let one = bump.alloc_cstr_fmt_mut(format_args!("{one}\0{two}"));
assert_eq!(one, c"1");

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

Allocate a CStr from format arguments.

If the string contains a '\0' then the CStr will stop at the first '\0'.

This function is designed as a performance improvement over try_alloc_cstr_fmt. By taking self as &mut, it can use the entire remaining chunk space as the capacity for the temporary string buffer used for the allocation. As a result, that string buffer rarely needs to grow.

Errors

Errors if the allocation fails.

This technically also errors if the fmt() implementation returned an Error, but since fmt() implementors should only error when writing to the stream fails, that should be equivalent to an allocation failure.

Examples

let one = 1;
let two = 2;
let string = bump.try_alloc_cstr_fmt_mut(format_args!("{one} + {two} = {}", one + two))?;
assert_eq!(string, c"1 + 2 = 3");

let one = bump.try_alloc_cstr_fmt_mut(format_args!("{one}\0{two}"))?;
assert_eq!(one, c"1");

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

Allocate elements of an iterator into a slice.

If you have an impl ExactSizeIterator then you can use alloc_iter_exact instead for better performance.

If iter is not an ExactSizeIterator but you have a &mut self you can still get somewhat better performance by using alloc_iter_mut.

Panics

Panics if the allocation fails.

Examples

let slice = bump.alloc_iter([1, 2, 3]);
assert_eq!(slice, [1, 2, 3]);

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

Allocate elements of an iterator into a slice.

If you have an impl ExactSizeIterator then you can use try_alloc_iter_exact instead for better performance.

If iter is not an ExactSizeIterator but you have a &mut self you can still get somewhat better performance by using try_alloc_iter_mut.

Errors

Errors if the allocation fails.

Examples

let slice = bump.try_alloc_iter([1, 2, 3])?;
assert_eq!(slice, [1, 2, 3]);

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

where I: ExactSizeIterator<Item = T>,

Allocate elements of an ExactSizeIterator into a slice.

Panics

Panics if the allocation fails.

Examples

let slice = bump.alloc_iter_exact([1, 2, 3]);
assert_eq!(slice, [1, 2, 3]);

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

where I: ExactSizeIterator<Item = T>,

Allocate elements of an ExactSizeIterator into a slice.

Errors

Errors if the allocation fails.

Examples

let slice = bump.try_alloc_iter_exact([1, 2, 3])?;
assert_eq!(slice, [1, 2, 3]);

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

Allocate elements of an iterator into a slice.

This function is designed as a performance improvement over alloc_iter. By taking self as &mut, it can use the entire remaining chunk space as the capacity for the temporary vector used for the allocation. As a result, that vector rarely needs to grow.

When bumping downwards, prefer alloc_iter_mut_rev instead.

Panics

Panics if the allocation fails.

Examples

let slice = bump.alloc_iter_mut([1, 2, 3]);
assert_eq!(slice, [1, 2, 3]);

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

Allocate elements of an iterator into a slice.

This function is designed as a performance improvement over try_alloc_iter. By taking self as &mut, it can use the entire remaining chunk space as the capacity for the temporary vector used for the allocation. As a result, that vector rarely needs to grow.

When bumping downwards, prefer alloc_iter_mut_rev instead.

Errors

Errors if the allocation fails.

Examples

let slice = bump.try_alloc_iter_mut([1, 2, 3])?;
assert_eq!(slice, [1, 2, 3]);

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

Allocate elements of an iterator into a slice in reverse order.

Compared to alloc_iter_mut this function is more performant for downwards bumping allocators as the allocation for the vector can be shrunk in place without any ptr::copy.

The reverse is true when upwards allocating. In that case it’s better to use alloc_iter_mut to prevent the ptr::copy.

Panics

Panics if the allocation fails.

Examples

let slice = bump.alloc_iter_mut_rev([1, 2, 3]);
assert_eq!(slice, [3, 2, 1]);

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

Allocate elements of an iterator into a slice in reverse order.

Compared to try_alloc_iter_mut this function is more performant for downwards bumping allocators as the allocation for the vector can be shrunk in place without any ptr::copy.

The reverse is true when upwards allocating. In that case it’s better to use try_alloc_iter_mut to prevent the ptr::copy.

Errors

Errors if the allocation fails.

Examples

let slice = bump.try_alloc_iter_mut_rev([1, 2, 3])?;
assert_eq!(slice, [3, 2, 1]);

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

Allocate an unitialized object.

You can safely initialize the object with init or unsafely with assume_init.

Panics

Panics if the allocation fails.

Examples

Safely:

let uninit = bump.alloc_uninit();

let five = uninit.init(5);

assert_eq!(*five, 5)

Unsafely:

let mut uninit = bump.alloc_uninit();

let five = unsafe {
    uninit.write(5);
    uninit.assume_init()
};

assert_eq!(*five, 5)

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

Allocate an unitialized object.

You can safely initialize the object with init or unsafely with assume_init.

Errors

Errors if the allocation fails.

Examples

Safely:

let uninit = bump.try_alloc_uninit()?;

let five = uninit.init(5);

assert_eq!(*five, 5);

Unsafely:

let mut uninit = bump.try_alloc_uninit()?;

let five = unsafe {
    uninit.write(5);
    uninit.assume_init()
};

assert_eq!(*five, 5);

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

Allocate an unitialized object slice.

You can safely initialize the object with init_fill, init_fill_with, init_copy, init_clone, init_zeroed or unsafely with assume_init.

Panics

Panics if the allocation fails.

Examples

Safely:

let uninit = bump.alloc_uninit_slice(3);

let values = uninit.init_copy(&[1, 2, 3]);

assert_eq!(values, [1, 2, 3])

Unsafely:

let mut uninit = bump.alloc_uninit_slice(3);

let values = unsafe {
    uninit[0].write(1);
    uninit[1].write(2);
    uninit[2].write(3);

    uninit.assume_init()
};

assert_eq!(values, [1, 2, 3]);

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

Allocate an unitialized object slice.

You can safely initialize the object with init_fill, init_fill_with, init_copy, init_clone, init_zeroed or unsafely with assume_init.

Errors

Errors if the allocation fails.

Examples

Safely:

let uninit = bump.try_alloc_uninit_slice(3)?;

let values = uninit.init_copy(&[1, 2, 3]);

assert_eq!(values, [1, 2, 3]);

Unsafely:

let mut uninit = bump.try_alloc_uninit_slice(3)?;

let values = unsafe {
    uninit[0].write(1);
    uninit[1].write(2);
    uninit[2].write(3);

    uninit.assume_init()
};

assert_eq!(values, [1, 2, 3]);

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

Allocate an unitialized object slice.

You can safely initialize the object with init_fill, init_fill_with, init_copy, init_clone, init_zeroed or unsafely with assume_init.

This is just like alloc_uninit_slice but uses a slice to provide the len. This avoids a check for a valid layout. The elements of slice are irrelevant.

Panics

Panics if the allocation fails.

Examples

let slice = &[1, 2, 3];
let uninit_slice = bump.alloc_uninit_slice_for(slice);
assert_eq!(uninit_slice.len(), 3);

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

Allocate an unitialized object slice.

You can safely initialize the object with init_fill, init_fill_with, init_copy, init_clone, init_zeroed or unsafely with assume_init.

This is just like try_alloc_uninit_slice but uses a slice to provide the len. This avoids a check for a valid layout. The elements of slice are irrelevant.

Errors

Errors if the allocation fails.

Examples

let slice = &[1, 2, 3];
let uninit_slice = bump.try_alloc_uninit_slice_for(slice)?;
assert_eq!(uninit_slice.len(), 3);

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

Allocates memory as described by the given Layout.

Panics

Panics if the allocation fails.

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

Allocates memory as described by the given Layout.

Errors

Errors if the allocation fails.

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

Drops an allocated value and attempts to free its memory.

The memory can only be freed if this is the last allocation.

Examples

let boxed = bump.alloc(3i32);
assert_eq!(bump.stats().allocated(), 4);
bump.dealloc(boxed);
assert_eq!(bump.stats().allocated(), 0);

pub fn reserve_bytes(&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_bytes, self.stats().remaining() will be greater than or equal to additional. Does nothing if the capacity is already sufficient.

Note that these additional bytes are not necessarily in one contiguous region but might be spread out among many chunks.

Panics

Panics if the allocation fails.

Examples

let bump: Bump = Bump::new();
assert!(bump.stats().capacity() < 4096);

bump.reserve_bytes(4096);
assert!(bump.stats().capacity() >= 4096);

pub fn try_reserve_bytes(&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_bytes, self.stats().remaining() will be greater than or equal to additional. Does nothing if the capacity is already sufficient.

Errors

Errors if the allocation fails.

Examples

let bump: Bump = Bump::try_new()?;
assert!(bump.stats().capacity() < 4096);

bump.try_reserve_bytes(4096)?;
assert!(bump.stats().capacity() >= 4096);

pub fn alloc_try_with<T, E>( &self, f: impl FnOnce() -> Result<T, E>, ) -> Result<BumpBox<'a, 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<'a, 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<'a, 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<'a, 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, A, const MIN_ALIGN: usize, const UP: bool> Debug for BumpPoolGuard<'a, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: Allocator + Debug,

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

Formats the value using the given formatter.

impl<'a, A, const MIN_ALIGN: usize, const UP: bool> Deref for BumpPoolGuard<'a, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: Allocator,

type Target = BumpScope<'a, A, MIN_ALIGN, UP>

The resulting type after dereferencing.

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

Dereferences the value.

impl<A, const MIN_ALIGN: usize, const UP: bool> DerefMut for BumpPoolGuard<'_, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: Allocator,

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

Mutably dereferences the value.

impl<A, const MIN_ALIGN: usize, const UP: bool> Drop for BumpPoolGuard<'_, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: Allocator,

fn drop(&mut self)

Executes the destructor for this type.