std/mem

Types

CapacityFull

pub type CapacityFull[T] = {
    pub value T
}

What a full BoundedArray hands back instead of storing: the value itself, so a move-only element is not lost.

BoundedArray

pub type BoundedArray[T, const N: usize] = resource {
    // private fields omitted
}

Up to N elements of T. A full array refuses a push and never grows, and N is part of the type. Its N slots are heap cells allocated once in new; dropping it drops the elements it holds and nothing else.

BoundedArray.new

pub pure fn BoundedArray.new[T, const N: usize]() -> BoundedArray[T, N]

An empty array.

BoundedArray.len

pub pure noalloc fn BoundedArray[T, N].len(self) -> usize

Number of elements held, between 0 and N.

BoundedArray.capacity

pub pure noalloc fn BoundedArray[T, N].capacity(self) -> usize

N, whatever the length.

BoundedArray.isEmpty

pub pure noalloc fn BoundedArray[T, N].isEmpty(self) -> Bool

BoundedArray.isFull

pub pure noalloc fn BoundedArray[T, N].isFull(self) -> Bool

BoundedArray.tryPush

pub fn BoundedArray[T, N].tryPush(mut self, value: T) -> Result[Void, CapacityFull[T]]

Appends value, or hands it back inside CapacityFull when the array already holds N elements.

BoundedArray.push

pub fn BoundedArray[T, N].push(mut self, value: T)

Appends value, or panics when the array already holds N elements.

BoundedArray.pop

pub fn BoundedArray[T, N].pop(mut self) -> T?

Removes and returns the last element; None when empty.

BoundedArray.at

pub fn BoundedArray[T, N].at[R](self, index: usize, f: fn(&T) -> R) -> R?

Calls f once with a borrow of the element at index and does not keep it; None when index is out of range.

BoundedArray.withMut

pub fn BoundedArray[T, N].withMut[R](mut self, index: usize, f: fn(&mut T) -> R) -> R?

Calls f once with an exclusive borrow of the element at index, so f can change it in place; None when index is out of range.

BoundedArray.get

pub fn BoundedArray[T: Copy, N].get(self, index: usize) -> T?

A copy of the element at index, or None when index is out of range.

BoundedArray.index

pub fn BoundedArray[T: Copy, N].index(self, index: usize) -> T

a[i]: a copy of the element at index; traps when index is out of range.

BoundedArray.set

pub fn BoundedArray[T, N].set(mut self, index: usize, value: T) -> Bool

Replaces the element at index and drops the old one; false when index is out of range, dropping value.

BoundedArray.clear

pub fn BoundedArray[T, N].clear(mut self)

Drops every element and leaves the array empty.

BoundedArray.toArray

pub fn BoundedArray[T: Copy, N].toArray(self) -> Array[T]

A growable copy of the elements, in order.

UnsafeCell

@unsafeGuarantee(Send when T: Send)
pub type UnsafeCell[T]

The only compiler-known interior-mutable primitive: holds a T inline with no extra allocation, header, or lock; every accessor needs unsafe. Safety: moving an UnsafeCell[T] to another thread only ever moves the T inside, so doing so is sound exactly when T itself is.

UnsafeCell.new

pub fn UnsafeCell.new[T](value: T) -> UnsafeCell[T]

Wraps value for interior mutation through shared references.

UnsafeCell.get

pub unsafe fn UnsafeCell[T: Copy].get(self) -> T

A copy of the content as of this call. The caller rules out a concurrent write through another alias of the same cell.

UnsafeCell.set

pub unsafe fn UnsafeCell[T].set(self, value: T)

Replaces the content; the old value is dropped. The caller rules out overlapping access through another alias of the same cell for the duration of the call.

UnsafeCell.atomicLoad

pub unsafe fn UnsafeCell[T].atomicLoad(self, order: AtomicOrder) -> T

Atomically reads the cell; T is an integer up to 64 bits, Bool or a raw pointer. The cell must not be read or written through get / set at the same time.

UnsafeCell.atomicStore

pub unsafe fn UnsafeCell[T].atomicStore(self, value: T, order: AtomicOrder)

Atomically replaces the content of the cell.

UnsafeCell.atomicExchange

pub unsafe fn UnsafeCell[T].atomicExchange(self, value: T, order: AtomicOrder) -> T

Atomically replaces the content and returns the value it held.

UnsafeCell.atomicCompareExchange

pub unsafe fn UnsafeCell[T].atomicCompareExchange(self, expected: T, desired: T, order: AtomicOrder) -> T

Writes desired when the cell holds expected; returns the value it held, so the exchange happened exactly when that equals expected.

UnsafeCell.atomicAdd

pub unsafe fn UnsafeCell[T].atomicAdd(self, value: T, order: AtomicOrder) -> T

Adds value to the cell, wrapping at the type's width, and returns the value it held; T is an integer.

UnsafeCell.atomicSub

pub unsafe fn UnsafeCell[T].atomicSub(self, value: T, order: AtomicOrder) -> T

Subtracts value from the cell, wrapping at the type's width, and returns the value it held; T is an integer.

UnsafeCell.atomicAnd

pub unsafe fn UnsafeCell[T].atomicAnd(self, value: T, order: AtomicOrder) -> T

Bitwise-ands value into the cell and returns the value it held; T is an integer.

UnsafeCell.atomicOr

pub unsafe fn UnsafeCell[T].atomicOr(self, value: T, order: AtomicOrder) -> T

Bitwise-ors value into the cell and returns the value it held; T is an integer.

UnsafeCell.atomicXor

pub unsafe fn UnsafeCell[T].atomicXor(self, value: T, order: AtomicOrder) -> T

Bitwise-xors value into the cell and returns the value it held; T is an integer.

AtomicOrder

pub type AtomicOrder =
    | Relaxed
    | Acquire
    | Release
    | AcqRel
    | SeqCst

The memory order of an atomic operation; the argument must be written as one of these variants.

Uninit

@unsafeGuarantee(Send when T: Send, Sync when T: Sync)
pub type Uninit[T]

Storage for one T that may or may not hold a value, with no flag saying which, so every state-dependent operation is unsafe. Safety: moving an Uninit[T] to another thread moves at most one T, and sharing it shares at most one T.

Functions

secureErase

pub pure fn secureErase(region: &mut Bytes)

Zeros the bytes behind region, surviving the optimizer, but not registers, the stack or reused memory; a let b = a or by-value copy keeps its own bytes, a copy stored in or read from a container shares them.

trySecureErase

pub pure fn trySecureErase(region: &mut Bytes) -> Result[Void, AllocError]

Zeros region like secureErase, or AllocError when the allocator refuses (secureErase panics instead; only an unowned region can hit this path).

atomicLoad

pub noalloc unsafe fn atomicLoad[T](place: &T, order: AtomicOrder) -> T

Atomically reads the static mut named by place (&name); an integer up to 64 bits or Bool, never Release or AcqRel.

atomicStore

pub noalloc unsafe fn atomicStore[T](place: &mut T, value: T, order: AtomicOrder)

Atomically writes value to the static mut named by place (&mut name); never Acquire or AcqRel.

atomicExchange

pub noalloc unsafe fn atomicExchange[T](place: &mut T, value: T, order: AtomicOrder) -> T

Atomically replaces the static mut and returns the value it held.

atomicCompareExchange

pub noalloc unsafe fn atomicCompareExchange[T](place: &mut T, expected: T, desired: T, order: AtomicOrder) -> T

Writes desired when the static mut holds expected; returns the value it held, so the exchange happened exactly when that equals expected. When it fails, the read uses the order without its release part.

atomicAdd

pub noalloc unsafe fn atomicAdd[T](place: &mut T, value: T, order: AtomicOrder) -> T

Adds value to the static mut, wrapping at the type's width, and returns the value it held.

atomicSub

pub noalloc unsafe fn atomicSub[T](place: &mut T, value: T, order: AtomicOrder) -> T

Subtracts value from the static mut, wrapping at the type's width, and returns the value it held.

atomicAnd

pub noalloc unsafe fn atomicAnd[T](place: &mut T, value: T, order: AtomicOrder) -> T

Bitwise-ands value into the static mut and returns the value it held.

atomicOr

pub noalloc unsafe fn atomicOr[T](place: &mut T, value: T, order: AtomicOrder) -> T

Bitwise-ors value into the static mut and returns the value it held.

atomicXor

pub noalloc unsafe fn atomicXor[T](place: &mut T, value: T, order: AtomicOrder) -> T

Bitwise-xors value into the static mut and returns the value it held.

volatileRead

pub noalloc unsafe fn volatileRead[T](p: *const T) -> T

Reads the value at p in exactly one access that the optimizer neither drops, merges nor reorders against other volatile accesses; for memory-mapped registers. T is a fixed-width number, Bool, Char or a raw pointer. It orders nothing across threads.

volatileWrite

pub noalloc unsafe fn volatileWrite[T](p: *mut T, value: T)

Writes value at p in exactly one access like volatileRead.

volatileReadAt

pub noalloc unsafe fn volatileReadAt[T](address: usize) -> T

Reads the register at a fixed address like volatileRead, without forming a pointer; T is an integer up to 64 bits or Bool. It is called directly, never as a function value. The VM has no device memory: it keeps a table of the addresses written so far, and a register nobody wrote reads as zero.

volatileWriteAt

pub noalloc unsafe fn volatileWriteAt[T](address: usize, value: T)

Writes value to the register at a fixed address like volatileWrite, without forming a pointer.

uninit

pub pure fn uninit[T]() -> Uninit[T]

An empty slot. The cell behind it is allocated here, so unlike the operations below this is not noalloc.

initialize

pub pure noalloc unsafe fn initialize[T](slot: &mut Uninit[T], value: T)

Moves value into the slot, which dropping the slot will not drop: empty it with takeInitialized or dropInitialized. The caller rules out the slot already holding a value, which would be lost.

borrowInitialized

pub pure noalloc unsafe fn borrowInitialized['a, T](slot: &'a Uninit[T]) -> &'a T

The value in the slot. The caller rules out an empty slot and any write to it while the borrow lives.

borrowInitializedMut

pub pure noalloc unsafe fn borrowInitializedMut['a, T](slot: &'a mut Uninit[T]) -> &'a mut T

The value in the slot, exclusively. The caller rules out an empty slot and any other access while the borrow lives.

takeInitialized

pub pure noalloc unsafe fn takeInitialized[T](slot: &mut Uninit[T]) -> T

Moves the value out and leaves the slot empty. The caller rules out an empty slot.

dropInitialized

pub pure noalloc unsafe fn dropInitialized[T](slot: &mut Uninit[T])

Drops the value and leaves the slot empty. The caller rules out an empty slot.