Struct acid_alloc::Slab

pub struct Slab<A: BackingAllocator> { /* private fields */ }

A slab allocator.

For a general discussion of slab allocation, see the module-level documentation.

Configuration

Each constructor takes the following parameters:

• block_size is the size in bytes of each allocation.
• num_blocks is the maximum number of allocations that a Slab may make at once.

Blocks are packed as tightly as possible. As such, the minimum guaranteed alignment of a block is

1 << block_size.trailing_zeros()

If a higher guaranteed alignment is required, the block size must be rounded up to the proper alignment when creating the allocator. Calls to Slab::allocate with a Layout alignment greater than the minimum guaranteed alignment will result in an error.

Implementations

impl Slab<Raw>

pub unsafe fn new_raw(
    region: NonNull<u8>,
    block_size: usize,
    num_blocks: usize
) -> Result<Slab<Raw>, AllocInitError>

Constructs a new Slab from a raw pointer to a region of memory.

Errors

Returns an error if Slab::region_layout(block_size, num_blocks) would return an error due to overflow.

Safety

The caller must uphold the following invariants:

• region must be a pointer to a region that fits the Layout returned by Slab::region_layout(block_size, num_blocks), and it must be valid for reads and writes for the entire size indicated by that Layout.
• No references to the memory at region may exist when this function is called.
• As long as the returned Slab exists, no accesses may be made to the memory at region except by way of methods on the returned Slab.

impl Slab<Global>

pub fn try_new(
    block_size: usize,
    num_blocks: usize
) -> Result<Slab<Global>, AllocInitError>

Available on crate feature alloc only.

Attempts to construct a new Slab backed by the global allocator.

The memory managed by this Slab is allocated from the global allocator according to the layout indicated by Slab::region_layout(block_size, num_blocks).

Errors

Returns an error if sufficient memory could not be allocated from the global allocator.

impl<A> Slab<A> where
    A: Allocator, 

pub fn try_new_in(
    block_size: usize,
    num_blocks: usize,
    backing_allocator: A
) -> Result<Slab<A>, AllocInitError>

Available on crate feature unstable only.

Attempts to construct a new Slab backed by backing_allocator.

The memory managed by this Slab is allocated from backing_allocator according to the layout indicated by Slab::region_layout(block_size, num_blocks).

Errors

Returns an error if sufficient memory could not be allocated from backing_allocator.

impl<A> Slab<A> where
    A: BackingAllocator, 

pub fn region_layout(
    block_size: usize,
    num_blocks: usize
) -> Result<Layout, AllocInitError>

Returns the layout requirements of the region managed by a Slab of this type.

Errors

Returns Err if the total size and alignment of the region cannot be represented as a Layout.

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

Attempts to allocate a block of memory with the specified layout.

The returned block is guaranteed to be aligned to self.block_align() bytes.

Errors

Returns Err if any of the following are true:

• No blocks are available.
• layout.size() is greater than the value returned by self.block_size().
• layout.align() is greater than the value returned by self.block_align().

pub fn allocate_block(&mut self) -> Result<NonNull<[u8]>, AllocError>

Attempts to allocate a block of memory from the slab.

The returned block has a size of self.block_size() and an alignment of self.block_align().

Errors

Returns Err if no blocks are available.

pub unsafe fn deallocate(&mut self, ptr: NonNull<u8>)

Deallocates the memory referenced by ptr.

Safety

ptr must denote a block of memory currently allocated via this allocator.

pub fn block_size(&self) -> usize

Returns the size in bytes of blocks allocated by this Slab.

Example

use acid_alloc::Slab;

let slab = Slab::try_new(96, 8).unwrap();
assert_eq!(slab.block_size(), 96);

pub fn block_align(&self) -> usize

Returns the minimum alignment of blocks allocated by this Slab.

Example

use acid_alloc::Slab;

let slab = Slab::try_new(48, 12).unwrap();
assert_eq!(slab.block_align(), 16);

pub fn num_blocks(&self) -> usize

Returns the number of blocks managed by this allocator.

Example

use acid_alloc::Slab;

let slab = Slab::try_new(64, 7).unwrap();
assert_eq!(slab.num_blocks(), 7);

pub fn size(&self) -> usize

Returns the size in bytes of the managed region.

Example

use acid_alloc::Slab;

let slab = Slab::try_new(128, 4).unwrap();
assert_eq!(slab.size(), 512);

pub fn limit(&self) -> Option<NonZeroUsize>

Returns the first address above the managed region.

If the managed region ends at the end of the address space, returns None.

pub fn contains_ptr(&self, ptr: NonNull<u8>) -> bool

Returns true iff ptr is within this allocator’s managed region.

Note that a return value of true does not indicate whether or not ptr points into an outstanding allocation.

pub fn can_allocate(&self) -> bool

Returns true iff this allocator can make at least one additional allocation.

pub fn outstanding(&self) -> usize

Returns the number of outstanding allocations.

Trait Implementations

impl<A> Debug for Slab<A> where
    A: BackingAllocator, 

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

Formats the value using the given formatter.

impl<A> Drop for Slab<A> where
    A: BackingAllocator, 

fn drop(&mut self)

Executes the destructor for this type.

impl<A> Send for Slab<A> where
    A: BackingAllocator + Send, 

impl<A> Sync for Slab<A> where
    A: BackingAllocator + Sync,