Trait BumpAllocatorCore 

pub unsafe trait BumpAllocatorCore: Allocator + Sealed {
    // Required methods
    fn any_stats(&self) -> AnyStats<'_>;
    fn checkpoint(&self) -> Checkpoint;
    unsafe fn reset_to(&self, checkpoint: Checkpoint);
    fn is_claimed(&self) -> bool;
    fn prepare_allocation(
        &self,
        layout: Layout,
    ) -> Result<Range<NonNull<u8>>, AllocError>;
    unsafe fn allocate_prepared(
        &self,
        layout: Layout,
        range: Range<NonNull<u8>>,
    ) -> NonNull<u8>;
    fn prepare_allocation_rev(
        &self,
        layout: Layout,
    ) -> Result<Range<NonNull<u8>>, AllocError>;
    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 BumpAllocatorCore has laxer safety conditions when using Allocator methods:

• You can call grow*, shrink and deallocate with pointers that came from a different BumpAllocatorCore. 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.
• shrink never errors unless the new alignment is greater
• deallocate may always be called when the pointer address is less than 16 and the size is 0

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.
• The non-erroring behavior of shrink is necessary for BumpAllocatorTyped::shrink_slice
• deallocate with a dangling pointer is used in the drop implementation of BumpString

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
• the bump allocator must be unclaimed at the time the checkpoint is created and when this function is called

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);

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

The start 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
• the bump allocator must be unclaimed at the time prepare_allocation was called and when calling this function

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

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

Safety

• range must have been returned from a call to prepare_allocation_rev
• 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_rev, both in size and alignment
• the bump allocator must be unclaimed at the time prepare_allocation_rev was called and when calling this function

Trait Implementations

impl BumpAllocatorTyped for dyn BumpAllocatorCore + '_

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

The type returned by the stats method.

fn typed_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.

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.

Implementations on Foreign Types

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

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

fn checkpoint(&self) -> Checkpoint

unsafe fn reset_to(&self, checkpoint: Checkpoint)

fn is_claimed(&self) -> bool

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

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

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

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

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

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

fn checkpoint(&self) -> Checkpoint

unsafe fn reset_to(&self, checkpoint: Checkpoint)

fn is_claimed(&self) -> bool

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

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

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

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

Implementors

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

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

impl<A, S> BumpAllocatorCore for BumpScope<'_, A, S>

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

impl<B: BumpAllocatorCore> BumpAllocatorCore for WithoutDealloc<B>

impl<B: BumpAllocatorCore> BumpAllocatorCore for WithoutShrink<B>