Trait BumpAllocatorScope 

pub trait BumpAllocatorScope<'a>: BumpAllocator + MutBumpAllocatorCoreScope<'a> {
    // Required methods
    fn claim(&self) -> BumpClaimGuard<'_, 'a, Self::Allocator, Self::Settings>;
    fn stats(&self) -> Stats<'a, Self::Allocator, Self::Settings>;
    fn aligned<const NEW_MIN_ALIGN: usize, R>(
        &mut self,
        f: impl FnOnce(&mut BumpScope<'a, Self::Allocator, <Self::Settings as BumpAllocatorSettings>::WithMinimumAlignment<NEW_MIN_ALIGN>>) -> R,
    ) -> R
       where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment;
    fn allocator(&self) -> Option<&'a Self::Allocator>;
}

A bump allocator scope.

Required Methods

fn claim(&self) -> BumpClaimGuard<'_, 'a, Self::Allocator, Self::Settings>

Claims exclusive access to the bump allocator from a shared reference.

This makes it possible to enter scopes while a there are still outstanding references to that bump allocator.

The claim call replaces this allocator with a dummy allocator while the returned BumpClaimGuard is live. This dummy allocator errors on allocate / grow, does nothing on deallocate / shrink and reports an empty bump allocator from the stats api.

Panics

Panics if the bump allocator is already claimed.

Examples

use bump_scope::{Bump, BumpVec, bump_vec};

let bump: Bump = Bump::new();
let vec1: BumpVec<u8, _> = bump_vec![in &bump; 1, 2, 3];
let vec2: BumpVec<u8, _> = bump_vec![in &bump; 4, 5, 6];

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

assert_eq!(vec1, [1, 2, 3]);
assert_eq!(vec2, [4, 5, 6]);

fn stats(&self) -> Stats<'a, Self::Allocator, Self::Settings>

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

fn aligned<const NEW_MIN_ALIGN: usize, R>( &mut self, f: impl FnOnce(&mut BumpScope<'a, Self::Allocator, <Self::Settings as BumpAllocatorSettings>::WithMinimumAlignment<NEW_MIN_ALIGN>>) -> 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().unwrap().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:

type Settings = <BumpSettings as BumpAllocatorSettings>::WithMinimumAlignment<8>;

let mut bump: Bump<Global, Settings> = 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().unwrap().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);

fn allocator(&self) -> Option<&'a Self::Allocator>

Returns a reference to the base allocator.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types

impl<'a, B> BumpAllocatorScope<'a> for &mut B

where B: BumpAllocatorScope<'a>,

fn claim(&self) -> BumpClaimGuard<'_, 'a, Self::Allocator, Self::Settings>

fn stats(&self) -> Stats<'a, Self::Allocator, Self::Settings>

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

where MinimumAlignment<NEW_MIN_ALIGN>: SupportedMinimumAlignment,

fn allocator(&self) -> Option<&'a Self::Allocator>

Implementors

impl<'a, A, S> BumpAllocatorScope<'a> for BumpScope<'a, A, S>

where A: BaseAllocator<S::GuaranteedAllocated>, S: BumpAllocatorSettings,