dymokomi/luce-browser-foundation
Source of release 0.6.1
0.6.1 / 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.