Struct bump_scope::BumpScope

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

A bump allocation scope whose allocations are valid for the lifetime of its associated BumpScopeGuard or closure.

Alternatively a Bump can be turned into a BumpScope with as_scope, as_mut_scope and into.

You can see examples in the crate documentation.

Implementations

impl<'a, A: Allocator + Clone, const MIN_ALIGN: usize, const UP: bool> BumpScope<'a, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,

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

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(), 12);
});

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

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

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

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

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

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(), 12);
}

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

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

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

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

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

Returns Stats, which provides statistics about the memory usage of the bump allocator.

pub fn checkpoint(&self) -> Checkpoint

Creates a checkpoint of the current bump position.

Examples

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(&mut 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

pub fn allocator(&self) -> &A

Returns a reference to the underlying allocator.

pub fn without_dealloc(&self) -> WithoutDealloc<&Self>

Wraps &self in WithoutDealloc so that deallocate becomes a no-op.

pub fn without_shrink(&self) -> WithoutShrink<&Self>

Wraps &self in WithoutShrink so that shrink becomes a no-op.

pub fn as_scope(&self) -> &Self

Returns &self as is. This is used in for macros that support both Bump and BumpScope, like mut_bump_vec!.

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, like mut_bump_vec!.

pub fn into_aligned<const NEW_MIN_ALIGN: usize>( self ) -> BumpScope<'a, A, NEW_MIN_ALIGN, UP>

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

Converts this BumpScope into a BumpScope with a new minimum alignment.

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

This mustn't decrease alignment because otherwise you could do this:

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

{
    let scope = guard.scope().into_aligned::<1>();
    scope.alloc(0u8);      
}

{
    let scope = guard.scope();
    // scope is not aligned to `MIN_ALIGN`!!
}

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

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

Mutably borrows BumpScope with a new minimum alignment.

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

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

Converts this BumpScope into a raw pointer.

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

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

Safety

This is highly unsafe, due to the number of invariants that aren’t checked:

• ptr must have been created with Self::into_raw.
• This function must only be called once with this ptr.
• The lifetime must be the original one.
• Nothing must have been allocated since then.

impl<'a, A: Allocator + Clone, const MIN_ALIGN: usize, const UP: bool> BumpScope<'a, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,

Functions to allocate. Available as fallible or infallible.

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

Allocate an object.

Panics

Panics if the allocation fails.

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

Pre-allocate space for an object. Once space is allocated f will be called to create the value to be put at that place. In some situations this can help the compiler realize that T can be constructed at the allocated space instead of having to copy it over.

Panics

Panics if the allocation fails.

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.

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

Allocate a slice and Copy elements from an existing slice.

Panics

Panics if the allocation fails.

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

Allocate a slice and Clone elements from an existing slice.

Panics

Panics if the allocation fails.

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.

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 (try_)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.

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

Allocate a str.

Panics

Panics if the allocation fails.

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

Allocate a str from format arguments. For better performance prefer alloc_fmt_mut.

Panics

Panics if the allocation fails.

Panics if a formatting trait implementation returned an error.

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 alloc_fmt_mut(&mut self, args: Arguments<'_>) -> BumpBox<'a, str>

Allocate a str from format arguments. Unlike alloc_fmt, this function requires a mutable Bump(Scope).

Panics

Panics if the allocation fails.

Panics if a formatting trait implementation returned an error.

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 alloc_iter<T>( &self, iter: impl IntoIterator<Item = T> ) -> BumpBox<'a, [T]>

Allocate elements of an iterator into a slice. For better performance prefer alloc_iter_exact or alloc_iter_mut(_rev).

Panics

Panics if the allocation fails.

Examples

let slice = bump.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.

Panics if the supplied iterator returns fewer elements than it promised.

Examples

let slice = bump.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. Unlike alloc_iter, this function requires a mutable Bump(Scope).

When bumping downwards, prefer alloc_iter_mut_rev or alloc_iter_exact as in this case this function incurs an additional copy of the slice internally.

Panics

Panics if the allocation fails.

Examples

let slice = bump.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.

When bumping upwards, prefer alloc_iter_mut or alloc_iter_exact as in this case this function incurs an additional copy of the slice internally.

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 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 mut bump: Bump = Bump::new();
let mut five = bump.alloc_uninit();

let five = five.init(5);

assert_eq!(*five, 5)

Unsafely:

let mut bump: Bump = Bump::new();
let mut five = bump.alloc_uninit();

let five = unsafe {
    five.write(5);
    five.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 or unsafely with assume_init.

Panics

Panics if the allocation fails.

Examples

Safely:

let bump: Bump = Bump::new();
let mut values = bump.alloc_uninit_slice(3);

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

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

Unsafely:

let bump: Bump = Bump::new();
let mut values = bump.alloc_uninit_slice(3);

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

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

Panics

Panics if the allocation fails.

pub fn alloc_fixed_vec<T>(&self, len: usize) -> FixedBumpVec<'a, T>

Allocate a FixedBumpVec with the given capacity.

Panics

Panics if the allocation fails.

Examples

let mut values = bump.alloc_fixed_vec(3);
values.push(1);
values.push(2);
values.push(3);
assert_eq!(values, [1, 2, 3])

pub fn alloc_fixed_string(&self, len: usize) -> FixedBumpString<'a>

Allocate a FixedBumpString with the given capacity.

Panics

Panics if the allocation fails.

Examples

let mut values = bump.alloc_fixed_vec(3);
values.push(1);
values.push(2);
values.push(3);
assert_eq!(values, [1, 2, 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 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, chunks().remaining() will be greater than or equal to additional. Does nothing if capacity is already sufficient.

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_alloc<T>(&self, value: T) -> Result<BumpBox<'a, T>, AllocError>

Allocate an object.

Errors

Errors if the allocation fails.

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

Pre-allocate space for an object. Once space is allocated f will be called to create the value to be put at that place. In some situations this can help the compiler realize that T can be constructed at the allocated space instead of having to copy it over.

Errors

Errors if the allocation fails.

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.

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

Allocate a slice and Copy elements from an existing slice.

Errors

Errors if the allocation fails.

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

Allocate a slice and Clone elements from an existing slice.

Errors

Errors if the allocation fails.

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.

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.

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

Allocate a str.

Errors

Errors if the allocation fails.

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

Allocate a str from format arguments. For better performance prefer try_alloc_fmt_mut.

Errors

Errors if the allocation fails.

Errors if a formatting trait implementation returned an error.

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

Allocate a str from format arguments. Unlike try_alloc_fmt, this function requires a mutable Bump(Scope).

Errors

Errors if the allocation fails.

Errors if a formatting trait implementation returned an error.

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. For better performance prefer try_alloc_iter_exact or try_alloc_iter_mut(_rev).

Errors

Errors if the allocation fails.

Examples

let slice = bump.alloc_iter([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.

Panics

Panics if the supplied iterator returns fewer elements than it promised.

Errors

Errors if the allocation fails.

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. Unlike try_alloc_iter, this function requires a mutable Bump(Scope).

When bumping downwards, prefer try_alloc_iter_mut_rev or try_alloc_iter_exact as in this case this function incurs an additional copy of the slice internally.

Errors

Errors 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_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.

When bumping upwards, prefer try_alloc_iter_mut or try_alloc_iter_exact as in this case this function incurs an additional copy of the slice internally.

Errors

Errors if the allocation fails.

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 mut bump: Bump = Bump::new();
let mut five = bump.alloc_uninit();

let five = five.init(5);

assert_eq!(*five, 5)

Unsafely:

let mut bump: Bump = Bump::new();
let mut five = bump.alloc_uninit();

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

assert_eq!(*five, 5)

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 or unsafely with assume_init.

Errors

Errors if the allocation fails.

Examples

Safely:

let bump: Bump = Bump::new();
let mut values = bump.alloc_uninit_slice(3);

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

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

Unsafely:

let bump: Bump = Bump::new();
let mut values = bump.alloc_uninit_slice(3);

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

    values.assume_init()
};

assert_eq!(*values, [1, 2, 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 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.

pub fn try_alloc_fixed_vec<T>( &self, len: usize ) -> Result<FixedBumpVec<'a, T>, AllocError>

Allocate a FixedBumpVec with the given capacity.

Errors

Errors if the allocation fails.

Examples

let mut values = bump.alloc_fixed_vec(3);
values.push(1);
values.push(2);
values.push(3);
assert_eq!(values, [1, 2, 3])

pub fn try_alloc_fixed_string( &self, len: usize ) -> Result<FixedBumpString<'a>, AllocError>

Allocate a FixedBumpString with the given capacity.

Errors

Errors if the allocation fails.

Examples

let mut values = bump.alloc_fixed_vec(3);
values.push(1);
values.push(2);
values.push(3);
assert_eq!(values, [1, 2, 3])

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 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, chunks().remaining() will be greater than or equal to additional. Does nothing if capacity is already sufficient.

Errors

Errors if the allocation fails.

Examples

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

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

Trait Implementations

impl<A: Allocator + Clone, const MIN_ALIGN: usize, const UP: bool> Allocator for BumpScope<'_, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,

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: Allocator + Clone, const MIN_ALIGN: usize, const UP: bool> Debug for BumpScope<'_, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,

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

Formats the value using the given formatter.

impl<'b, A: Allocator + Clone, const MIN_ALIGN: usize, const UP: bool> From<&'b Bump<A, MIN_ALIGN, UP>> for &'b BumpScope<'b, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,

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

Converts to this type from the input type.

impl<'b, A: Allocator + Clone, const MIN_ALIGN: usize, const UP: bool> From<&'b mut Bump<A, MIN_ALIGN, UP>> for &'b mut BumpScope<'b, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,

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

Converts to this type from the input type.

impl<A: Allocator + Clone, const MIN_ALIGN: usize, const UP: bool> BumpAllocator for BumpScope<'_, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment,

impl<const MIN_ALIGN: usize, const UP: bool, A> RefUnwindSafe for BumpScope<'_, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: Allocator + Clone + UnwindSafe,

impl<const MIN_ALIGN: usize, const UP: bool, A> UnwindSafe for BumpScope<'_, A, MIN_ALIGN, UP>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: Allocator + Clone + UnwindSafe,