332 lines
12 KiB
Markdown
332 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 ([provider specifications](../../../../../runtime/docs/specs/runtime/README.md); [mirror and provenance policy](../../../vm-arch/README.md))
|
|
2. Bytecode authority ([provider Core ISA](../../../../../runtime/docs/vm-arch/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:
|
|
|
|
- `discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.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.
|
|
- PBS uses the existing synthetic frame lifecycle. Runtime GC opportunities, including successful root return, follow the runtime contract; there is no PBS sync statement.
|
|
- 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 Function values and closures
|
|
|
|
Closures are ordinary managed objects retaining their typed captures. Reachable closures may survive across frames; unreachable closures are eligible for GC. Their invocations do not suspend across frames. See [First-class functions and explicit value captures](15.%20First-Class%20Functions%20and%20Captures%20Specification.md).
|
|
|
|
## 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 closure 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
|
|
|
|
PBS uses the existing synthetic frame lifecycle. Runtime GC opportunities, including successful root return, follow the runtime contract; there is no PBS sync statement.
|
|
|
|
No user-visible program rule may depend on another safepoint existing.
|
|
|
|
GC timing remains a runtime concern and introduces no user callback or observable scheduling operation.
|
|
|
|
### 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 Explicit capture storage
|
|
|
|
Closure creation retains the values named in its explicit capture list, including shared object identities. Lifetime follows ordinary reachability and runtime resource limits. Captured bindings cannot be reassigned.
|
|
|
|
### 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.
|
|
|
|
## Typed arrays and optional execution extension
|
|
|
|
The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
|
|
defines the complete type, optional-flow and storage contract.
|
|
This chapter supplies shared reachability and ownership rules; Array storage
|
|
and complete-group packing are defined by that owner.
|