338 lines
12 KiB
Markdown
338 lines
12 KiB
Markdown
# PBS Memory and Lifetime Specification
|
|
|
|
Status: Draft v1 (Temporary)
|
|
Applies to: runtime memory spaces, value representation classes, identity, aliasing, GC baseline, host-memory boundaries, and cost visibility in PBS core
|
|
|
|
## 1. Purpose
|
|
|
|
This document defines 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 the current core value categories,
|
|
- 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 defines:
|
|
|
|
- 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 integrates the following accepted decisions:
|
|
|
|
- `docs/compiler/pbs/learn/03. Runtime Values, Identity, and Memory Boundaries.md`
|
|
|
|
## 5. Already-Settled Inputs
|
|
|
|
The following inputs are already fixed elsewhere and must not be contradicted here:
|
|
|
|
- Struct values are reference-like and identity-bearing in v1 core.
|
|
- Service values are canonical module-owned singleton values in v1 core.
|
|
- `declare const` values are compile-time constants rather than mutable runtime module storage.
|
|
- `FRAME_SYNC` is the only normative safepoint in PBS v1.
|
|
- Core PBS v1 does not expose explicit lifetime-control syntax in ordinary user code.
|
|
|
|
## 6. Runtime Memory Spaces
|
|
|
|
PBS v1 distinguishes, at minimum:
|
|
|
|
1. VM-managed runtime storage used for GC-managed values and retained runtime state.
|
|
2. Stack-like transient value flow used for ordinary value exchange during evaluation.
|
|
3. Host-owned memory and resources that remain outside ordinary PBS userland memory semantics.
|
|
|
|
The VM heap and host-owned memory remain distinct in the user model.
|
|
|
|
Cross-boundary host/userland interaction is value-based rather than memory-sharing-based.
|
|
|
|
## 7. Value Representation Classes
|
|
|
|
### 7.1 Pure copied values
|
|
|
|
The following value kinds are pure copied values in the user model:
|
|
|
|
- `int`
|
|
- `float`
|
|
- `bool`
|
|
- enum values
|
|
- canonical `str`
|
|
|
|
Assignment, parameter passing, and return of these values copy the value itself.
|
|
|
|
### 7.2 Identity-bearing values
|
|
|
|
The following value kinds carry stable user-visible identity:
|
|
|
|
- struct values
|
|
- service values
|
|
- host-backed resource values on the PBS side
|
|
|
|
Assignment, parameter passing, and return of these values preserve aliasing to the same runtime entity rather than copying an independent underlying object.
|
|
|
|
### 7.3 Carrier-only values
|
|
|
|
The following value kinds are carriers and do not introduce identity of their own:
|
|
|
|
- tuples
|
|
- `optional`
|
|
- `result`
|
|
|
|
If a carrier contains an identity-bearing payload, the carrier transports that same payload identity rather than inventing a new one.
|
|
|
|
### 7.4 Contract values
|
|
|
|
Contract values do not introduce a new user-visible identity distinct from the underlying struct or service value.
|
|
|
|
They are runtime views over an underlying identity-bearing value together with the selected contract implementation used for dispatch.
|
|
|
|
### 7.5 Callback values
|
|
|
|
Callback values are first-class callable values in PBS v1.
|
|
|
|
They may be assigned, passed, and returned, but callback identity is not promoted as a separate user-visible identity concept.
|
|
|
|
When formed through `bind(context, fn_name)`, a callback value retains:
|
|
|
|
- the target function,
|
|
- and the same captured struct context identity without copying it.
|
|
|
|
## 8. Identity, Aliasing, and Copy Behavior
|
|
|
|
### 8.1 Structs
|
|
|
|
Struct values are always reference-like in PBS v1.
|
|
|
|
Rules:
|
|
|
|
- `new Struct(...)` produces a fresh struct identity.
|
|
- Assignment of a struct value copies the reference, not the underlying field storage.
|
|
- Passing or returning a struct value preserves aliasing to the same struct instance.
|
|
- Mutation through one alias is observable through other aliases to that same struct instance.
|
|
|
|
### 8.2 Services
|
|
|
|
Service values denote the same canonical singleton identity wherever used in the same resolved program.
|
|
|
|
Assignment, parameter passing, and return preserve that same singleton identity.
|
|
|
|
### 8.3 Carriers
|
|
|
|
`optional`, `result`, and tuples preserve the semantics of their contained values.
|
|
|
|
Examples:
|
|
|
|
- assigning an `optional<Player>` that contains `some(player)` preserves the same `Player` identity inside the carrier,
|
|
- assigning a `result<E> Player` success payload preserves the same `Player` identity inside the carrier.
|
|
|
|
### 8.4 General rule
|
|
|
|
The general rule for PBS v1 is:
|
|
|
|
- pure value kinds are copied by value,
|
|
- identity-bearing kinds preserve aliasing,
|
|
- carrier kinds preserve the semantics of their contained values and do not create identity of their own.
|
|
|
|
## 9. GC Baseline
|
|
|
|
### 9.1 Reachability
|
|
|
|
GC is the baseline runtime model for VM-owned memory in PBS core.
|
|
|
|
For GC-managed VM-owned values, liveness is defined by reachability from the runtime roots that matter to PBS semantics.
|
|
|
|
At minimum, those roots include:
|
|
|
|
- currently active local/frame state,
|
|
- reachable fields of reachable struct instances,
|
|
- service singleton roots,
|
|
- retained callback state that remains reachable,
|
|
- and any other runtime roots required to preserve already-observable PBS behavior.
|
|
|
|
If a GC-managed value remains reachable through the normative runtime state, the implementation must preserve its continued semantic availability.
|
|
|
|
### 9.2 Reclamation
|
|
|
|
PBS v1 guarantees eventual reclamation, not prompt reclamation.
|
|
|
|
The language does not promise:
|
|
|
|
- immediate reclamation,
|
|
- reclamation at a specific frame boundary,
|
|
- or a semantic event when reclamation occurs.
|
|
|
|
### 9.3 Safepoint relationship
|
|
|
|
`FRAME_SYNC` is the only normative safepoint in PBS v1.
|
|
|
|
No user-visible program rule may depend on another safepoint existing.
|
|
|
|
Implementations may perform internal GC work outside `FRAME_SYNC` only if doing so creates no additional user-visible semantic effects.
|
|
|
|
### 9.4 Observability
|
|
|
|
User code cannot observe reclamation directly.
|
|
|
|
PBS v1 provides no user-visible mechanism for:
|
|
|
|
- detecting that a value was collected,
|
|
- registering a callback on reclamation,
|
|
- forcing immediate collection,
|
|
- sequencing user code against collector timing.
|
|
|
|
PBS v1 defines no user-authored finalizers or destructor-like reclamation hooks.
|
|
|
|
## 10. Host Memory Boundary
|
|
|
|
The host/userland boundary in PBS v1 is value-based rather than memory-sharing-based.
|
|
|
|
Cross-boundary interaction between host and PBS userland is restricted to stack-only values.
|
|
|
|
PBS userland does not expose host memory as ordinary language values.
|
|
|
|
PBS v1 does not expose:
|
|
|
|
- raw host pointers,
|
|
- borrowed host-memory views,
|
|
- pinning,
|
|
- zero-copy transfer,
|
|
- shared heap objects spanning host memory and VM memory.
|
|
|
|
Long-lived host resources, if later exposed, must be specified by subsystem contract rather than inferred from a general host-memory-handle model in core PBS.
|
|
|
|
## 11. Cost Visibility Hooks
|
|
|
|
### 11.1 Normatively relevant cost facts
|
|
|
|
The normatively relevant cost facts in PBS v1 are:
|
|
|
|
- whether an operation may allocate VM-owned runtime storage,
|
|
- whether an operation retains state beyond the current evaluation,
|
|
- whether an operation copies payload versus preserves aliasing,
|
|
- whether an operation crosses the host boundary,
|
|
- whether an operation may trap.
|
|
|
|
### 11.2 `bind`
|
|
|
|
`bind(context, fn_name)` is retention-bearing and requires runtime storage sufficient to preserve:
|
|
|
|
- the callback target identity,
|
|
- the captured context,
|
|
- and the captured context's continued liveness while the callback value remains alive.
|
|
|
|
This document does not freeze the exact runtime layout used to implement that storage.
|
|
|
|
### 11.3 Non-allocation-bearing surfaces by themselves
|
|
|
|
The following constructs are not allocation-bearing by themselves in PBS v1:
|
|
|
|
- `optional`
|
|
- `result`
|
|
- `handle`
|
|
- `!`
|
|
- `if`
|
|
- `switch`
|
|
- `apply`
|
|
|
|
If allocation or retention occurs while evaluating one of these constructs, that cost arises from:
|
|
|
|
- subexpression evaluation,
|
|
- called targets,
|
|
- payload formation already defined elsewhere,
|
|
- or runtime behavior outside the surface itself.
|
|
|
|
### 11.4 Quantitative reporting
|
|
|
|
The language does not normatively guarantee:
|
|
|
|
- exact byte counts,
|
|
- exact object counts,
|
|
- exact collector timing,
|
|
- exact host-side allocation volume,
|
|
- precise performance ranking.
|
|
|
|
Those belong to diagnostics/profiling quality rather than to the core language contract.
|
|
|
|
## 12. Future Lifetime Control Policy
|
|
|
|
PBS v1 adopts the following policy:
|
|
|
|
- no dormant lifetime-control keyword is preserved merely for speculative future use,
|
|
- advanced memory workflows should default to library/tooling-first exploration,
|
|
- future explicit lifetime-oriented syntax, if introduced at all, must be profile-gated and justified by real need rather than by historical inertia.
|
|
|
|
Core PBS v1 does not promise future activation of legacy RC/HIP-style syntax.
|
|
|
|
## 13. Beginner-Facing Model
|
|
|
|
The user-facing explanation should be:
|
|
|
|
- some values are plain data, so passing them passes the value,
|
|
- structs and services are shared entities, so passing them passes access to the same entity,
|
|
- tuples, `optional`, and `result` only package values and do not become new entities by themselves,
|
|
- the runtime keeps reachable GC-managed values alive,
|
|
- the program does not directly hold or manipulate host memory.
|
|
|
|
## 14. TODO
|
|
|
|
The following items remain editorial or adjacent-spec integration tasks rather than open memory-model agenda questions:
|
|
|
|
- subsystem-specific wording for long-lived host resources if those are later introduced,
|
|
- diagnostics-specific wording for cost warnings and notes,
|
|
- future profile mechanics if an explicit lifetime profile is ever proposed.
|
|
|
|
## 15. 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 beyond what is required for consistency with accepted decisions.
|
|
|
|
## 16. Exit Criteria
|
|
|
|
This document is ready to move beyond temporary draft status only when:
|
|
|
|
1. every current core value category has explicit representation and aliasing wording,
|
|
2. GC guarantees and non-guarantees are separated clearly,
|
|
3. the VM heap versus host-memory boundary is normatively described,
|
|
4. memory-related cost facts are specified well enough for diagnostics/tooling hooks,
|
|
5. the remaining TODO items are reduced to editorial integration or future optional work rather than semantic uncertainty.
|