Struct Bump

pub struct Bump<Size, Align = Size>(/* private fields */);

A bump allocator that allocates memory in non-amortized O(1) (constant) time.

The allocator internally uses fixed-size chunks of memory. The size and alignment of each chunk of memory is determined by the type parameters Size and Align: the size is mem::size_of::<Size>() and the alignment is mem::align_of::<Align>(). The default value of Align is Size, so you can specify both the size and alignment with a single type parameter.

A common use of this type, and the most space-efficient way to use it, is to allocate many values of the same type (or at least the same size and alignment). In this case, it may be convenient to specify the chunk size using an array type: to use properly aligned chunks large enough to allocate n values of type T, pass [T; n] as the Size parameter, which will also be the Align parameter by default.

Implementations

impl<Size, Align> Bump<Size, Align>

pub fn new() -> Self

Creates a new Bump.

pub fn allocate(&self, layout: Layout) -> Option<NonNull<[u8]>>

Tries to allocate memory with a size and alignment matching layout.

Returns a pointer to the memory on success, or None on failure. The memory is valid until the Bump is dropped. Note that the returned memory could be larger than layout.size().

This method is similar to Allocator::allocate, except it returns an Option instead of a Result.

Allocation is guaranteed to succeed, assuming the global allocator succeeds, if layout.size() is less than or equal to mem::size_of::<Size>() and layout.align() is less than or equal to mem::align_of::<Align>(). See Self::can_allocate.

pub fn alloc_value<T>(&self, value: T) -> &mut T

Allocates a value of type T.

The memory is initialized with value and a reference to the value is returned. Note that the value’s destructor will not be called automatically.

Panics

Panics if this allocator cannot allocate memory matching Layout::new::<T>() (see Self::can_allocate). Note that if the global allocator fails, handle_alloc_error is called instead of panicking.

For an equivalent that doesn’t panic or call handle_alloc_error, see Self::try_alloc_value.

pub fn try_alloc_value<T>(&self, value: T) -> Result<&mut T, T>

Tries to allocate a value of type T.

If the allocation succeeds, the memory is initialized with value and a reference to the value is returned. Note that the value’s destructor will not be called automatically.

Allocation succeeds if and only if Self::allocate is able to allocate memory matching Layout::new::<T>(). See Self::allocate for details regarding the circumstances in which allocation can fail.

Errors

If allocation fails, Err(value) is returned.

pub fn can_allocate(&self, layout: Layout) -> bool

Returns whether this allocator can allocate memory matching layout.

This is guaranteed to return true if layout.size() is less than or equal to mem::size_of::<Size>() and layout.align() is less than or equal to mem::align_of::<Align>(). It may return true if the alignment is bigger, but never if the size is.

Trait Implementations

impl<Size, Align> Allocator for Bump<Size, Align>

Available on crate features allocator_api or allocator-fallback only.

fn allocate(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to allocate a block of memory.

unsafe fn deallocate(&self, _ptr: NonNull<u8>, _layout: Layout)

🔬This is a nightly-only experimental API. (allocator_api)

Deallocates the memory referenced by ptr.

fn allocate_zeroed(&self, layout: Layout) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Behaves like allocate, but also ensures that the returned memory is zero-initialized.

unsafe fn grow( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to extend the memory block.

unsafe fn grow_zeroed( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

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>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to shrink the memory block.

fn by_ref(&self) -> &Self

where Self: Sized,

🔬This is a nightly-only experimental API. (allocator_api)

Creates a “by reference” adapter for this instance of Allocator.

impl<Size, Align> Default for Bump<Size, Align>

fn default() -> Self

Returns the “default value” for a type.