docs(gc): document boa_gc API surface used by the engine#38
docs(gc): document boa_gc API surface used by the engine#38mrhapile wants to merge 2 commits intoboa-dev:mainfrom
Conversation
Signed-off-by: mrhapile <[email protected]>
Signed-off-by: mrhapile <[email protected]>
There was a problem hiding this comment.
Pull request overview
Adds repository documentation that defines the Boa engine’s boa_gc dependency contract, capturing the specific public API surface that a replacement collector would need to support.
Changes:
- Adds
docs/boa_gc_api_surface.mddescribing the engine-facingboa_gcpointer types, traits, weak references/collections, macros, and runtime utilities. - Adds a small mark-sweep test that smoke-tests creating an
oscarsWeakGcfrom a strongGc.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
oscars/src/collectors/mark_sweep/tests.rs |
Adds a minimal WeakGc creation smoke test for the mark-sweep collector. |
docs/boa_gc_api_surface.md |
New documentation describing the intended boa_gc API compatibility contract used by the Boa engine. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
| ```rust | ||
| // Allocate a new GC-managed value. | ||
| Gc::new(value: T) -> Gc<T> | ||
|
|
||
| // Allocate a value that may reference itself through a weak pointer. | ||
| Gc::new_cyclic<F>(data_fn: F) -> Gc<T> | ||
| where F: FnOnce(&WeakGc<T>) -> T |
There was a problem hiding this comment.
The fenced snippet is labeled as ```rust but uses pseudo-signatures (e.g., Gc::new(value: T) -> Gc<T>), which isn’t valid Rust syntax. Consider rewriting these as valid Rust items (`pub fn ...`) or changing the fence to `text`/`rust,ignore` so it’s clear the snippet is illustrative.
This PR documents the subset of the
boa_gcAPI that the Boa enginecurrently depends on.
ref - #27
Understanding the exact API surface used by the engine is important for:
The document describes pointer types, tracing traits, weak references,
interior mutability primitives, and runtime utilities relied upon by
the engine.
The goal is to provide a clear compatibility contract for any garbage
collector implementation that aims to replace
boa_gc.The document deliberately avoids internal implementation details (heap vectors, Box allocation, mark-stack internals) and focuses exclusively on the engine → GC interface boundary, making it suitable for inclusion in repository documentation.