Struct slab_alloc::SlabAllocBuilder

pub struct SlabAllocBuilder<T, I: InitSystem> { /* fields omitted */ }

A builder for SlabAllocs.

Methods

impl<T, I: InitSystem> SlabAllocBuilder<T, I>

fn align(self, align: usize) -> SlabAllocBuilder<T, I>

Updates the alignment guaranteed by the allocator.

align must not be greater than the size of T (that is, core::mem::size_of::<T>()), must not be greater than the system's page size, and must be a power of two. The size of T must be a multiple of align.

If align is called multiple times, then the largest specified alignment will be used. Since all alignments must be powers of two, allocations which satisfy the largest specified alignment will also satisfy all smaller alignments.

fn build(self) -> SlabAlloc<T, I, HeapBackingAlloc>

Builds a SlabAlloc whose memory is backed by the heap.

fn build_mmap(self) -> SlabAlloc<T, I, MmapBackingAlloc>

Builds a SlabAlloc whose memory is backed by mmap.

On Unix and Linux, mmap is used. On Windows, VirtualAlloc is used.

fn build_untyped(self) -> UntypedSlabAlloc<I, HeapBackingAlloc>

Builds an UntypedSlabAlloc whose memory is backed by the heap.

fn build_untyped_mmap(self) -> UntypedSlabAlloc<I, MmapBackingAlloc>

Builds an UntypedSlabAlloc whose memory is backed by mmap.

On Unix and Linux, mmap is used. On Windows, VirtualAlloc is used.

fn build_backing<B, A, L>(
    self,
    get_aligned: A,
    get_large: L
) -> SlabAlloc<T, I, B> where
    B: BackingAlloc,
    A: Fn(Layout) -> Option<B::Aligned>,
    L: Fn(Layout) -> B::Large, 

Builds a new SlabAlloc with a custom memory provider.

build_backing builds a new SlabAlloc from the configuration self. SlabAllocs get their memory from UntypedObjectAllocs which allocate the memory necessary to back a single slab. Under the hood, slab allocators use two types of slabs - "aligned" slabs and "large" slabs. Aligned slabs perform better, but are not always supported for all slab sizes. Large slabs do not perform as well, but are supported for all slab sizes. In particular, aligned slabs require that the memory used to back them is aligned to its own size (ie, a 16K slab has alignment 16K, etc), while large slabs only require page alignment regardless of the slab size. All slabs are always at least one page in size and are always page-aligned at a minimum.

Because support for a particular slab size may not be knowable until runtime (e.g., it may depend on the page size, which can vary by system), which slab type will be used cannot be known at compile time. Instead, build_backing computes the ideal aligned slab size, and calls get_aligned with a Layout describing that size. get_aligned returns an Option - None if the requested size is not supported, and Some if the size is supported. If the size is not supported, build_backing will fall back to using large slabs, and will call get_large to get an allocator. It will only call get_large with a Layout that is required to be supported (at least a page in size and page-aligned), so get_large returns an allocator directly rather than an Option.

fn build_untyped_backing<B, A, L>(
    self,
    get_aligned: A,
    get_large: L
) -> UntypedSlabAlloc<I, B> where
    B: BackingAlloc,
    A: Fn(Layout) -> Option<B::Aligned>,
    L: Fn(Layout) -> B::Large, 

Builds a new UntypedSlabAlloc with a custom memory provider.

build_untyped_backing is like build_backing, except that it builds an UntypedSlabAlloc instead of a SlabAlloc.

impl<T: Default> SlabAllocBuilder<T, InitInitSystem<T, DefaultInitializer<T>>>

fn default() -> SlabAllocBuilder<T, InitInitSystem<T, DefaultInitializer<T>>>

Constructs a new builder for an allocator which uses T::default to initialize allocated objects.

The constructed allocator will call T::default whenever a new object needs to be initialized.

impl<T, F: Fn() -> T> SlabAllocBuilder<T, InitInitSystem<T, FnInitializer<T, F>>>

fn func(f: F) -> SlabAllocBuilder<T, InitInitSystem<T, FnInitializer<T, F>>>

Constructs a new builder for an allocator which uses f to initialize allocated objects.

The constructed allocator will call f whenever a new object needs to be initialized.

impl<T, F: Fn(*mut T)> SlabAllocBuilder<T, InitInitSystem<T, UnsafeFnInitializer<T, F>>>

unsafe fn unsafe_func(
    f: F
) -> SlabAllocBuilder<T, InitInitSystem<T, UnsafeFnInitializer<T, F>>>

Constructs a new builder for an allocator which uses f to initialize allocated objects.

The constructed allocator will call f whenever a new object needs to be initialized. A pointer to the uninitialized memory will be passed, and it is f's responsibility to initialize this memory to a valid instance of T.

Safety

This function is unsafe because passing a function which does not abide by the documented contract could result in an allocator handing out uninitialized or invalid memory.

impl<T> SlabAllocBuilder<T, NopInitSystem>

unsafe fn no_initialize() -> SlabAllocBuilder<T, NopInitSystem>

Constructs a new builder for an allocator which does not initialize allocated objects. Objects returned by alloc are not guaranteed to be valid instances of T.

Safety

This function is unsafe because it constructs an allocator which will hand out uninitialized memory.