@scriptc/compiler 0.2.8 → 0.2.10

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

@@ -11,6 +11,7 @@ import { OptionalArrayReads, type LocalArrayRead } from "./local-array-reads.js"
 import { CheckedNarrows } from "./checked-narrows.js";
 import { type MapReadLifetimes } from "./map-read-lifetimes.js";
 import { ReferenceEffects } from "./reference-effects.js";
+import { ReferenceWrites, type Writes } from "./reference-writes.js";
 import { StackCallbacks } from "./stack-callbacks.js";
 import { AmbientReceiverReaders } from "./constant-callbacks.js";
 import { type StringSliceSnapshot } from "./string-slices.js";
@@ -45,10 +46,14 @@ export interface LlvmTargetOptions {
     /** Emit retain/release fast paths inline (the `speed` posture). Off, every
      * retain and release is a runtime call. */
     inlineRc?: boolean;
+    /** Define `scr_detached_exit` so the Linux runtime hands the address-space
+     * teardown after `process.exit` to a helper process (`--detached-exit`).
+     * Executables only; the runtime's weak default keeps it off. */
+    detachedExit?: boolean;
 }
-export declare function emitLlvmModule(mod: IrModule, options?: LlvmTargetOptions): string;
+export declare function emitLlvmModule(input: IrModule, options?: LlvmTargetOptions): string;
 /** Keep large translation units below the host's single-string limit. */
-export declare function emitLlvmModuleSource(mod: IrModule, options?: LlvmTargetOptions): string | readonly string[];
+export declare function emitLlvmModuleSource(input: IrModule, options?: LlvmTargetOptions): string | readonly string[];
 export declare class LlEmitter {
     readonly mod: IrModule;
     localArrayReads: Map<string, LocalArrayRead>;
@@ -73,12 +78,27 @@ export declare class LlEmitter {
     private debugScope;
     readonly sizeType: "i32" | "i64";
     readonly ffiExtendNarrowIntegers: boolean;
-    readonly cycleColorOffset: number;
+    readonly cycleBufferedOffset: number;
+    /** Emitted ScrCycType descriptors so far (their collector statistics
+     * indices; see ShapeHost.nextCycKind). */
+    private cycKinds;
     readonly wasi: boolean;
+    /** The target lacks a rounding instruction at its baseline CPU (x86-64
+     * before SSE4.1), so `llvm.trunc` would lower to a libm call: emit
+     * truncation inline through an integer round trip instead. */
+    readonly inlineTrunc: boolean;
     /** ELF worker executables give thread-locals the executable TLS models. */
     private readonly executableTls;
+    /** Source loops enclosing the statement being emitted in the current
+     * function body. */
+    private loopDepth;
+    /** Darwin worker executables read the stack guard from a pthread
+     * thread-specific-data slot off the thread pointer (scr_runtime.h's
+     * SCR_STACK_GUARD_TSD): the architecture names the access sequence. */
+    private readonly stackGuardTsd;
     private readonly emitLibraryIdentity;
     private readonly runtimeAbiMarker;
+    private readonly detachedExit;
     /** Interned string literals: UTF-8 text → { symbol, byte length } —
      * first-use order, the runtime ABI’s determinism discipline. */
     private readonly literals;
@@ -140,6 +160,12 @@ export declare class LlEmitter {
      * fiberless-async analysis scans it for suspension entry points. */
     private readonly fnDefText;
     readonly referenceEffects: ReferenceEffects;
+    /** Field-sensitive reference writes (null in debug builds). */
+    referenceWrites: ReferenceWrites | null;
+    private readonly borrowedReturnKeyCache;
+    /** The statement list being emitted and the current index, for blocks
+     * whose bindings end with the list (emitBlock and function bodies). */
+    private stmtCursor;
     readonly optionalArrayReads: OptionalArrayReads;
     readonly checkedNarrows: CheckedNarrows;
     callArrayReads: Map<IrExpr, LocalArrayRead>;
@@ -183,6 +209,9 @@ export declare class LlEmitter {
     readonly ffiHasRetainedCallback: boolean;
     private readonly ffiHasForeignCallback;
     private readonly globalTypes;
+    /** Module constants that keep one value once initialized
+     * (immutability.ts stableGlobals). */
+    private stableGlobals;
     private readonly tdzGlobals;
     readonly constantNumericTables: ReadonlyMap<string, ConstantNumericTable>;
     /** May-throw analysis (computeMayThrow): pending
@@ -198,6 +227,13 @@ export declare class LlEmitter {
     /** Static types whose values can be published (@scriptc/threads): their
      * stores carry the frozen-object guard. Null without publish calls. */
     readonly publishedTypes: PublishedTypes | null;
+    /** Construction-only class and record fields (immutability.ts); null
+     * where the facts are disabled. */
+    private readonly immutableFields;
+    /** Constructor function names: their bodies may still write their own
+     * `this`'s construction-only fields. */
+    private readonly constructorFunctions;
+    private inConstructor;
     /** Method names with at least one may-throw implementation — the
      * virtualCall pending check's key. */
     readonly mayThrowMethods: Set<string>;
@@ -273,6 +309,12 @@ export declare class LlEmitter {
     private readonly initializerBindings;
     /** Whole-program int32 storage and parameter/result facts. */
     readonly int32Slots: Int32Slots;
+    /** Immutable module constants (contract types) whose graphs become
+     * immortal once initialized: their reads need no reference counting. */
+    readonly immortalGlobals: ReadonlySet<string>;
+    /** ProgramLifetime hierarchy roots (contract types): their instances are
+     * immortal from construction (classes.ts programLifetimeClass). */
+    readonly programLifetime: ReadonlySet<string>;
     private numericLocals;
     private captureIds;
     /** Active induction bindings retain their width independently of size_t. */
@@ -286,6 +328,11 @@ export declare class LlEmitter {
         };
     }>;
     private countedLoopsEnabled;
+    /** Whole-program final reference fields (ir/final-fields.ts). */
+    private finalFields;
+    /** The current function may borrow final fields of borrowable objects:
+     * not a constructor (where they change), not async or a generator. */
+    private finalFieldBorrows;
     integerRanges: IntegerRanges;
     private byteWindowsEnabled;
     private byteWindowEntries;
@@ -486,6 +533,13 @@ export declare class LlEmitter {
      * unwind returns it as the dummy, so a call in tail position keeps a single
      * return and stays eligible for tail-call and recursion elimination. */
     private emitUnwind;
+    /** Loads the running thread's exact pending word (ELF worker
+     * executables, scr_exception.c): bit 0 mirrors the active cell, bit 1
+     * requests the context's stop. It lives in the executable's static TLS
+     * block, so the access is one thread-pointer-relative load. Monotonic by
+     * default: a loop must not hoist the load out and miss a cross-thread
+     * stop (see emitPendingCheck for the unordered tests). */
+    private loadExcFlag;
     /** Instructions (two-space indented) that set the i1 `dest` to "an
      * exception is pending in the active context" — scr_exc_pending()'s
      * meaning — for the helper and adapter bodies that test it outside
@@ -501,11 +555,12 @@ export declare class LlEmitter {
      * call's result temp must join its frame BEFORE this runs so the unwind
      * releases the dummy (NULL for refcounted kinds) harmlessly. A scalar
      * call result of the function's return type may be passed as the unwind's
-     * dummy value (see emitUnwind). */
+     * dummy value (see emitUnwind). `poll` marks a worker termination poll
+     * (function entry or loop budget), whose test must stay ordered. */
     emitPendingCheck(passThrough?: {
         name: string;
         type: IrType;
-    }): void;
+    }, poll?: boolean): void;
     /** After a runtime call that ALWAYS leaves an exception pending (the
      * compiler-resolved Node throws): the pending test would always answer
      * true, so unwind unconditionally. Emission continues in a block with no
@@ -515,6 +570,9 @@ export declare class LlEmitter {
     /** A recursive function's entry check: below the running stack's guard,
      * throw Node's RangeError and unwind like any other pending exception. */
     private emitStackCheck;
+    /** Whether the emitter follows this call with a pending test (the
+     * conditions in expr-calls.ts). */
+    private callTestsPending;
     private workerLoopBudget;
     private emitWorkerLoopCheck;
     /** Moves an already-evaluated value into the runtime's exception cell —
@@ -621,6 +679,13 @@ export declare class LlEmitter {
      * array cell holding the value and move it into the ARR-kind box
      * (set_ref releases nothing — the slot was the empty sentinel). */
     private tdzScalarInit;
+    /** The payload a TDZ box holds before its declaration runs, when that is
+     * not NULL. A nullable union's value is its arm pointer with NULL as a
+     * unit arm (nullable-unions.ts), so a stored `null`/`undefined` would
+     * read back as the temporal dead zone; such boxes start at the module's
+     * immortal NULLABLE_ABSENT sentinel instead, which no value of the
+     * binding can hold and every RC entry point and the collector skip. */
+    private tdzEmptySentinel;
     /** The TDZ-guarded read of a boxed binding: an empty payload slot is
      * the temporal dead zone — throw Node's exact catchable ReferenceError
      * (exprs.ts's varRef guard). Scalars then peek the one-element
@@ -664,6 +729,42 @@ export declare class LlEmitter {
      * rebound during a call; its independent payload owner keeps it alive.
      * Other writable bindings need an owned snapshot. */
     canBorrowCallArgument(value: IrExpr): boolean;
+    /** A plain-pointer read of a construction-only field outside any
+     * constructor (ImmutableFields). */
+    private immutableRead;
+    /** A projection read whose locations nothing writes while a borrowed
+     * read of it is in use (ReferenceWrites), given the writes of that
+     * extent. The root binding itself must stay alive across it too, which
+     * its own location (`l:`, `g:`, `bx`) covers. */
+    unwrittenRead(e: IrExpr, writes: Writes): boolean;
+    /** A stable binding initialized by a projection can borrow it when the
+     * rest of its block (its whole lifetime) writes none of the projection's
+     * locations: the source edge then keeps the value alive, and uses that
+     * escape still retain their own copies. */
+    private unwrittenAlias;
+    /** An optional element read into a projection-only local can borrow the
+     * element when the rest of the block writes no array element and none of
+     * the locations keeping the array alive (which must itself be read
+     * without a frame owner). */
+    private unwrittenLocalArrayRead;
+    /** An optional element read passed to a projection-only parameter can
+     * borrow the element when the callee and later arguments (`writes`)
+     * write no array element and nothing keeping the array alive. */
+    unwrittenCallArrayRead(read: LocalArrayRead, writes: Writes): boolean;
+    /** `return x` of a local whose slot is an owned scope entry of the same
+     * type: the return can take over the local's reference. */
+    private movableReturn;
+    /** A walk host for a body that may write the heap: each walk must read
+     * only locations the whole body (with its callees) never writes;
+     * rebinding the walk locals themselves releases nothing. */
+    private unwrittenWalkHost;
+    /** emitReadReceiver yields a plain pointer for `e` that no statement
+     * frame owns, so it can outlive the statement (walk-borrows' walks, from
+     * any unboxed plain-pointer binding, plus element reads). */
+    private unownedWalk;
+    /** Every location a borrowed-return callee's walks can read (its body's
+     * field, record and element reads, through nested borrowed returns). */
+    private borrowedReturnKeys;
     private emitStmts;
     /** Emits a block in its own lexical scope (refcounted locals released at
      * end). `setup` runs after the
@@ -766,6 +867,9 @@ export declare class LlEmitter {
     private publishedNamesSym;
     /** The class-name table the hierarchy field guards index by preorder. */
     private publishedClassNamesDefs;
+    /** The frozen-object guard of a class field store, unless the store
+     * provably targets a still-private `this` (PublishedTypes.privateStores). */
+    private emitStoreGuard;
     /** The frozen-object guard of a class field or record field store:
      * Node's "Cannot assign to read only property" TypeError when the target
      * is published. `className` null means a record (`#<Object>`). */