pub struct SecStackSinglePageAlloc<Z: MemZeroizer = DefaultMemZeroizer> { /* private fields */ }
Expand description

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

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.

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.

Create a zero-sized allocation.

Safety

align must be a power of 2

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.

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

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

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

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

Attempts to allocate a block of memory. Read more

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

Deallocates the memory referenced by ptr. Read more

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

Attempts to shrink the memory block. Read more

🔬 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. Read more

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

Attempts to extend the memory block. Read more

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

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

Executes the destructor for this type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.