Struct BlinkAlloc

pub struct BlinkAlloc<A: Allocator = Global> { /* private fields */ }

Single-threaded blink allocator.

Blink-allocator is arena-based allocator that allocates memory in growing chunks and serve allocations from them. When chunk is exhausted a new larger chunk is allocated.

Deallocation is no-op. BlinkAlloc can be reset to free all chunks except the last one, that will be reused.

Blink allocator aims to allocate a chunk large enough to serve all allocations between resets.

A shared and mutable reference to the BlinkAlloc implement Allocator trait. When “nightly” feature is enabled, Allocator trait is core::alloc::Allocator. Otherwise it is duplicated trait defined in allocator-api2.

Resetting blink allocator requires mutable borrow, so it is not possible to do while shared borrow is alive. That matches requirement of Allocator trait - while Allocator instance (a shared reference to BlinkAlloc) or any of its clones are alive, allocated memory must be valid.

This version of blink-allocator is single-threaded. It is possible to send to another thread, but cannot be shared. Internally it uses Cell for interior mutability and requires that state cannot be changed from another thread.

For multi-threaded version see SyncBlinkAlloc. Requires "sync" feature.

Example

let mut blink = BlinkAlloc::new();
let layout = std::alloc::Layout::new::<[u32; 8]>();
let ptr = blink.allocate(layout).unwrap();
let ptr = NonNull::new(ptr.as_ptr() as *mut u8).unwrap(); // Method for this is unstable.

unsafe {
    std::ptr::write(ptr.as_ptr().cast(), [1, 2, 3, 4, 5, 6, 7, 8]);
}

blink.reset();

Example that uses nightly’s allocator_api

let mut blink = BlinkAlloc::new();
let mut vec = Vec::new_in(&blink);
vec.push(1);
vec.extend(1..3);
vec.extend(3..10);
drop(vec);
blink.reset();

Implementations

impl BlinkAlloc<Global>

pub const fn new() -> Self

Creates new blink allocator that uses global allocator to allocate memory chunks.

See BlinkAlloc::new_in for using custom allocator.

pub const fn with_chunk_size(chunk_size: usize) -> Self

Creates new blink allocator that uses global allocator to allocate memory chunks. With this method you can specify initial chunk size.

See BlinkAlloc::new_in for using custom allocator.

impl<A> BlinkAlloc<A>

where A: Allocator,

pub const fn new_in(allocator: A) -> Self

Creates new blink allocator that uses provided allocator to allocate memory chunks.

See BlinkAlloc::new for using global allocator.

pub const fn inner(&self) -> &A

Returns reference to the underlying allocator used by this blink allocator.

pub const fn with_chunk_size_in(chunk_size: usize, allocator: A) -> Self

Creates new blink allocator that uses global allocator to allocate memory chunks. With this method you can specify initial chunk size.

See BlinkAlloc::new_in for using custom allocator.

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

Allocates memory with specified layout from this allocator. If needed it will allocate new chunk using underlying allocator. If chunk allocation fails, it will return Err.

pub unsafe fn resize( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

Resizes memory allocation. Potentially happens in-place.

Safety

ptr must be a pointer previously returned by allocate. old_size must be in range layout.size()..=slice.len() where layout is the layout used in the call to allocate. and slice is the slice pointer returned by allocate.

On success, the old pointer is invalidated and the new pointer is returned. On error old allocation is still valid.

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

Deallocates memory previously allocated from this allocator.

This call may not actually free memory. All memory is guaranteed to be freed on reset call.

Safety

ptr must be a pointer previously returned by allocate. size must be in range layout.size()..=slice.len() where layout is the layout used in the call to allocate. and slice is the slice pointer returned by allocate.

pub fn reset(&mut self)

Resets this allocator, deallocating all chunks except the last one. Last chunk will be reused. With steady memory usage after few iterations one chunk should be sufficient for all allocations between resets.

pub fn reset_final(&mut self)

Resets this allocator, deallocating all chunks.

pub unsafe fn reset_unchecked(&self)

Resets this allocator, deallocating all chunks except the last one. Last chunk will be reused. With steady memory usage after few iterations one chunk should be sufficient for all allocations between resets.

Safety

Blink-allocators guarantee that memory can be used while shared borrow to the allocator is held, preventing safe fn reset call.

With this method it becomes caller responsibility to ensure that allocated memory won’t be used after reset.

pub fn into_inner(self) -> A

Unwrap this allocator, returning the underlying allocator. Leaks allocated chunks.

To deallocate all chunks call reset_final first.

Trait Implementations

impl<A> Allocator for &mut BlinkAlloc<A>

where A: Allocator,

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

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to allocate a block of memory.

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

🔬This is a nightly-only experimental API. (allocator_api)

Behaves like allocate, but also ensures that the returned memory is zero-initialized.

unsafe fn shrink( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to shrink the memory block.

unsafe fn grow( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to extend the memory block.

unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)

🔬This is a nightly-only experimental API. (allocator_api)

Deallocates the memory referenced by ptr.

unsafe fn grow_zeroed( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

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

fn by_ref(&self) -> &Self

where Self: Sized,

🔬This is a nightly-only experimental API. (allocator_api)

Creates a “by reference” adapter for this instance of Allocator.

impl<A> Allocator for BlinkAlloc<A>

where A: Allocator,

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

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to allocate a block of memory.

unsafe fn shrink( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to shrink the memory block.

unsafe fn grow( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

Attempts to extend the memory block.

unsafe fn deallocate(&self, ptr: NonNull<u8>, layout: Layout)

🔬This is a nightly-only experimental API. (allocator_api)

Deallocates the memory referenced by ptr.

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

🔬This is a nightly-only experimental API. (allocator_api)

Behaves like allocate, but also ensures that the returned memory is zero-initialized.

unsafe fn grow_zeroed( &self, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout, ) -> Result<NonNull<[u8]>, AllocError>

🔬This is a nightly-only experimental API. (allocator_api)

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

fn by_ref(&self) -> &Self

where Self: Sized,

🔬This is a nightly-only experimental API. (allocator_api)

Creates a “by reference” adapter for this instance of Allocator.

impl<A> BlinkAllocator for BlinkAlloc<A>

where A: Allocator,

fn reset(&mut self)

Resets allocator potentially invalidating all allocations made from this instance. This is no-op if allocator is Clone (typically shared reference to blink-allocator).

impl<A> Default for BlinkAlloc<A>

where A: Allocator + Default,

fn default() -> Self

Returns the “default value” for a type.

impl<A> Drop for BlinkAlloc<A>

where A: Allocator,

fn drop(&mut self)

Executes the destructor for this type.