Struct static_alloc::bump::Level

pub struct Level(/* private fields */);

Specifies an amount of consumed space of a slab.

Each allocation of the Bump increases the current level as they must not be empty. By ensuring that an allocation is performed at a specific level it is thus possible to check that multiple allocations happened in succession without other intermediate allocations. This ability in turns makes it possible to group allocations together, for example to initialize a #[repr(C)] struct member-by-member or to extend a slice.

Usage

The main use is successively allocating a slice without requiring all data to be present at once. Other similar interface often require an internal locking mechanism but Level leaves the choice to the user. This is not yet encapsulate in a safe API yet Level makes it easy to reason about.

See MemBump::get_unchecked for redeeming a value.

Unsound usage.

FIXME: the below is UB because we don’t gain provenance over the complete array, only each individual element. Instead, we must derive a new pointer from the allocator!

static BUMP: Bump<[u64; 4]> = Bump::uninit();

/// Gathers as much data as possible.
///
/// An arbitrary amount of data, can't stack allocate!
fn gather_data(mut iter: impl Iterator<Item=u64>) -> &'static mut [u64] {
    let first = match iter.next() {
        Some(item) => item,
        None => return &mut [],
    };

    let mut level: Level = BUMP.level();
    let mut begin: *mut u64;
    let mut count;

    match BUMP.leak_at(first, level) {
        Ok((first, first_level)) => {
            begin = first;
            level = first_level;
            count = 1;
        },
        _ => return &mut [],
    }

    let _ = iter.try_for_each(|value: u64| {
        match BUMP.leak_at(value, level) {
            Err(err) => return Err(err),
            Ok((_, new_level)) => level = new_level,
        };
        count += 1;
        Ok(())
    });

    unsafe {
        // SAFETY: all `count` allocations are contiguous, begin is well aligned and no
        // reference is currently pointing at any of the values. The lifetime is `'static` as
        // the BUMP itself is static.
        slice::from_raw_parts_mut(begin, count)
    }
}

fn main() {
    // There is no other thread running, so this succeeds.
    let slice = gather_data(0..=3);
    assert_eq!(slice, [0, 1, 2, 3]);
}

Trait Implementations

impl Clone for Level

fn clone(&self) -> Level

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Level

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

Formats the value using the given formatter.

impl Hash for Level

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Level

fn cmp(&self, other: &Level) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for Level

fn eq(&self, other: &Level) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Level

fn partial_cmp(&self, other: &Level) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Level

impl Eq for Level

impl StructuralPartialEq for Level