Struct Allocation

pub struct Allocation { /* private fields */ }

An allocation backed by raw virtual memory, giving you the power to directly manipulate the pages within it.

See also the crate-level documentation for more information about virtual memory.

Implementations

impl Allocation

pub fn new(size: usize) -> Result<Self>

Allocates a new region in the process’s virtual address space.

size is the size to reserve in bytes. This number can be excessively huge, as none of the memory is committed until you call commit. The memory is unreserved when the Allocation is dropped.

Errors

Returns an error if the operating system returns an error.

Panics

• Panics if size is not aligned to the page size.
• Panics if size is zero.

pub const fn dangling(alignment: usize) -> Allocation

Creates a dangling Allocation, that is, an allocation with a dangling pointer and zero size.

This is useful as a placeholder value to defer allocation until later or if no allocation is needed.

alignment is the alignment of the allocation’s pointer, and must be a power of two.

Panics

Panics if alignment is not a power of two.

pub const fn ptr(&self) -> *mut u8

Returns the pointer to the beginning of the allocation.

The returned pointer is always valid, including dangling allocations, for reads and writes of size() bytes in the sense that it can never lead to undefined behavior. However, doing a read or write access to pages that have not been committed will result in the process receiving SIGSEGV / STATUS_ACCESS_VIOLATION.

The pointer must not be accessed after self has been dropped.

pub const fn size(&self) -> usize

Returns the size that was used to allocate self.

pub fn commit(&self, ptr: *mut u8, size: usize) -> Result<()>

Commits the given region of memory.

Errors

Returns an error if the operating system returns an error.

Panics

• Panics if the allocation is dangling.
• Panics if ptr and size denote a region that is out of bounds of the allocation.
• Panics if ptr and/or size is not aligned to the page size.
• Panics if size is zero.

pub fn decommit(&self, ptr: *mut u8, size: usize) -> Result<()>

Decommits the given region of memory.

Errors

Returns an error if the operating system returns an error.

Panics

• Panics if the allocation is dangling.
• Panics if ptr and size denote a region that is out of bounds of the allocation.
• Panics if ptr and/or size is not aligned to the page size.
• Panics if size is zero.

pub fn prefault(&self, ptr: *mut u8, size: usize) -> Result<()>

Prefaults the given region of memory.

Errors

Returns an error if the operating system returns an error.

Panics

• Panics if the allocation is dangling.
• Panics if ptr and size denote a region that is out of bounds of the allocation.
• Panics if ptr and/or size is not aligned to the page size.
• Panics if size is zero.

Trait Implementations

impl Debug for Allocation

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

Formats the value using the given formatter.