gizlang:memory

import * as Memory from "gizlang:memory";

Types

Weak

type Weak<T>

A reference that does not keep its object alive: upgrade gives the Ref while the object lives. It is always the full 64-bit Ref, never a boxed word's short form, so a dead one never names a later object in its slot.

Opaque: create and use it through this module's functions.

MemoryLimit

type MemoryLimit = { bytes: i64; }

A budget scope refused memory: the call it bounded ended.

• bytes: i64

Boxed

type Boxed<MASK>

A NaN-boxed word whose tagged payloads are heap edges: boxed when its top 13 bits are set, its tag in bits 48 to 50. A tag in MASK (a bit set: JS uses 0x78, tags 3 to 6) holds a reference: the Ref's slot in the low 32 bits and the low 16 bits of its generation above them. A collection traces those and nothing else: a double, or another tag (JS's 7, an array hole, has payload 0).

Opaque: create and use it through this module's functions.

Dyn

type Dyn = | { kind: "word"; bits: u64; } | { kind: "bytes"; data: bytes; } | { kind: "vector"; items: Vec<Dyn>; } | { kind: "record"; items: Vec<Dyn>; } | { kind: "variant"; tag: i64; fields: Vec<Dyn>; }

A flat value (flatten) as a tree: a scalar's word, a string's or bytes' bytes, the elements of a vector, the fields of a record, or a union's case number with the fields of that case.

• word
• bytes
• vector
• record
• variant

Field

type Field = { name: string; earlier: Vec<string>; scalar: string; }

A record field as its schema records it: its name, earlier names from @was doc tags (newest first), and its scalar type (i64, u64, f64, bool, string, bytes), or "" for any other type.

• name: string
• earlier: Vec<string>
• scalar: string

Functions

create

function create<T>(value: T): Ref<T> effects { write, fail }

The compiler checks these bodies through its ordinary generic/effect rules. Ref<T> is an opaque managed identity; its physical carrier is never exposed. This module grants no filesystem/network capability and creates no heap.

load

function load<T>(reference: Ref<T>): T effects { read, fail }

The value that reference holds.

store

function store<T>(reference: Ref<T>, value: T): bool effects { write, fail }

Replace the value that reference holds; true when it was stored.

take

function take<T>(reference: Ref<T>): T effects { read, write, fail }

Moves the value out of the object, as update does, for a caller that cannot write through a closure (it holds other mutable state): the caller is the value's one owner and writes it without a copy, and it must store the value back on every path. Meanwhile the object is busy (a load of it faults). A load instead shares the value with the object, and its first write copies what it changes (a statement copied the page cache's slots).

update

function update<T, R>(reference: Ref<T>, f: (value: mut T) => R effects { read, write, fail, io, console }): R effects { read, write, fail, io, console }

Runs F with the value of REFERENCE as a mutable argument and stores what F leaves in it; the result of F.

weak

function weak<T>(reference: Ref<T>): Weak<T>

A weak reference: it does not keep the value alive.

upgrade

function upgrade<T>(reference: Weak<T>): Option<Ref<T>> effects { read, fail }

The reference that a weak one names, or none when its value was collected.

pin

function pin<T>(reference: Ref<T>): u64 effects { write, fail }

A word that keeps REFERENCE's value alive until unpin, for a table outside the program's values (a VM's, a native's). pinned gives the Ref back. Each pin needs its own unpin.

pinned

function pinned<T>(word: u64): Ref<T> | undefined effects { read, fail }

The Ref a pinned word holds, or undefined when the word names a value of another type.

unpin

function unpin(word: u64): void effects { write, fail }

Ends one pin of WORD: its value then lives only while something else holds it. A word with no pin faults.

Effects: fail, write.

collections

function collections(): u64 effects { read }

Collections so far. A table of Weak values drops its dead entries when this has changed since it last looked.

Effects: read.

region

function region<F>(f: F): ReturnType<F>

f() as one lifetime: the objects f made and did not keep (in its result, a root or an older object) are freed when it returns, by a minor collection; what f kept is old from then on.

minorCollections

function minorCollections(): i64 effects { read }

Minor collections so far (each Memory.region ends with one).

Effects: read.

budgeted

function budgeted<F>(bytes: i64, f: F): ReturnType<F> throws MemoryLimit

f() with at most bytes of the running budget, on the calling task. A scope draws from its parent's budget (a nested one from its scope's) and never adds to it. Over it, f ends with fault 11 and this returns the limit; any other fault goes on. The caller's state is as f left it.

boxed

function boxed<MASK>(word: u64): Boxed<MASK>

A boxed word of any bits: a double, or a tag whose payload is no reference.

wordOf

function wordOf<MASK>(value: Boxed<MASK>): u64

The 64-bit word of a boxed value.

box

function box<T, MASK>(reference: Ref<T>, tag: u64): Boxed<MASK>

The boxed word of a tag in MASK for REFERENCE.

unbox

function unbox<T, MASK>(word: Boxed<MASK>): Option<Ref<T>> effects { read, fail }

The Ref a boxed word of a reference tag holds, when it is a T.

sameIdentity

function sameIdentity<T>(left: Ref<T>, right: Ref<T>): bool effects { fail }

Whether two references name the same value.

collect

function collect(): u64 effects { write, fail }

Collect the unreachable values now.

Effects: fail, write.

liveObjects

function liveObjects(): u64 effects { read, fail }

The number of values that are alive.

Effects: fail, read.

census

function census(top: i64): string effects { read, fail }

Where the memory is, as lines of text, each part the largest first, at most TOP lines a part: objects N bytes B, then object COUNT BYTES TYPE for this World's Ref objects by type (their blocks, not the buffers they hold); blocks N bytes B pages P empty E released R, then block COUNT BYTES SIZE for the allocator's blocks of every thread by size class (strings, vectors and bytes are blocks), with the bytes of the pages that hold them, of empty pages kept, and of empty pages given back; and large COUNT bytes B kept K for the blocks past 64 KiB. It walks every object and page: for finding where memory went, not for a hot path.

Effects: fail, read.

limitBytes

function limitBytes(): i64 effects { read }

The allocator's configured World/shared-memory ceiling, not free memory or remaining allocation credit. Resource policies must derive from this owner.

Effects: read.

residentBytes

function residentBytes(): i64 effects { read }

The anonymous resident memory of the process now, all Worlds together, less the freed blocks the allocator keeps for reuse (it gives them back before it refuses): what limitBytes bounds. A request past the limit fails with fault 11 on whichever thread asks.

Effects: read.

roomBytes

function roomBytes(): i64 effects { read }

The bytes the host can still give before its kernel kills a process: the room left in the process's cgroup and on the machine, other processes counted. A program that keeps a cache gives it back when this is short (the limit counts only this process).

Effects: read.

essential

function essential(): void effects { write }

Marks the calling thread as one that must not fail while others still use the limit (a server's engine loop): it may take the reserve the other threads leave (a fixed share of the limit).

Effects: write.

schemaOf

function schemaOf<T>(): bytes

T's schema key, what live state migrates by: 8 bytes per word, little-endian. Most programs want fieldsOf.

flatten

function flatten<T>(value: T): bytes

The record or union VALUE as little-endian 8-byte words that a program reads without its layout: each node is its layout kind (1 scalar, 2 Ref, 3 bytes or string, 4 vector, 5 record, 6 union, 8 boxed word) and then a scalar's word; a length, then the bytes padded to words; a count, then each element or field; or a case number, then its fields. Fails on a value with a function inside.

unflatten

function unflatten<T>(words: bytes): T

The value that flatten made WORDS from; a stream that does not fit T fails.

dynamicOf

function dynamicOf(words: bytes): Dyn

The tree of words that flatten made.

Effects: fail.

wordsOf

function wordsOf(node: Dyn): bytes

The words of a tree, as unflatten reads them.

Effects: fail.

describe

function describe<T>(): bytes

The JSON of the declaration of the non-generic record or union T, a constant of the program: its name, docs, annotations (with their arguments), fields or cases, and the structured type of each, as giz outline gives them. db/model.giz reads it.

keys

function keys<T>(value: T): Vec<string>

The field names of the record VALUE, in declaration order: TypeScript's Object.keys(value).

fieldsOf

function fieldsOf<T>(): Vec<Field>

The fields of the record type T, in declaration order, from schemaOf<T>().

Methods

Dyn.bits

function Dyn.bits(self: Dyn): u64

A scalar's word; fails on another node.

Effects: fail.

Dyn.data

function Dyn.data(self: Dyn): bytes

A string's or bytes' bytes; fails on another node.

Effects: fail.

Dyn.items

function Dyn.items(self: Dyn): Vec<Dyn>

The elements of a vector, the fields of a record or the fields of a union's case; fails on another node.

Effects: fail.

Dyn.tag

function Dyn.tag(self: Dyn): i64

A union's case number (in declaration order; Option is some, none); fails on another node.

Effects: fail.