Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-foundation

Source of release 0.6.0

0.6.0 / docs / regions / r04.md

# Region r04: LibGC (`gc`) — what other regions need to know

The `gc` module is LibGC, ported faithfully (DESIGN.md §3.2), with the additions of DESIGN.md §3.1–§3.4
(managed blobs, the large-object space, the heap as luce-base's `Allocator`, the stack and register
scan in `asm`). Each fragment's header describes it, and `docs/namemap.tsv` lists every name.

## Signature and type changes against the skeleton

### Roots

- The root set is `gc.GcHashMap[HeapRoot]`, keyed by cell address. It replaces
  `HashMap<Cell*, HeapRoot>` in:
  - `heap_construct`'s embedder callback (`ak.Function1[GcHashMap[HeapRoot]*, unit]`);
  - the `gather_roots` slots of `RootVectorBase` and `RootHashMapBase`.

  An embedder adds a root with `gc.gc_hash_map_set(roots, (usize)cell, gc.HeapRoot(type_ = .vm))`.
- `GC::Root<T>` held in managed memory or on the stack is just `T*`: the conservative scans keep the
  cell alive, and `make_root*` returns the cell.
- For pointers kept outside managed memory (C heap, OS callbacks), use `gc.Root[T]`:
  `root_create(cell)`, `root_cell(&root)`, and `root_release(&root)` where C++ drops the last copy.
- A `GC::Root<T>` *field inside a cell* is not a root in the port. Visit it in that cell's
  `visit_edges`: a cell's bytes are scanned for blob pointers only, never for cell pointers.

### Allocation

- `heap_allocate_cell[T](heap, allocator: CellAllocator*?) -> Cell*` takes the class's
  type-isolating allocator (`&x_cell_allocator.allocator`), or none for size-based allocation.
  `heap_allocate_cell_of_size(heap, size, allocator?)` is the seam for `web_allocate_cell` with a
  `ClassInfo` size.
- Cells come back zeroed, with a live header whose vtable is `cell_vtable`. The caller sets
  `vtable` and `class_id` and constructs under `heap_defer_gc` / `heap_undefer_gc`, as
  `Heap::allocate` does. `has_own_gc_allocator_marker` (a compile-time check) is dropped.
- Type-isolating allocators are zero module `var`s. The engine calls
  `type_isolating_cell_allocator_construct` for each class before its first allocation.

### Functions, weak references, iteration

- `GC::create_function` is `create_function0` … `create_function8`, one per arity, taking an
  `ak.FunctionN`. `gc.Function0` … `gc.Function8` conform to `IsCell`.
- Weak API:
  - `make_weak(ptr)` and `weak_construct(&w, ptr)` construct a `Weak`;
  - `weak_assign` is `operator=`;
  - `weak_ptr(&w) -> T*?` reads it;
  - `weak_impl(&w)` answers the WeakImpl.

  A null Weak has `m_impl == none`. `weak_callback` returns a `WeakCallback[T]`, run with
  `weak_callback_call`.
- WeakImpls are not reference counted. A cell has one WeakImpl, shared by all its Weaks, and
  the impl goes back to its weak block when the cell dies. A `Weak` also holds the impl's
  generation, so a Weak whose impl went back reads none. A `Weak` may therefore live anywhere: a
  cell, a blob (atomic too), the stack, the C heap or a module global. It is copied as plain
  bytes and never released (`weak_impl_ref`, `weak_impl_unref` and `weak_impl_ref_count` are
  dropped). See DESIGN.md §3.3.
- `for_each_*(callback)` functions return iterables (DESIGN.md §2.9):
  - `heap_for_each_block`;
  - `cell_allocator_for_each_block`;
  - `heap_block_for_each_cell`;
  - `heap_block_for_each_cell_in_state`.

  `weak_hash_set_begin` returns an iterable of the live cells; `weak_hash_set_end` and
  `weak_hash_set_end_const` are dropped.

### Visitor

- Visitor overloads:
  - cells: `cell_visitor_visit_cell*`;
  - `Ptr`/`Ref` of any `IsCell` class: `cell_visitor_visit_t`, `cell_visitor_visit_t_2`;
  - spans: `cell_visitor_visit_opaque` (GC::Ref) and `cell_visitor_visit_span` (GC::Ptr);
  - vectors: `cell_visitor_visit_vector`, `cell_visitor_visit_vector_nullable`,
    `cell_visitor_visit_vector_nan_boxed_value`;
  - hash tables: `cell_visitor_visit_hash_table`, `cell_visitor_visit_hash_table_nullable`,
    `cell_visitor_visit_opaque_2` (ordered);
  - hash maps: `cell_visitor_visit_hash_map` (values), `cell_visitor_visit_hash_map_keys`,
    `cell_visitor_visit_hash_map_keys_and_values`, `cell_visitor_visit_opaque_3` (ordered);
  - optionals: `cell_visitor_visit_opaque_4`;
  - NaN-boxed values: `cell_visitor_visit_nan_boxed_value`,
    `cell_visitor_visit_span_nan_boxed_value`.
- The container visitors read ak's layout in place:
  - `Vector.m_outline_buffer` and `m_size`;
  - `HashTable.m_buckets` and `m_capacity`, with `bucket.state != 0` meaning a used bucket.

  **r01 must keep these fields**, or update the visitors in `gc/cell.lucb`.

### C++ destructors

C++ destructors become explicit calls:

- `heap_destroy`, `block_allocator_destroy`;
- `conservative_vector_base_destroy`, `root_vector_base_destroy`, `root_hash_map_base_destroy`;
- `root_impl_destroy`, `weak_container_destroy`, `defer_gc_destroy`.

### Smaller signature changes

- `heap_sweep_dead_cells(heap, print_report, measurement_start: u64)`: a `time.now()` value
  replaces `Core::ElapsedTimer`.
- Pointers that C++ never returns null are non-null:
  - `block_allocator_allocate_block`;
  - `heap_create_weak_impl`;
  - `heap_block_from_cell`, `heap_block_base_from_cell`;
  - `heap_block_create_with_cell_size`.

### Types fixed by hand

- `CellState` is `as u8` with `dead = 1` (the generator produced `-1`).
- `HeapBlock` has no `m_storage` field; `heap_block_storage(block)` answers it (offset 64, as in
  C++).
- `HeapBlockFreelistEntry`, `GraphConstructorVisitorGraphNode`, the constants, the list nodes and
  the Heap's fields are filled in. `WeakHashSet` uses `WeakHashSetInternalTraits`.

## For ak (r01)

- AK's atomic allocations should go through `gc.heap_atomic_allocator(heap)` while a heap is
  current (DESIGN.md §3.3 rule 5). ak needs a hook for it.
- `gc/ak_support.lucb` holds private stand-ins until r01–r03 land. Each one says which ak
  function replaces it:
  - `dbgln(fmt)`, `sv`;
  - calling an `AK::Function`;
  - `StackInfo`;
  - `get_random_uniform`.

## Not yet exercised

- `WeakHashSet` insert, remove and lookup call r01's HashTable stubs.
- `heap_dump_graph`'s JSON calls r02/r03 stubs.

## Compiler issue

`asm` blocks that declared a callee-saved register destroyed did not make the function save and
restore it. See `.donors/luce-browser-tools/compiler-issues/asm_callee_saved_clobber.lucb`
(COMPILER-REQUESTS item 12). Fixed in Luce 0.8.13: the register-spill test sets a marker in x19
(rbx) and finds it in the spill.