393 lines
8.1 KiB
Markdown
393 lines
8.1 KiB
Markdown
# PR-3.1 — Introduce HeapRef Handle Type in Value Model
|
||
|
||
### Briefing
|
||
|
||
The VM must reference heap objects through opaque handles. This PR introduces a `HeapRef` (or equivalent) type and integrates it into the VM value model without implementing the GC yet.
|
||
|
||
### Target
|
||
|
||
* Add a handle-based reference type for heap objects.
|
||
* Integrate it into the `Value` representation.
|
||
|
||
### Work items
|
||
|
||
* Define a `HeapRef` struct or newtype (e.g., index-based handle).
|
||
* Add a `Value::HeapRef` (or equivalent) variant.
|
||
* Ensure stack operations can carry this value type.
|
||
* Do not allocate real objects yet; this is only the type integration.
|
||
|
||
### Acceptance checklist
|
||
|
||
* [ ] `HeapRef` type exists and is used in `Value`.
|
||
* [ ] VM compiles with the new value variant.
|
||
* [ ] No GC or allocator logic is introduced yet.
|
||
* [ ] `cargo test` passes.
|
||
|
||
### Tests
|
||
|
||
* Existing tests only.
|
||
|
||
### Junie instructions
|
||
|
||
**You MAY:**
|
||
|
||
* Add a new handle type.
|
||
* Extend the `Value` enum/struct.
|
||
|
||
**You MUST NOT:**
|
||
|
||
* Design or implement the GC algorithm here.
|
||
* Introduce object allocation logic.
|
||
* Add hidden ownership or lifetime systems.
|
||
|
||
**If unclear:**
|
||
|
||
* Ask what fields the handle should contain.
|
||
|
||
---
|
||
|
||
# PR-3.2 — Define Heap Object Header and Object Kind Tags
|
||
|
||
### Briefing
|
||
|
||
All heap objects must share a common header so the GC can traverse them. This PR introduces the canonical object header and object kind tagging.
|
||
|
||
### Target
|
||
|
||
* Define a unified object header.
|
||
* Introduce object kind tags for future types (array, string, closure, etc.).
|
||
|
||
### Work items
|
||
|
||
* Define `ObjectHeader` containing:
|
||
|
||
* Mark bit or flag.
|
||
* Object kind/tag.
|
||
* Size or length field if required.
|
||
* Define an `ObjectKind` enum.
|
||
* Ensure header layout is clearly documented in comments.
|
||
* Do not implement traversal or GC logic yet.
|
||
|
||
### Acceptance checklist
|
||
|
||
* [ ] `ObjectHeader` and `ObjectKind` are defined.
|
||
* [ ] Code compiles without GC logic.
|
||
* [ ] Comments explain header semantics in English.
|
||
* [ ] `cargo test` passes.
|
||
|
||
### Tests
|
||
|
||
* None required.
|
||
|
||
### Junie instructions
|
||
|
||
**You MAY:**
|
||
|
||
* Introduce header structs and enums.
|
||
* Add comments explaining layout.
|
||
|
||
**You MUST NOT:**
|
||
|
||
* Implement object traversal logic.
|
||
* Add allocation strategies or pools.
|
||
|
||
**If unclear:**
|
||
|
||
* Ask before choosing header fields.
|
||
|
||
---
|
||
|
||
# PR-3.3 — Implement Basic Heap Allocator (No GC Yet)
|
||
|
||
### Briefing
|
||
|
||
We need a simple heap allocator that can store objects and return handles. This PR introduces a minimal allocator without garbage collection.
|
||
|
||
### Target
|
||
|
||
* Create a heap structure that stores objects.
|
||
* Return `HeapRef` handles for allocated objects.
|
||
|
||
### Work items
|
||
|
||
* Implement a `Heap` struct.
|
||
* Store objects in a vector or arena-like container.
|
||
* Provide methods such as:
|
||
|
||
* `allocate_object(kind, payload)`.
|
||
* Return a `HeapRef` handle.
|
||
* Integrate heap into VM state.
|
||
|
||
### Acceptance checklist
|
||
|
||
* [ ] Heap exists and can allocate objects.
|
||
* [ ] VM can hold a heap instance.
|
||
* [ ] Allocation returns valid `HeapRef`.
|
||
* [ ] `cargo test` passes.
|
||
|
||
### Tests
|
||
|
||
* Add a unit test allocating a few objects and verifying handles are valid.
|
||
|
||
### Junie instructions
|
||
|
||
**You MAY:**
|
||
|
||
* Use a simple vector-backed heap.
|
||
* Implement minimal allocation logic.
|
||
|
||
**You MUST NOT:**
|
||
|
||
* Implement garbage collection here.
|
||
* Add compaction or generational strategies.
|
||
|
||
**If unclear:**
|
||
|
||
* Ask before choosing allocation layout.
|
||
|
||
---
|
||
|
||
# PR-3.4 — Define GC Root Set (Stack, Frames, Globals)
|
||
|
||
### Briefing
|
||
|
||
The GC must know where roots are located. This PR defines the root set abstraction without running a full GC yet.
|
||
|
||
### Target
|
||
|
||
* Identify and enumerate all GC roots.
|
||
* Provide a mechanism to iterate them.
|
||
|
||
### Work items
|
||
|
||
* Define a root traversal interface or helper.
|
||
* Enumerate roots from:
|
||
|
||
* Value stack.
|
||
* Call frames.
|
||
* Globals or constant pools if applicable.
|
||
* Provide a function like `visit_roots(visitor)`.
|
||
|
||
### Acceptance checklist
|
||
|
||
* [ ] Root set traversal exists.
|
||
* [ ] Stack and frames are included as roots.
|
||
* [ ] Code compiles.
|
||
* [ ] `cargo test` passes.
|
||
|
||
### Tests
|
||
|
||
* Add a test that inserts a `HeapRef` in the stack and confirms it is visited by root traversal.
|
||
|
||
### Junie instructions
|
||
|
||
**You MAY:**
|
||
|
||
* Add root iteration helpers.
|
||
* Traverse stack and frames.
|
||
|
||
**You MUST NOT:**
|
||
|
||
* Implement marking logic yet.
|
||
* Change frame or stack architecture.
|
||
|
||
**If unclear:**
|
||
|
||
* Ask which structures must be roots.
|
||
|
||
---
|
||
|
||
# PR-3.5 — Implement Mark Phase (Reachability Traversal)
|
||
|
||
### Briefing
|
||
|
||
This PR introduces the mark phase of a simple mark-sweep collector. It must traverse from roots and mark reachable objects.
|
||
|
||
### Target
|
||
|
||
* Implement reachability marking from root set.
|
||
* Set mark bits on visited objects.
|
||
|
||
### Work items
|
||
|
||
* Implement a `mark()` function in the heap.
|
||
* Traverse roots using the root iterator.
|
||
* For each `HeapRef`, mark the object.
|
||
* Recursively traverse references inside objects.
|
||
* Ensure no infinite loops on cycles.
|
||
|
||
### Acceptance checklist
|
||
|
||
* [ ] Mark phase visits all reachable objects.
|
||
* [ ] Cycles are handled safely.
|
||
* [ ] Unreachable objects remain unmarked.
|
||
* [ ] `cargo test` passes.
|
||
|
||
### Tests
|
||
|
||
* Add tests:
|
||
|
||
* Reachable object stays marked.
|
||
* Unreachable object remains unmarked.
|
||
* Cyclic references do not crash.
|
||
|
||
### Junie instructions
|
||
|
||
**You MAY:**
|
||
|
||
* Implement a simple DFS or stack-based marking.
|
||
|
||
**You MUST NOT:**
|
||
|
||
* Add generational, incremental, or parallel GC.
|
||
* Change object layout.
|
||
|
||
**If unclear:**
|
||
|
||
* Ask before deciding traversal structure.
|
||
|
||
---
|
||
|
||
# PR-3.6 — Implement Sweep Phase (Reclaim Unmarked Objects)
|
||
|
||
### Briefing
|
||
|
||
After marking, the GC must reclaim unreachable objects. This PR implements the sweep phase.
|
||
|
||
### Target
|
||
|
||
* Remove or reclaim unmarked objects.
|
||
* Reset mark bits for the next cycle.
|
||
|
||
### Work items
|
||
|
||
* Iterate over heap storage.
|
||
* For each object:
|
||
|
||
* If unmarked, reclaim it.
|
||
* If marked, clear the mark bit.
|
||
* Ensure handles to reclaimed objects become invalid or reused safely.
|
||
|
||
### Acceptance checklist
|
||
|
||
* [ ] Unreachable objects are reclaimed.
|
||
* [ ] Reachable objects remain intact.
|
||
* [ ] Mark bits are cleared after sweep.
|
||
* [ ] `cargo test` passes.
|
||
|
||
### Tests
|
||
|
||
* Add tests:
|
||
|
||
* Allocate objects, drop references, run sweep, confirm removal.
|
||
* Confirm live objects survive.
|
||
|
||
### Junie instructions
|
||
|
||
**You MAY:**
|
||
|
||
* Implement a simple sweep over the heap vector.
|
||
|
||
**You MUST NOT:**
|
||
|
||
* Implement compaction or handle relocation.
|
||
* Introduce advanced memory strategies.
|
||
|
||
**If unclear:**
|
||
|
||
* Ask before choosing handle invalidation strategy.
|
||
|
||
---
|
||
|
||
# PR-3.7 — Integrate GC Cycle at Safepoint (`FRAME_SYNC`)
|
||
|
||
### Briefing
|
||
|
||
The GC must only run at safepoints. This PR connects the mark-sweep collector to the VM’s safepoint logic, primarily at `FRAME_SYNC`.
|
||
|
||
### Target
|
||
|
||
* Trigger GC cycles only at safepoints.
|
||
* Keep execution deterministic.
|
||
|
||
### Work items
|
||
|
||
* Identify safepoint handling code in the VM.
|
||
* Add logic:
|
||
|
||
* If allocation threshold exceeded, run GC at `FRAME_SYNC`.
|
||
* Ensure GC does not run in arbitrary instruction contexts.
|
||
|
||
### Acceptance checklist
|
||
|
||
* [ ] GC runs only at safepoints.
|
||
* [ ] No GC during arbitrary instruction execution.
|
||
* [ ] VM remains deterministic.
|
||
* [ ] `cargo test` passes.
|
||
|
||
### Tests
|
||
|
||
* Add a test where allocations trigger GC only at `FRAME_SYNC`.
|
||
|
||
### Junie instructions
|
||
|
||
**You MAY:**
|
||
|
||
* Hook GC invocation into safepoint handling.
|
||
|
||
**You MUST NOT:**
|
||
|
||
* Trigger GC at random points.
|
||
* Add background or concurrent GC.
|
||
|
||
**If unclear:**
|
||
|
||
* Ask before modifying safepoint semantics.
|
||
|
||
---
|
||
|
||
# PR-3.8 — GC Smoke and Stress Tests
|
||
|
||
### Briefing
|
||
|
||
We need confidence that the GC behaves correctly under simple and stressed conditions.
|
||
|
||
### Target
|
||
|
||
* Add deterministic smoke and stress tests for the GC.
|
||
|
||
### Work items
|
||
|
||
* Add tests:
|
||
|
||
* Simple allocation and collection cycle.
|
||
* Many short-lived objects.
|
||
* Cyclic references.
|
||
* Ensure tests are deterministic.
|
||
|
||
### Acceptance checklist
|
||
|
||
* [ ] Smoke tests pass.
|
||
* [ ] Stress tests pass.
|
||
* [ ] No nondeterministic failures.
|
||
* [ ] `cargo test` passes.
|
||
|
||
### Tests
|
||
|
||
* New GC-specific tests.
|
||
|
||
### Junie instructions
|
||
|
||
**You MAY:**
|
||
|
||
* Add deterministic tests.
|
||
|
||
**You MUST NOT:**
|
||
|
||
* Introduce random or timing-dependent tests.
|
||
* Modify GC semantics to satisfy tests.
|
||
|
||
**If unclear:**
|
||
|
||
* Ask before changing test scenarios.
|