Trait BumpAllocator 

pub unsafe trait BumpAllocator: Allocator + Sealed {
    // Required methods
    fn any_stats(&self) -> AnyStats<'_>;
    fn checkpoint(&self) -> Checkpoint;
    unsafe fn reset_to(&self, checkpoint: Checkpoint);
    fn prepare_allocation(
        &self,
        layout: Layout,
    ) -> Result<Range<NonNull<u8>>, AllocError>;
    unsafe fn allocate_prepared(
        &self,
        layout: Layout,
        range: Range<NonNull<u8>>,
    ) -> NonNull<u8>;
    unsafe fn allocate_prepared_rev(
        &self,
        layout: Layout,
        range: Range<NonNull<u8>>,
    ) -> NonNull<u8>;
}

A bump allocator.

This trait provides additional methods and guarantees on top of an Allocator.

A BumpAllocator has laxer safety conditions when using Allocator methods:

• You can call grow*, shrink and deallocate with pointers that did not come from this allocator. In this case:
  • grow* will always allocate a new memory block.
  • deallocate will do nothing
  • shrink will either do nothing or allocate iff the alignment increases
• Memory blocks can be split.
• deallocate can be called with any pointer or alignment when the size is 0.
• shrink never errors unless the new alignment is greater

Those invariants are used here:

• Handling of foreign pointers is necessary for implementing BumpVec::from_parts, BumpBox::into_box and Bump(Scope)::dealloc.
• Memory block splitting is necessary for split_off and split_at.
• Deallocate with a size of 0 is used in the drop implementation of BumpVec.
• The non-erroring behavior of shrink is necessary for BumpAllocatorExt::shrink_slice

Safety

An implementor must support the conditions described above.

Required Methods

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.

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

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

fn test(bump: impl BumpAllocator) {
    let checkpoint = bump.checkpoint();
     
    {
        let hello = bump.allocate(Layout::new::<[u8;5]>()).unwrap();
        assert_eq!(bump.any_stats().allocated(), 5);
    }
     
    unsafe { bump.reset_to(checkpoint); }
    assert_eq!(bump.any_stats().allocated(), 0);
}

test(<Bump>::new());
test(Bump::<Global, 1, true, false>::unallocated());

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

Both the start and the end of the range is aligned to layout.align().

The pointer range takes up as much of the free space of the chunk as possible while satisfying the other conditions.

Errors

Errors if the allocation fails.

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.

Safety

• range must have been returned from a call to prepare_allocation
• no allocation, grow, shrink or deallocate must have taken place since then
• no resets must have taken place since then
• layout must be less than or equal to the layout used when calling prepare_allocation, both in size and alignment

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 call starting at the end.

Safety

• range must have been returned from a call to prepare_allocation
• no allocation, grow, shrink or deallocate must have taken place since then
• no resets must have taken place since then
• layout must be less than or equal to the layout used when calling prepare_allocation, both in size and alignment

Trait Implementations

impl BumpAllocatorExt for dyn BumpAllocator + '_

type Stats<'b> = AnyStats<'b> where Self: 'b

The type returned by the stats method.

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

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.

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.

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

A specialized version of allocate_prepared_rev.

Implementations on Foreign Types

impl<B: BumpAllocator + ?Sized> BumpAllocator for &B

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

fn checkpoint(&self) -> Checkpoint

unsafe fn reset_to(&self, checkpoint: Checkpoint)

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

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

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

impl<B: BumpAllocator + ?Sized> BumpAllocator for &mut B

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

fn checkpoint(&self) -> Checkpoint

unsafe fn reset_to(&self, checkpoint: Checkpoint)

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

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

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

Implementors

impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool, const DEALLOCATES: bool> BumpAllocator for Bump<A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED, DEALLOCATES>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

impl<A, const MIN_ALIGN: usize, const UP: bool, const GUARANTEED_ALLOCATED: bool, const DEALLOCATES: bool> BumpAllocator for BumpScope<'_, A, MIN_ALIGN, UP, GUARANTEED_ALLOCATED, DEALLOCATES>

where MinimumAlignment<MIN_ALIGN>: SupportedMinimumAlignment, A: BaseAllocator<GUARANTEED_ALLOCATED>,

impl<B: BumpAllocator> BumpAllocator for WithoutDealloc<B>

impl<B: BumpAllocator> BumpAllocator for WithoutShrink<B>