Skip to content

feat: fork-frontier waves 1-3 — advanced V8 bindings#4

Open
yneves wants to merge 1 commit into
mainfrom
feat/fork-frontier-waves-1-3
Open

feat: fork-frontier waves 1-3 — advanced V8 bindings#4
yneves wants to merge 1 commit into
mainfrom
feat/fork-frontier-waves-1-3

Conversation

@yneves
Copy link
Copy Markdown
Collaborator

@yneves yneves commented May 18, 2026

Summary

Implements the remaining fork-frontier techniques from doc 207, giving er and blindfox fine-grained control over V8's runtime behavior.

Wave 1 — Cooperative GC & microtasks

  • AdjustExternalMemory — report Go-side allocations to V8's GC heuristic so it can schedule collections at the right time
  • SetMicrotasksPolicy — control when V8 drains the microtask queue (Explicit / Scoped / Auto)
  • EnqueueMicrotask — schedule JS functions as microtasks without the overhead of Promise.resolve().then()
  • SetOOMErrorHandler — observe OOM events via a Go callback trampoline for diagnostics and graceful shutdown

Wave 2 — Zero-copy data & profiling

  • ArrayBufferNewArrayBuffer (copy), NewArrayBufferAlloc (V8-sandbox-allocated), ArrayBufferGetBytes for single-copy Go↔JS binary data transfer
  • ExternalStringResourceNewExternalOneByteString for zero-copy Latin-1/ASCII string injection into V8
  • Named property interceptors — getter/setter callbacks on ObjectTemplate using an isolate callback registry, enabling virtual-property patterns
  • HeapProfilerTakeHeapSnapshot returning Chrome DevTools-compatible JSON for memory debugging

Wave 3 — ES module support

  • CompileModule / Instantiate / Evaluate — full ESM lifecycle with Go-side resolve callback
  • GetNamespace — access module exports after evaluation
  • Import request introspectionGetModuleRequestsLength / GetModuleRequest to inspect import specifiers before instantiation
  • ModuleStatus enum — complete lifecycle tracking

Deferred

  • Fast API Callbacks (F4.1) — C++ CFunction templates are impractical to bridge through CGO
  • Streaming Bundle Compile (F1.3) — requires background thread management for ScriptStreamingTask

Test plan

  • 35 new tests across 9 test files covering all new APIs
  • Full regression suite passes (go test ./... — 0 failures)
  • V8 sandbox compatibility verified (ArrayBuffer uses V8-internal allocator)
  • CGO trampoline patterns validated (OOM handler, interceptors, module resolver)
  • Documentation updated: api-reference.md, architecture.md, maintaining.md, CHANGELOG.md

Implement the remaining fork-frontier techniques from doc 207 to give
er and blindfox fine-grained control over V8's runtime behavior.

Wave 1 — Cooperative GC & microtasks:
  - AdjustExternalMemory: report Go-side allocations to V8's GC heuristic
  - SetMicrotasksPolicy: control when V8 drains the microtask queue
  - EnqueueMicrotask: schedule JS functions as microtasks without Promise
  - SetOOMErrorHandler: observe OOM events via Go callback trampoline

Wave 2 — Zero-copy data & profiling:
  - ArrayBuffer: NewArrayBuffer (copy), NewArrayBufferAlloc (V8-sandbox),
    ArrayBufferGetBytes for single-copy Go↔JS data transfer
  - ExternalStringResource: NewExternalOneByteString for zero-copy
    Latin-1/ASCII string injection into V8
  - Named property interceptors: getter/setter callbacks on ObjectTemplate
    using isolate callback registry
  - HeapProfiler: TakeHeapSnapshot returning DevTools-compatible JSON

Wave 3 — ES module support:
  - CompileModule, Instantiate (with Go resolve callback), Evaluate,
    GetNamespace, import request introspection, full ModuleStatus enum

Deferred to a future release:
  - Fast API Callbacks (C++ CFunction templates impractical via CGO)
  - Streaming Bundle Compile (requires background thread management)

35 tests across 9 new test files. Full regression suite passes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant