# gizlang:memory ```gizlang import * as Memory from "gizlang:memory"; ``` ## Types ### `Weak` ```gizlang type Weak ``` 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` ```gizlang type MemoryLimit = { bytes: i64; } ``` A budget scope refused memory: the call it bounded ended. - `bytes`: `i64` ### `Boxed` ```gizlang type Boxed ``` 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` ```gizlang type Dyn = | { kind: "word"; bits: u64; } | { kind: "bytes"; data: bytes; } | { kind: "vector"; items: Vec; } | { kind: "record"; items: Vec; } | { kind: "variant"; tag: i64; fields: Vec; } ``` 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` ```gizlang type Field = { name: string; earlier: Vec; 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` - `scalar`: `string` ## Functions ### `create` ```gizlang function create(value: T): Ref effects { write, fail } ``` The compiler checks these bodies through its ordinary generic/effect rules. Ref is an opaque managed identity; its physical carrier is never exposed. This module grants no filesystem/network capability and creates no heap. ### `load` ```gizlang function load(reference: Ref): T effects { read, fail } ``` The value that `reference` holds. ### `store` ```gizlang function store(reference: Ref, value: T): bool effects { write, fail } ``` Replace the value that `reference` holds; true when it was stored. ### `take` ```gizlang function take(reference: Ref): 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` ```gizlang function update(reference: Ref, 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` ```gizlang function weak(reference: Ref): Weak ``` A weak reference: it does not keep the value alive. ### `upgrade` ```gizlang function upgrade(reference: Weak): Option> effects { read, fail } ``` The reference that a weak one names, or none when its value was collected. ### `pin` ```gizlang function pin(reference: Ref): 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` ```gizlang function pinned(word: u64): Ref | undefined effects { read, fail } ``` The Ref a pinned word holds, or undefined when the word names a value of another type. ### `unpin` ```gizlang 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` ```gizlang 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` ```gizlang function region(f: F): ReturnType ``` 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` ```gizlang function minorCollections(): i64 effects { read } ``` Minor collections so far (each Memory.region ends with one). Effects: read. ### `budgeted` ```gizlang function budgeted(bytes: i64, f: F): ReturnType 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` ```gizlang function boxed(word: u64): Boxed ``` A boxed word of any bits: a double, or a tag whose payload is no reference. ### `wordOf` ```gizlang function wordOf(value: Boxed): u64 ``` The 64-bit word of a boxed value. ### `box` ```gizlang function box(reference: Ref, tag: u64): Boxed ``` The boxed word of a tag in MASK for REFERENCE. ### `unbox` ```gizlang function unbox(word: Boxed): Option> effects { read, fail } ``` The Ref a boxed word of a reference tag holds, when it is a T. ### `sameIdentity` ```gizlang function sameIdentity(left: Ref, right: Ref): bool effects { fail } ``` Whether two references name the same value. ### `collect` ```gizlang function collect(): u64 effects { write, fail } ``` Collect the unreachable values now. Effects: fail, write. ### `liveObjects` ```gizlang function liveObjects(): u64 effects { read, fail } ``` The number of values that are alive. Effects: fail, read. ### `census` ```gizlang 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` ```gizlang 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` ```gizlang 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` ```gizlang 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` ```gizlang 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` ```gizlang function schemaOf(): bytes ``` T's schema key, what live state migrates by: 8 bytes per word, little-endian. Most programs want fieldsOf. ### `flatten` ```gizlang function flatten(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` ```gizlang function unflatten(words: bytes): T ``` The value that `flatten` made WORDS from; a stream that does not fit T fails. ### `dynamicOf` ```gizlang function dynamicOf(words: bytes): Dyn ``` The tree of words that `flatten` made. Effects: fail. ### `wordsOf` ```gizlang function wordsOf(node: Dyn): bytes ``` The words of a tree, as `unflatten` reads them. Effects: fail. ### `describe` ```gizlang function describe(): 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` ```gizlang function keys(value: T): Vec ``` The field names of the record VALUE, in declaration order: TypeScript's Object.keys(value). ### `fieldsOf` ```gizlang function fieldsOf(): Vec ``` The fields of the record type T, in declaration order, from schemaOf(). ## Methods ### `Dyn.bits` ```gizlang function Dyn.bits(self: Dyn): u64 ``` A scalar's word; fails on another node. Effects: fail. ### `Dyn.data` ```gizlang function Dyn.data(self: Dyn): bytes ``` A string's or bytes' bytes; fails on another node. Effects: fail. ### `Dyn.items` ```gizlang function Dyn.items(self: Dyn): Vec ``` 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` ```gizlang function Dyn.tag(self: Dyn): i64 ``` A union's case number (in declaration order; Option is some, none); fails on another node. Effects: fail.