Struct bump_into::BumpInto

pub struct BumpInto<'a> { /* fields omitted */ }

A bump allocator sourcing space from an &mut [MaybeUninit].

Allocation methods produce mutable references with lifetimes tied to the lifetime of the backing slice, meaning the BumpInto itself can be freely moved around, including between threads.

Values held in BumpInto allocations are never dropped. If they must be dropped, you can use core::mem::ManuallyDrop::drop or core::ptr::drop_in_place to drop them explicitly (and unsafely). In safe code, you can allocate an Option and drop the value inside by overwriting it with None.

Implementations

impl<'a> BumpInto<'a>

pub fn from_slice<S>(array: &'a mut [MaybeUninit<S>]) -> Self

Creates a new BumpInto, wrapping a slice of MaybeUninit<S>.

pub fn available_bytes(&self) -> usize

Returns the number of bytes remaining in the allocator's space.

pub fn available_spaces<S: Into<usize>, A: Into<usize>>(
    &self,
    size: S,
    align: A
) -> usize

Returns the number of spaces of size size that could be allocated in a contiguous region ending at alignment align within the allocator's remaining space.

Returns usize::MAX if size is zero.

Panics

Panics if align is zero.

pub fn available_spaces_for<T>(&self) -> usize

Returns the number of T that could be allocated in a contiguous region within the allocator's remaining space.

Returns usize::MAX if T is a zero-sized type.

pub fn alloc_space<S: Into<usize>, A: Into<usize>>(
    &self,
    size: S,
    align: A
) -> *mut MaybeUninit<u8>

Tries to allocate size bytes with alignment align. Returns a null pointer on failure.

Panics

Panics if align is zero.

pub fn alloc_space_for<T>(&self) -> *mut T

Tries to allocate enough space to store a T. Returns a properly aligned pointer to uninitialized T if there was enough space; otherwise returns a null pointer.

pub fn alloc_space_for_n<T>(&self, count: usize) -> *mut T

Tries to allocate enough space to store count number of T. Returns a properly aligned pointer to uninitialized T if there was enough space; otherwise returns a null pointer.

pub fn alloc_space_to_limit_for<T>(&self) -> (NonNull<T>, usize)

Allocates space for as many aligned T as will fit in the free space of this BumpInto. Returns a tuple holding a pointer to the lowest T-space that was just allocated and the count of T that will fit (which may be zero).

This method will produce a count of usize::MAX if T is a zero-sized type.

pub fn alloc<T>(&self, x: T) -> Result<&'a mut T, T>

Tries to allocate enough space to store a T and place x there.

On success (i.e. if there was enough space) produces a mutable reference to x with the lifetime of this BumpInto's backing slice ('a).

On failure, produces x.

pub fn alloc_with<T, F: FnOnce() -> T>(&self, f: F) -> Result<&'a mut T, F>

Tries to allocate enough space to store a T and place the result of calling f there.

On success (i.e. if there was enough space) produces a mutable reference to the stored result with the lifetime of this BumpInto's backing slice ('a).

On failure, produces f.

Allocating within f is allowed; f is only called after the initial allocation succeeds.

pub fn alloc_slice<T: Copy>(&self, xs: &[T]) -> Option<&'a mut [T]>

Tries to allocate enough space to store a copy of xs and copy xs into it.

On success (i.e. if there was enough space) produces a mutable reference to the copy with the lifetime of this BumpInto's backing slice ('a).

pub fn alloc_n_with<T, I: IntoIterator<Item = T>>(
    &self,
    count: usize,
    iter: I
) -> Result<&'a mut [T], I>

Tries to allocate enough space to store count number of T and fill it with the values produced by iter.into_iter().

On success (i.e. if there was enough space) produces a mutable reference to the stored results as a slice, with the lifetime of this BumpInto's backing slice ('a).

On failure, produces iter.

If the iterator ends before producing enough items to fill the allocated space, the same amount of space is allocated, but the returned slice is just long enough to hold the items that were actually produced.

Allocating within the iterator's next method is allowed; iteration only begins after the initial allocation succeeds.

pub fn alloc_down_with<T, I: IntoIterator<Item = T>>(
    &mut self,
    iter: I
) -> &'a mut [T]

Allocates enough space to store as many of the values produced by iter.into_iter() as possible. Produces a mutable reference to the stored results as a slice, in the opposite order to the order they were produced in, with the lifetime of this BumpInto's backing slice ('a).

This method will create a slice of up to usize::MAX elements if T is a zero-sized type. This means it technically will not try to exhaust an infinite iterator, but it may still take much longer than expected in generic code!

If you have only a shared reference, and especially if you must call non-allocating methods of self within the iterator, you can use the unsafe alloc_down_with_shared.

pub unsafe fn alloc_down_with_shared<T, I: IntoIterator<Item = T>>(
    &self,
    iter: I
) -> &'a mut [T]

Unsafe version of alloc_down_with, taking self as a shared reference instead of a mutable reference.

Safety

Undefined behavior may result if any methods of this BumpInto are called from within the next method of the iterator, with the exception of the available_bytes, available_spaces, and available_spaces_for methods, which are safe.

Trait Implementations

impl<'a> Debug for BumpInto<'a>

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

Formats the value using the given formatter.