silk.platform.wasm.heap.

When to use#

The wasm entry modules export malloc, free, calloc and realloc from WasmHeap, and a module without host services exports its report through WasmHeap.report. Applications use Allocator.systemAllocatorProvider.

Details#

The heap starts at the linker's __heap_base and grows with memory.grow. Its first bytes hold the heap's own state, which a fresh linear memory already holds as zeros: the top chunk, the lock, the report's length, the bin map, the bins and the report buffer. Chunks follow. The initial memory may end inside the state, so each entry first grows the memory to cover it.

Each chunk is a 16-byte header and a payload aligned to 16. A header holds the size of the chunk before it while that one is free, then the chunk's own size with two flags, so a release coalesces a chunk with both neighbors. Free chunks wait in bins by size: one per 16 bytes below 1 KiB, then four per power of two. The last chunk is the top, which grows the memory instead of joining a bin. Positions are byte offsets from the heap's start; offset zero, inside the state, is no chunk. With the multi threading profile one lock serializes the heap.

Public declarations: 1.

WasmHeap#

pub struct WasmHeap

The wasm heap: malloc-style storage over linear memory.

Implementation WasmHeap#

impl WasmHeap

Associated function allocate#

pub unsafe fn allocate(size: usize) -> ?[*]mut u8

Returns uninitialized storage of at least size bytes aligned to 16, or null when the memory cannot grow.

Safety#

Release a non-null result once with WasmHeap.release after every access ends.

Associated function allocateZeroed#

pub unsafe fn allocateZeroed(count: usize, size: usize) -> ?[*]mut u8

Returns storage of count * size zero bytes, or null when the product overflows or the memory cannot grow.

Safety#

Release a non-null result once with WasmHeap.release after every access ends.

Associated function release#

pub unsafe fn release(allocation: ?[*]mut u8) -> ()

Releases storage from WasmHeap.allocate. Null does nothing.

Safety#

allocation must be null or a live result of this heap, released once, after every access.

Associated function resize#

pub unsafe fn resize(allocation: ?[*]mut u8, size: usize) -> ?[*]mut u8

Keeps an allocation that already holds size bytes; otherwise moves its bytes to a new one and releases the old. Returns null, keeping the old allocation, when the memory cannot grow. A null allocation allocates.

Safety#

allocation must be null or a live result of this heap. After a non-null result, only that result may be used.

Associated function reportWrite#

pub unsafe fn reportWrite(bytes: ?[*]const u8, length: usize) -> bool

Appends what fits of bytes to the report buffer, and answers whether all of it did. Threads that report at once each reserve their own bytes.

Safety#

bytes must address length readable bytes.

Associated function empty#

pub fn empty() -> ?[*]mut u8

A non-null address aligned to 16 that holds no storage, for empty allocations that are never read or released.

Associated function report#

pub fn report() -> ?[*]const u8

The address of the report buffer, which the host reads after a trap.

Associated function reportLength#

pub fn reportLength() -> usize

The number of bytes written to the report buffer.

Category: Native platform.

Profiles: wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, wasm64-unknown-unknown.