132 lines
5.1 KiB
Markdown
132 lines
5.1 KiB
Markdown
# PBS Memory and Lifetime Specification
|
|
|
|
Status: Draft v0 (Skeleton)
|
|
Applies to: runtime memory spaces, value representation classes, identity, aliasing, GC baseline, and host-memory boundaries in PBS core
|
|
|
|
## 1. Purpose
|
|
|
|
This document will define the authoritative PBS memory and lifetime model for v1.
|
|
|
|
Its purpose is to make the language's runtime storage model explicit enough that:
|
|
|
|
- implementations agree on which values are heap-backed,
|
|
- identity and aliasing are not left implicit,
|
|
- GC remains compatible with deterministic execution,
|
|
- the VM heap and host-owned memory boundary stay understandable,
|
|
- tooling can surface runtime-visible memory and allocation costs consistently.
|
|
|
|
## 2. Scope
|
|
|
|
This document is intended to define:
|
|
|
|
- runtime memory spaces relevant to PBS user semantics,
|
|
- value categories and their representation classes,
|
|
- identity, aliasing, and copy behavior,
|
|
- baseline GC guarantees and non-guarantees,
|
|
- host-memory boundary rules,
|
|
- memory-related safety invariants and remaining runtime failure boundaries,
|
|
- hooks that later diagnostics and tooling may rely on for cost reporting.
|
|
|
|
This document does not define:
|
|
|
|
- exact GC algorithm internals,
|
|
- general-purpose allocator APIs,
|
|
- future explicit lifetime syntax activation,
|
|
- final IR lowering details,
|
|
- subsystem-specific host resource APIs.
|
|
|
|
## 3. Authority and Precedence
|
|
|
|
Normative precedence:
|
|
|
|
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
|
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
|
3. `1. Language Charter.md`
|
|
4. `3. Core Syntax Specification.md`
|
|
5. `4. Static Semantics Specification.md`
|
|
6. `9. Dynamic Semantics Specification.md`
|
|
7. This document
|
|
|
|
If a rule here conflicts with higher authority, it is invalid.
|
|
|
|
## 4. Normative Inputs
|
|
|
|
This document depends on, at minimum:
|
|
|
|
- `1. Language Charter.md`
|
|
- `3. Core Syntax Specification.md`
|
|
- `4. Static Semantics Specification.md`
|
|
- `9. Dynamic Semantics Specification.md`
|
|
|
|
This document is expected to be closed using decisions from:
|
|
|
|
- `docs/agendas/Heap Model - Agenda.md`
|
|
- `docs/agendas/Memory and Lifetime - Agenda.md`
|
|
- `docs/agendas/Dynamic Semantics - Execution Model Agenda.md`
|
|
- `docs/agendas/Dynamic Semantics - Effect Surfaces Agenda.md`
|
|
|
|
## 5. Already-Settled Inputs
|
|
|
|
The following inputs are already fixed elsewhere and must not be contradicted here:
|
|
|
|
- Struct values are heap-backed reference values in v1 core.
|
|
- Assigning a struct value copies the reference, not the underlying field storage.
|
|
- Service values are canonical module-owned singleton values in v1 core.
|
|
- Assigning a service value copies the same singleton identity and does not create a new instance.
|
|
- `declare const` values are compile-time constants rather than mutable runtime module storage.
|
|
- Advanced memory syntax such as `alloc`, `borrow`, `mutate`, `peek`, `take`, and `weak` is not active in PBS core v1.
|
|
|
|
## 6. Initial Section Targets
|
|
|
|
At minimum, the completed document should contain normative sections for:
|
|
|
|
1. runtime memory spaces,
|
|
2. value representation classes,
|
|
3. identity and aliasing,
|
|
4. copy and passing behavior,
|
|
5. GC guarantees and safepoint constraints,
|
|
6. host-memory boundary rules,
|
|
7. memory-related safety properties,
|
|
8. cost visibility hooks consumed by diagnostics/tooling.
|
|
|
|
## 7. A Ver
|
|
|
|
The following items remain to be closed in agenda discussion before this document can be considered complete.
|
|
|
|
### 7.1 `Memory and Lifetime - Agenda.md`
|
|
|
|
- Heap residency by value category beyond already-settled struct and service behavior.
|
|
- Which values have stable user-visible identity.
|
|
- Exact aliasing story for tuples, callbacks, collections, `optional`, and `result<E>`.
|
|
- Normative GC guarantees versus implementation-defined GC details.
|
|
- Representation and safety model of host-backed resources and handles.
|
|
|
|
### 7.2 `Heap Model - Agenda.md`
|
|
|
|
- Cross-cutting visibility of allocation, copy, retention, and host-boundary costs.
|
|
- Which memory facts are normative versus profiler-quality best effort.
|
|
- Migration policy and activation criteria for reserved lifetime keywords in future profiles.
|
|
|
|
### 7.3 `Dynamic Semantics - Execution Model Agenda.md` and `Dynamic Semantics - Effect Surfaces Agenda.md`
|
|
|
|
- Which constructs allocate or retain memory during ordinary execution.
|
|
- Which effect-bearing constructs may trap only because their subexpressions trap.
|
|
- Which safepoints are observable versus implementation detail.
|
|
|
|
## 8. Non-Goals
|
|
|
|
- Designing full pool, arena, or weak-reference libraries in this pass.
|
|
- Reintroducing mandatory user-authored lifetime syntax in core v1.
|
|
- Defining exact collector implementation strategy.
|
|
- Rewriting already-settled source syntax.
|
|
|
|
## 9. Exit Criteria
|
|
|
|
This document is ready to move beyond skeleton status only when:
|
|
|
|
1. every core value category has an explicit representation and aliasing story,
|
|
2. GC guarantees and non-guarantees are separated clearly,
|
|
3. the VM heap versus host-memory boundary is normatively described,
|
|
4. memory-related costs are specified well enough for diagnostics/tooling hooks,
|
|
5. the document no longer relies on unresolved `A Ver` items for ordinary v1 behavior.
|