SystemAllocator structv0.1.0

pub struct SystemAllocator {
    // private fields
}

Carries no state: every instance behaves identically, and one may be created wherever it is needed rather than passed around. It is Copy for that reason. Page-granular, so a small allocation costs a whole page. Use it as the backing store for an arena or a pool rather than for many small values directly.

Constructors

SystemAllocator

pub func SystemAllocator() -> SystemAllocator

Constructs a stateless system allocator. The result is structural and copyable. Borrow it as &var Allocator when a temporary interface view is sufficient; no adapter or owning conversion is required.

Returns: the allocator, which holds no state of its own

Source

Implements Allocator

SystemAllocator conforms to Allocator.

Allocate

pub func Allocate(
    self: &SystemAllocator,
    layout: Layout
) -> (*var opaque) ! AllocError

Takes storage matching layout from the operating system. result receives the address when this reports None. A zero-sized layout gives the shared empty block and takes nothing from the system. Reports Unsupported for an alignment larger than the total the request would occupy, OutOfMemory when the system refuses. The storage is the caller's until Deallocate takes it back with an equal layout.

Returns: the address of the storage, or why none was taken

Source

Deallocate

pub func Deallocate(
    self: &SystemAllocator,
    block: *var opaque,
    layout: Layout
) -> ! AllocError

Gives the storage behind block back to the operating system. layout must equal the one the block was allocated with. Reports InvalidBlock when the header is not there or does not agree with the layout, which catches a foreign pointer and a mismatched size before either reaches the page layer. Every pointer into the block becomes invalid.

Returns: nothing when the release was accepted, or why it was refused

Source

Reallocate

pub func Reallocate(
    self: &SystemAllocator,
    block: *var opaque,
    oldLayout: Layout,
    newLayout: Layout
) -> (*var opaque) ! AllocError

Changes the size of a block by taking a new one and copying what fits. The two layouts must share an alignment; anything else reports Unsupported rather than moving the block to a different one. On success the original block is released and result holds the new address, which is generally not the old one. This allocator never grows a block in place, even when the page it sits in has room: doing so would need a free-list it deliberately does not keep. The old pointer is invalid once this succeeds. On failure it is untouched and still the caller's.

Returns: the address the block is at afterwards, or why it was not resized

Source

Related

SystemBlockHeader

pub struct SystemBlockHeader {
    // private fields
}

What a system allocation records about itself, immediately before the address the caller sees. Never constructed by a caller. The magic is checked on release, which is what turns a mismatched or foreign pointer into a reported InvalidBlock rather than a corrupted heap.

Source

SystemBlockMagic

pub const SystemBlockMagic: uint64 = 0x52757841_6C6C6F63;

The pattern a valid system block header carries. Chosen to be unlikely in ordinary data, so a pointer that was never one of these is very unlikely to look like one. This is a check against a mistake, not against an adversary.

Source