@scriptc/compiler 0.2.6 → 0.2.8

package/dist/backend/llvm/shapes.d.ts

@@ -3,6 +3,7 @@
  * their fields. Every allocation has a size_t reference count at offset zero
  * and participates in the runtime allocation audit. */
 import type { IrModule, IrRecordShape, IrType } from "../../ir/ir.js";
+import type { NullableUnions } from "./nullable-unions.js";
 /** What the tables need from the emitter: the extern-declaration ledger
  * and the module-wide cycle/shape indexes. */
 export interface ShapeHost {
@@ -15,8 +16,26 @@ export interface ShapeHost {
     readonly cycleColorOffset: number;
     readonly tracedShapes: Set<string>;
     readonly tracedUnions: Set<string>;
+    /** Unions represented as a nullable arm pointer (nullable-unions.ts):
+     * their RC and trace entry points are the arm's NULL-tolerant ones. */
+    readonly nullableUnions: NullableUnions;
     readonly recordsById: Map<string, IrRecordShape>;
     readonly recordCloneShapes: ReadonlySet<string>;
+    /** Emit the live-object audit notes (`scr_obj_alloc_note` /
+     * `scr_obj_free_note`) in emitted new/free helpers. Only runtimes built
+     * with SCR_RC_AUDIT (the sanitized lane) count them; release and dev
+     * runtime packs define them empty, so plain builds omit the calls.
+     * Absent means emit. */
+    readonly objectAudit?: boolean;
+    /** Inline the small-object allocator's fast paths (llvm/alloc.ts). */
+    readonly inlineAlloc?: boolean;
+    /** Worker executables: the inline allocator state is thread-local. */
+    readonly threadLocalAlloc?: boolean;
+    /** Inline RC fast-path helpers requested so far ("<family>:<op>"); the
+     * emitter defines each once through {@link emitInlineRcHelpers}. Null
+     * keeps every retain/release a runtime call: inline RC is a
+     * size-for-speed optimization of the `speed` posture only. */
+    readonly rcHelpers: Set<string> | null;
 }
 /** Every emitted function/helper carries #0 = { sanitize_address } — see
  * the emitter header. */
@@ -34,12 +53,66 @@ export declare function vAdapters(host: ShapeHost, t: IrType): {
     release: string;
 };
 /** The retain call target (ptr → ptr, +1 unless immortal) — the `_v`
- * table above; the split exists so call sites read type-directedly. */
+ * table above; the split exists so call sites read type-directedly.
+ * Families with a mirrored fast path call the inline helper instead. */
 export declare function retainSym(host: ShapeHost, t: IrType): string;
+/** Definitions of the requested NULL-skipping retain wrappers. */
+export declare function emitNullableRetainWrappers(host: ShapeHost): string[];
 /** The release call target (ptr → void, NULL-tolerant). The runtime's
  * typed releases are external symbols, so the direct (non-`_v`) entry
- * points serve where one exists; records use their emitted helper. */
+ * points serve where one exists; records use their emitted helper.
+ * Families with a mirrored fast path call the inline helper instead. */
 export declare function releaseSym(host: ShapeHost, t: IrType): string;
+/** How a runtime family decides whether an object carries a ScrCycHdr:
+ * never, always, or per object through the trace slots its C release
+ * tests (`a->elem_trace`, `m->key_trace || m->val_trace`). */
+type RcCycle = "none" | "always" | "arr" | "map";
+interface InlineRcFamily {
+    readonly cycle: RcCycle;
+    /** The C retain tolerates NULL (the others dereference unconditionally). */
+    readonly retainNull: boolean;
+    /** The out-of-line release behind the inline fast path: it owns the
+     * rc == 1 → 0 transition and, for per-object (`arr`/`map`) families,
+     * every release of a headered object. Null keeps the release a plain
+     * runtime call. */
+    readonly release: string | null;
+}
+/** Runtime RC families whose fast paths the backend mirrors in IR, keyed
+ * by the family name without its `scr_` stem prefix. Each
+ * row restates the C entry points in scr_runtime.h and the runtime TUs:
+ * retain is `if (rc != SIZE_MAX) rc++`, and a release that leaves the
+ * object alive is `rc--`, then scr_cyc_on_release when headered. Everything else (destruction, RC-audit accounting, the
+ * collector's on_dead bookkeeping) stays in the runtime release, which
+ * repeats its own checks, so the fast path never duplicates it.
+ *
+ * Releases stay plain calls for:
+ * - dyn: scr_dyn_release buffers a surviving object only for some kinds.
+ * - arr: array releases are the most numerous release sites and the
+ *   least hot (at most 1% self time across the benchmark suite), and
+ *   inlining them roughly doubled the code growth for no measured speedup.
+ *   Array retains are inlined. */
+export declare const INLINE_RC_FAMILIES: Readonly<Record<string, InlineRcFamily>>;
+type RcOp = "retain" | "release";
+/** The mirrored family for an RC operation on a runtime stem (`scr_str`),
+ * or null when it stays a call. */
+export declare function inlineRcFamily(stem: string, op: RcOp): InlineRcFamily | null;
+/** The release call target for a capture box: scr_box_release's fast path,
+ * or scr_box_release itself without inline RC. */
+export declare function boxReleaseSym(host: ShapeHost): string;
+export declare function inlineRcDecls(host: ShapeHost): string[];
+/** Definitions for every requested inline RC helper, in a stable order.
+ *
+ * retain: a NULL skip where the C retain tolerates NULL, the immortal skip
+ * and the increment; retains never touch the cycle header.
+ *
+ * release: NULL and immortal skips. rc == 1 (and any headered object of a
+ * per-object family) calls the runtime release, marked cold so destruction
+ * stays out of line. Otherwise decrement; always-headered families then
+ * inline scr_cyc_on_release's already-buffered case (`buffered` is the i16
+ * four bytes after color), calling the runtime only
+ * to enqueue a new candidate. scr_runtime.h asserts both header offsets and
+ * the trace-slot offsets. */
+export declare function emitInlineRcHelpers(host: ShapeHost): string[];
 /** The trace entry point for a payload/field type, or null when the type
  * cannot participate in a cycle. */
 export declare function traceAdapter(host: ShapeHost, t: IrType): string | null;
@@ -75,19 +148,41 @@ export declare function mapKeyParamType(access: MapKeyAccess): string;
 /** The ScrMapKeyKind / ScrMapValKind constants for scr_map_new. */
 export declare function mapKeyKindNum(key: IrType, unionArms?: IrType[]): number;
 export declare function mapValKindNum(value: IrType): number;
-/** The immortal-skip + mark-live retain body shared by every shape. The
- * cycle header sits before the object; `color` is at obj-16 on 64-bit
- * targets and obj-12 on wasm32,
- * so mark-live is one i32 store at obj-16 (scr_cyc_mark_live inlined —
- * the runtime's is a static inline with no external symbol). */
-export declare function retainBody(host: ShapeHost, fnName: string, traced: boolean, comment?: string): string[];
+/** The NULL- and immortal-skipping retain body shared by every shape. A
+ * retain never touches the cycle header: a buffered candidate that is
+ * retained again stays a candidate (scr_cycle.c, markRoots). */
+export declare function retainBody(host: ShapeHost, fnName: string, comment?: string): string[];
 /** Scalar fields and native strings cannot form recursive ownership chains.
  * Other reference kinds conservatively share the runtime destruction budget. */
 export declare function needsBoundedRelease(type: IrType): boolean;
 /** Common NULL/immortal/decrement skeleton for ordinary object releases.
  * `freeBody` owns the zero-ref teardown and must leave the current block at
- * its end; traced objects also get the possible-cycle-root branch. */
+ * its end; traced objects also get the possible-cycle-root branch.
+ *
+ * `fnName` is only the inlinable fast path (releaseFastPath); the complete
+ * release is `${fnName}_slow`, kept out of line so callers that inline the
+ * release do not also inline its teardown. */
 export declare function releaseBody(host: ShapeHost, fnName: string, traced: boolean, freeBody: string[], comment?: string, bounded?: boolean): string[];
+/** The inlinable half of an object release. A reference that is neither the
+ * last one nor immortal (rc - 2 < SIZE_MAX - 2 rules out 0, 1 and SIZE_MAX
+ * in one compare) only decrements and, for headered objects, takes the
+ * possible-root step. Immortal references return; NULL and last references
+ * call `slow`, which
+ * holds the complete release: inlining it everywhere would copy teardowns
+ * (and their destroy calls) into every caller. */
+export declare function releaseFastPath(host: ShapeHost, fnName: string, slow: string, traced: boolean, comment?: string): string[];
+/** The possible-cycle-root step of a release that left a headered object
+ * alive: scr_cyc_on_release with its early return inlined. Read `buffered`
+ * (the i16 four bytes after color; nonzero for a queued candidate or a
+ * tenured object) and call the runtime only to enqueue a new candidate.
+ * Every emitted release of a headered object shares this sequence
+ * (scr_runtime.h asserts the offset); it ends by branching to `done`. */
+export declare function cycleRootLines(host: ShapeHost, done: string): string[];
+/** The death of a headered object: scr_cyc_on_dead with its early return
+ * inlined. Only an object still in a candidate buffer
+ * (`buffered` nonzero) has an entry to remove; the sequence continues at
+ * the new block `next`. */
+export declare function cycleDeadLines(host: ShapeHost, next: string): string[];
 /** Per-record-shape LLVM emission: the named struct types (returned as
  * `typeDefs`) and the new/retain/release (+trace/gcFree for cycle-capable
  * shapes) function definitions (`defs`). Layout follows the runtime ABI: