Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Add seven Registry-backed collection opcodes with bounded verification, complete value groups, transactional publication and exact attempt costs. Publish ISA, memory and cycle contracts, producer handoff and the completed lesson. Validate with 925 workspace tests, optimized collection suites and all eight coverage domain gates. Make headless fixture directory names unique for parallel tests.
217 lines
7.7 KiB
Markdown
217 lines
7.7 KiB
Markdown
# Memory Model
|
|
|
|
Domain: VM memory model
|
|
Function: normative
|
|
|
|
This chapter defines the VM memory architecture: stack, heap, handles, object layout, allocation, and garbage collection.
|
|
|
|
It intentionally focuses on VM-managed memory.
|
|
|
|
Host-owned memory surfaces such as asset banks and persistent save storage are covered by their own domain specs and by the host ABI docs.
|
|
|
|
## 1 Overview
|
|
|
|
The PVM memory model is based on:
|
|
|
|
- stack-resident execution values;
|
|
- heap-resident objects;
|
|
- validated handles for indirect heap access;
|
|
- GC-managed object lifetime.
|
|
|
|
## 2 Stack Memory
|
|
|
|
The stack stores transient execution values and frame-scoped data.
|
|
|
|
### Stack value types
|
|
|
|
The stack may contain:
|
|
|
|
- primitive values;
|
|
- string values;
|
|
- built-in fixed-layout values;
|
|
- heap handles;
|
|
- tuple-shaped multi-return values.
|
|
|
|
See [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) for the slot/value model.
|
|
|
|
### Stack properties
|
|
|
|
- stack values are local to execution state;
|
|
- stack discipline is verifier-sensitive;
|
|
- stack underflow and invalid access are traps.
|
|
|
|
## 3 Heap Memory
|
|
|
|
The heap stores runtime objects that require identity and reachability tracking.
|
|
|
|
### Heap characteristics
|
|
|
|
- user objects live in the heap;
|
|
- arrays and closures live in the heap;
|
|
- heap access is indirect through handles;
|
|
- the collector is non-moving in the baseline model.
|
|
|
|
## 4 Handles and Gate Table
|
|
|
|
All heap objects are accessed via handles.
|
|
|
|
A conceptual handle:
|
|
|
|
```
|
|
handle = { index, generation }
|
|
```
|
|
|
|
Conceptual gate entry:
|
|
|
|
```
|
|
GateEntry {
|
|
alive: bool
|
|
generation: u32
|
|
base: usize
|
|
slots: u32
|
|
type_id: u32
|
|
}
|
|
```
|
|
|
|
### Handle safety
|
|
|
|
When an object is freed:
|
|
|
|
- `alive` becomes false;
|
|
- `generation` is incremented, or the slot is permanently retired after its maximum-generation incarnation; generation must never wrap.
|
|
|
|
When a handle is used:
|
|
|
|
- the index must exist;
|
|
- the generation must match;
|
|
- invalid or stale handles trap.
|
|
|
|
This prevents:
|
|
|
|
- use-after-free;
|
|
- stale references;
|
|
- hidden raw memory access.
|
|
|
|
## 5 Object Layout
|
|
|
|
Heap objects use explicit, implementation-visible layout rules.
|
|
|
|
Conceptual form:
|
|
|
|
```
|
|
Object {
|
|
type_id
|
|
field_0
|
|
field_1
|
|
...
|
|
}
|
|
```
|
|
|
|
Properties:
|
|
|
|
- fields use declared-order typed offsets with alignment and padding; stack Value slots are not the heap layout;
|
|
- there is no raw pointer arithmetic in the VM model;
|
|
- layout rules are explicit and verifier/runtime-friendly.
|
|
|
|
Closures and coroutine-owned state may build on top of this memory model, but their behavioral rules are documented separately:
|
|
|
|
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md)
|
|
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md)
|
|
|
|
## 6 Garbage Collection
|
|
|
|
The PVM uses a **mark-sweep collector**.
|
|
|
|
### GC properties
|
|
|
|
- non-moving in the baseline model;
|
|
- runs only at safepoints;
|
|
- primary safepoint: `FRAME_SYNC`.
|
|
|
|
### GC triggers
|
|
|
|
GC may run when:
|
|
|
|
- the configured allocation threshold is reached at an established safepoint.
|
|
|
|
### Root set
|
|
|
|
The collector marks from:
|
|
|
|
- operand stack;
|
|
- call stack frames;
|
|
- global variables;
|
|
- coroutine-owned execution state;
|
|
- closure environments;
|
|
- host-held roots where the host legally retains VM heap references.
|
|
|
|
## 7 Allocation and Deallocation
|
|
|
|
### Allocation
|
|
|
|
Heap allocation conceptually performs:
|
|
|
|
1. reserve object storage;
|
|
2. create or reuse gate entry;
|
|
3. return validated handle.
|
|
|
|
First materialization cost is distinct from repeated hot-path copy pressure.
|
|
|
|
Implications:
|
|
|
|
- constant-pool-backed values may pay materialization cost before execution begins;
|
|
- runtime-created values may pay materialization cost when a new value is semantically produced;
|
|
- the runtime SHOULD minimize repeated implicit copying on hot paths after that first materialization;
|
|
- zero-allocation happy-path work is an engineering optimization target, not a published compatibility guarantee by itself.
|
|
|
|
If allocation fails:
|
|
|
|
- the attempt refuses with the applicable structured resource fault;
|
|
- it does not trigger reentrant GC or scheduling to satisfy its quota.
|
|
|
|
### Deallocation
|
|
|
|
Objects are reclaimed by GC.
|
|
|
|
When reclaimed:
|
|
|
|
- the gate is marked dead;
|
|
- the generation is incremented;
|
|
- storage becomes reusable.
|
|
|
|
## 8 Memory Safety Rules
|
|
|
|
The VM enforces:
|
|
|
|
1. all heap access goes through handles;
|
|
2. generation checks validate handle freshness;
|
|
3. object and field access is bounds-checked;
|
|
4. there is no guest-visible raw pointer arithmetic;
|
|
5. stack discipline remains verifier-constrained.
|
|
|
|
Any violation results in a trap or rejected program image.
|
|
|
|
## 9 Relationship to Other Specs
|
|
|
|
- [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) defines stack values and tuple/call-slot semantics.
|
|
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) defines closure function values.
|
|
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine state and scheduling behavior.
|
|
- [`15-asset-management.md`](15-asset-management.md) defines asset-bank surfaces outside VM heap ownership.
|
|
- [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md) defines save storage outside VM heap ownership.
|
|
- [`16a-syscall-policies.md`](16a-syscall-policies.md) defines host-root rules and host/heap interaction policy.
|
|
|
|
## Program Registry v1 integration
|
|
|
|
[Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md#values-storage-and-initialization) specifies compact typed layouts, defaults, native String/Dynamic ownership and generational handles. Its [memory quotas](02c-program-registry-and-pbx-v1.md#memory-ownership-and-quotas) apply jointly before allocation. Registry metadata is immutable image-owned native memory, outside guest GC. Stack/local execution retains Value.
|
|
|
|
|
|
## Typed Array and Struct Storage
|
|
|
|
Registry-backed Arrays have fixed u32 lengths; Structs have mutable declared fields. Instances use resolved aligned offsets/strides and ownership maps. Builtins remain inline; Struct/Array fields and elements hold references. Copies preserve identity and aliasing, including nested arrays. List, Set and Map policies and implementations belong to each language SDK, composed from runtime Array capabilities.
|
|
|
|
NEW fully initializes all storage before publishing a handle: primitive/builtin canonical zeros, null String and concrete references, absent Trait [Null, Null], and untyped-null Dynamic [Null, Null]. Empty instances remain valid identities. No source constructor, callback or referenced instance/subarray is invoked or allocated implicitly. A frontend may root a default instance, store fields and call its own constructor.
|
|
|
|
GET copies a complete group and native owners without implicit boxing; SET validates the entire group before replacing it. String copies retain Arc ownership/provenance/accounting; null and empty String differ. Trait stores receiver and ImplementationId together (zero is a valid implementation); Dynamic preserves its complete pair and shares existing immutable boxes.
|
|
|
|
After validation, an attempt provisionally reserves net stack growth and construction resources, keeping source operands/roots alive. It prepares complete defaults/results before publication. Commit replaces the whole stored group or publishes the complete result, then consumes operands. No fallible reservation/allocation follows publication. Refusal preserves operands and prior storage/owners, publishes no partial handle, and releases provisional reservations/owners. Attempted work/cycles are retained; preexisting auxiliary capacities follow their existing growth contract. NEW never invokes reentrant GC or scheduling to satisfy quota. GC remains confined to established safepoints; live transitively rooted graphs and native owners survive them, while unrooted cycles become reclaimable.
|