Struct BoundedAllocator 

pub struct BoundedAllocator<const MAX_BLOCKS: usize, const BLOCK_SIZE: usize, const BITMAP_WORDS: usize> { /* private fields */ }

Static pre-allocated bounded global allocator.

Generic parameters

• MAX_BLOCKS — maximum number of simultaneously-live blocks.
• BLOCK_SIZE — maximum bytes per allocation. Should be a multiple of 64 to avoid intra-block padding.
• BITMAP_WORDS — must be (MAX_BLOCKS + 63) / 64. Use the declare_global_allocator! / bounded_allocator! macros to compute it automatically.

Implementations

impl<const MAX_BLOCKS: usize, const BLOCK_SIZE: usize, const BITMAP_WORDS: usize> BoundedAllocator<MAX_BLOCKS, BLOCK_SIZE, BITMAP_WORDS>

pub const fn new() -> Self

Construct a fresh allocator. Intended for use as a static initialiser.

All bitmap words are initialised to all-ones, meaning every block is free. The few tail bits past MAX_BLOCKS in the last word are also set, but the bit-scan refuses to allocate them (block index >= MAX_BLOCKS rejection).

pub fn lock(&self)

Engage lock-after-init mode. Every subsequent alloc call panics immediately. One-way: there is no unlock method.

pub fn is_locked(&self) -> bool

Is the allocator locked? See Self::lock.

pub fn alloc_count(&self) -> usize

Total successful alloc calls since process start.

Examples found in repository

examples/fail_closed.rs (line 48)

fn main() {
    println!("taktora-bounded-alloc fail_closed demo");
    println!("arena: {MAX_BLOCKS} blocks × {BLOCK_SIZE} bytes");
    println!(
        "blocks already in use after Rust runtime startup: {}",
        ALLOC.live_blocks()
    );
    println!();

    let mut held: Vec<Box<[u8; 1024]>> = Vec::new();
    for i in 0_u32..64 {
        let b: Box<[u8; 1024]> = Box::new([(i & 0xff) as u8; 1024]);
        held.push(b);
        println!(
            "iter {i}: alloc_count={}, live={}, peak={}, held={}",
            ALLOC.alloc_count(),
            ALLOC.live_blocks(),
            ALLOC.peak_blocks_used(),
            held.len()
        );
    }

    // Unreachable: an allocation past the cap returns null, and
    // Rust's default alloc_error_handler aborts the process.
    println!("unexpectedly reached end of main (cap was not exhausted)");
}

pub fn dealloc_count(&self) -> usize

Total dealloc calls since process start.

pub fn peak_blocks_used(&self) -> usize

High-water mark of simultaneously-live blocks.

Examples found in repository

examples/fail_closed.rs (line 50)

fn main() {
    println!("taktora-bounded-alloc fail_closed demo");
    println!("arena: {MAX_BLOCKS} blocks × {BLOCK_SIZE} bytes");
    println!(
        "blocks already in use after Rust runtime startup: {}",
        ALLOC.live_blocks()
    );
    println!();

    let mut held: Vec<Box<[u8; 1024]>> = Vec::new();
    for i in 0_u32..64 {
        let b: Box<[u8; 1024]> = Box::new([(i & 0xff) as u8; 1024]);
        held.push(b);
        println!(
            "iter {i}: alloc_count={}, live={}, peak={}, held={}",
            ALLOC.alloc_count(),
            ALLOC.live_blocks(),
            ALLOC.peak_blocks_used(),
            held.len()
        );
    }

    // Unreachable: an allocation past the cap returns null, and
    // Rust's default alloc_error_handler aborts the process.
    println!("unexpectedly reached end of main (cap was not exhausted)");
}

pub fn live_blocks(&self) -> usize

Currently-live block count.

Examples found in repository

examples/fail_closed.rs (line 38)

fn main() {
    println!("taktora-bounded-alloc fail_closed demo");
    println!("arena: {MAX_BLOCKS} blocks × {BLOCK_SIZE} bytes");
    println!(
        "blocks already in use after Rust runtime startup: {}",
        ALLOC.live_blocks()
    );
    println!();

    let mut held: Vec<Box<[u8; 1024]>> = Vec::new();
    for i in 0_u32..64 {
        let b: Box<[u8; 1024]> = Box::new([(i & 0xff) as u8; 1024]);
        held.push(b);
        println!(
            "iter {i}: alloc_count={}, live={}, peak={}, held={}",
            ALLOC.alloc_count(),
            ALLOC.live_blocks(),
            ALLOC.peak_blocks_used(),
            held.len()
        );
    }

    // Unreachable: an allocation past the cap returns null, and
    // Rust's default alloc_error_handler aborts the process.
    println!("unexpectedly reached end of main (cap was not exhausted)");
}

pub const fn capacity_bytes(&self) -> usize

Total arena bytes addressed by this allocator.

Trait Implementations

impl<const MAX_BLOCKS: usize, const BLOCK_SIZE: usize, const BITMAP_WORDS: usize> Default for BoundedAllocator<MAX_BLOCKS, BLOCK_SIZE, BITMAP_WORDS>

fn default() -> Self

Returns the “default value” for a type.

impl<const MAX_BLOCKS: usize, const BLOCK_SIZE: usize, const BITMAP_WORDS: usize> GlobalAlloc for BoundedAllocator<MAX_BLOCKS, BLOCK_SIZE, BITMAP_WORDS>

unsafe fn alloc(&self, layout: Layout) -> *mut u8

Allocates memory as described by the given layout.

unsafe fn dealloc(&self, ptr: *mut u8, _layout: Layout)

Deallocates the block of memory at the given ptr pointer with the given layout.

unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8

Behaves like alloc, but also ensures that the contents are set to zero before being returned.

unsafe fn realloc( &self, ptr: *mut u8, layout: Layout, new_size: usize, ) -> *mut u8

Shrinks or grows a block of memory to the given new_size in bytes. The block is described by the given ptr pointer and layout.