mirror of https://github.com/vercel-labs/scriptc.git synced 2026-10-22 05:59:31 +08:00

Files

T

Malte Ubl bf508eb70f Publish typed object graphs to workers by reference (@scriptc/threads)

The new @scriptc/threads package exports publish(value) and
sharesPublishedGraphs. Node.js runs its JavaScript: publish validates
the whole graph (plain objects, arrays, class instances, Maps, Sets and
primitives other than symbols), then deep-freezes it, and published Maps
and Sets reject mutation. scriptc builds lower both exports to
intrinsics and never compile the package body.

In scriptc, publish makes the graph immutable and immortal: a
compiler-emitted walker per static type (llvm/publish.ts) marks every
object rc == SIZE_MAX through a runtime worklist (scr_publish.c), so
retains, releases and the collector skip it and nothing frees it, and
the objects leave the collector's buffers. Hierarchy members dispatch on
the concrete class; arrays, maps, sets, strings and dyn subgraphs have
runtime walkers. Static types over-approximate a graph, so an
unpublishable type gets a refusing walker that fails only when a value
is present, and every mark is logged so a refusal restores the whole
graph, exactly like the Node implementation's validate-first order.

A typed-ref capsule over a published object travels through postMessage
and workerData as a pointer (a fresh capsule in the receiver; vtables,
adapters and type keys are process-wide); immortal dyn graphs inside a
message are shared the same way. Iterating a published map no longer
writes its iteration depth.

Stores into the static types a program publishes (computed by
backend/publication.ts, a class with its whole hierarchy) carry a guard
that throws Node's frozen-object TypeErrors, and may-throw counts them.
The corpus program pins the contract against Node: shared and cyclic
class graphs with arrays, maps, sets and records read identically on
both threads, every write form fails with Node's message, unpublished
instances of the same classes stay writable, a refused publish leaves
its graph unchanged, and a worker-published graph reaches the main
thread. packages/threads/README.md documents the contract and the
differences (prototypes and identity across messages).

Each mark records its object kind, so a successful publish takes the
objects out of the RC audit's live counts (immortal objects are never
freed).

Dates (time values) and process streams (descriptors) are scalars in
scriptc, so their walkers refuse a date field or root directly instead
of pushing its bits as a pointer; the refusal corpus program pins the
statically typed refusals (date, function, RegExp, typed array and Error
values in class and record fields, and a date root) against Node.

Main lowers a discarded or union-typed `xs.pop()` to a length
truncation; those stores now carry a `pop` marker so a published array
fails with pop's own TypeError ("Cannot delete property 'N'", or the
length message for an empty array, whose `length = 0` store the emitter
drops unless the array type can be published).

2026-10-10 01:00:36 -05:00

3.3 KiB

Raw Blame History

@scriptc/threads

Zero-copy sharing of immutable object graphs between worker threads in scriptc builds, with a Node.js implementation that gives the same graphs the same immutability.

import { Worker, isMainThread, workerData } from "node:worker_threads";
import { publish, sharesPublishedGraphs } from "@scriptc/threads";

if (isMainThread) {
  const program = publish(buildProgram()); // immutable from here on
  new Worker(new URL(import.meta.url), { workerData: { program } });
} else {
  const program = publish((workerData as { program: Program }).program);
  check(program);
}

Contract

publish(value) returns value after making it and everything it reaches immutable.

Publishable: primitives other than symbols, plain objects, arrays, class instances, Map and Set. Anything else that is actually reached (functions, symbols, accessor properties, Date, RegExp, Error, Promise, typed arrays and other built-in objects) makes publish throw a TypeError (Cannot publish a function, Cannot publish a Date object, ...) and leaves the whole graph unchanged: both implementations validate the graph before changing anything.
Writes into a published graph throw Node's frozen-object TypeErrors: Cannot assign to read only property 'x' of object '#<Point>', Cannot add property 3, object is not extensible, Cannot delete property '2' of [object Array], and so on. Published Maps and Sets reject set, add, delete and clear with Cannot modify a published Map (or Set).
publish is idempotent; publishing an already published graph is cheap.

In scriptc builds a published graph is also immortal: it is never reference counted, collected or freed again, and postMessage and workerData deliver it to other threads by reference (sharesPublishedGraphs is true). Node.js clones what it posts (sharesPublishedGraphs is false). Programs that behave identically under both follow three rules:

A receiver calls publish on what it receives. In scriptc this is a no-op; in Node.js it freezes the clone, so writes fail the same way.
A receiver does not depend on prototypes. scriptc delivers the same class instances, with their methods and instanceof relations; Node's structured clone delivers plain objects. Error messages that name the receiving object's class differ accordingly (#<Point> in scriptc, #<Object> in Node.js).
Identity is not compared across messages. Two posts of one published graph arrive as the same object in scriptc and as two clones in Node.js.

scriptc specifics

Publication walks the graph once (compiler-generated walkers per static type) and marks every object immortal. Static types over-approximate what a graph holds, so an unpublishable type reachable from the root's type is only refused if a value of it is actually present.
Stores into the static types a program publishes carry a guard (one load and branch). In a store o.x = f(), Node evaluates f() before the write fails; scriptc does too, except for writes into union-typed class fields and for Map/Set/array mutator methods, where the guard runs before the arguments are evaluated.
Private fields (#x) of published objects cannot be written either (Node.js allows writing private fields of frozen objects).
Published objects must not be written by any thread; scriptc enforces this for every store the compiler emits.

3.3 KiB Raw Blame History

@scriptc/threads

Contract

scriptc specifics

3.3 KiB

Raw Blame History