Struct SecStackSinglePageAlloc

pub struct SecStackSinglePageAlloc { /* private fields */ }

Memory allocator for confidential memory. See the module level documentation.

Memory allocator which is backed by a single page of memory. Allocation works like in a bump allocator. This is very efficient for stacked allocations, i.e. a latter allocation drops before an earlier allocation. If allocations are deallocated in a different order, then memory can not be reused until everything is deallocated.

Since the allocator is backed by a single page, only 4 KiB of memory (on Linux with default configuration) can be allocated with a single. Exceeding this limit causes the allocator to error on allocation requests!

This is not a zero sized type and should not be dropped before all it’s memory is deallocated. The same allocator instance must be used for allocation and deallocation.

Panics

If debug assertions are enabled, some of the safety requirement for using the allocator are checked. In addition, memory leaks are then checked (at drop). Therefore, memory allocated with this allocated should not leak!

Errors

Allocation functions return errors when the requested allocation does not fit what is left of the backing page of memory. In addition, zero sized allocations are not allowed (but cause only an allocation error, no UB like with GlobalAlloc).

Memory fragmentation

This allocator is basically a bump allocator, and hence suffers from memory fragmentation: memory can only be reused once all allocations are deallocated, or if the allocator is used in a strictly (first-in last-out) stack like manner with at most 8 byte aligned allocations. When the allocator is used for a bunch of allocations which need to live for approximately the same lifetime memory fragmentation is not an issue. Otherwise, it might be a good idea to use the allocation in a filo stack like manner, that is, always only deallocate, shrink or grow the last created allocation, and request at most 8 byte alignment for all but the first allocation.

Implementations

impl SecStackSinglePageAlloc

pub fn new() -> Result<Self, PageAllocError>

Create a new SecStackSinglePageAlloc allocator. This allocates one page of memory to be used by the allocator. This page is only released once the allocator is dropped.

Errors

The function returns an PageAllocError if no page could be allocated by the system or if the page could not be locked. The second can be caused either by memory starvation of the system or the process exceeding the amount of memory it is allowed to lock.

For unprivileged processes amount of memory that locked is very limited on Linux. A process with CAP_SYS_RESOURCE can change the mlock limit using setrlimit from libc.

impl SecStackSinglePageAlloc

pub unsafe fn allocate_zerosized(align: usize) -> NonNull<[u8]>

Create a zero-sized allocation.

Safety

align must be a power of 2

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

Reallocate allocation into a smaller one.

This won’t try to reuse the existing allocation but forces a new allocation. Useful if the existing allocation e.g. doesn’t have the correct alignment.

Self::shrink falls back to this function if the current allocation cannot be reused.

Safety

Safety contract of this function is identical to that of Allocator::shrink.

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

Reallocate allocation into a larger one.

This won’t try to reuse the existing allocation but forces a new allocation. Useful if the existing allocation e.g. doesn’t have the correct alignment, or is not the last one on the memory page.

Self::grow and Self::grow_zeroed fall back to this function if the current allocation cannot be reused.

Safety

Safety contract of this function is identical to that of Allocator::grow.

Trait Implementations

impl Allocator for SecStackSinglePageAlloc

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.

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 deallocate(&self, ptr: NonNull<u8>, layout: Layout)

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

Deallocates the memory referenced by ptr.

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_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.

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.

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 Drop for SecStackSinglePageAlloc

fn drop(&mut self)

Executes the destructor for this type.