@scriptc/compiler 0.4.1 → 0.4.2

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

@@ -1,6 +1,7 @@
 import { JsIcSites } from "../../ir/js-ic.js";
 import { type ArraySearchKind } from "./array-search.js";
 import type { IrBytesElem, IrExpr, IrFfiCallbackParam, IrFfiImport, IrFunction, IrGlobal, IrLocal, IrModule, IrRecordShape, IrStmt, IrType, IrUnionDef, SrcLoc } from "../../ir/ir.js";
+import { type RuntimeFeatures } from "../../ir/runtime-features.js";
 import { type DenseArrayLoop } from "./dense-array-loops.js";
 import { findInitializedByteLoopBindings } from "./byte-windows.js";
 import { matchBytesLoopVersion } from "./bytes-loop-versions.js";
@@ -98,7 +99,18 @@ export interface LlvmTargetOptions {
     /** Translated WebAssembly memories check bounds explicitly instead of
      * relying on guard pages (wasm-modules.ts wasmBoundsChecks). */
     wasmBoundsChecks?: boolean;
+    /** The executable can reserve its program-lifetime region below 32 GiB
+     * (lowRegionTarget): fields that refer to compact class instances then
+     * store the instance's address over 8 in 32 bits (classes.ts
+     * compactRefLoadLines). Elsewhere they keep 8-byte pointers. */
+    lowRegion?: boolean;
 }
+/** LlvmTargetOptions.lowRegion for an executable: Linux targets without
+ * sanitizers, whose address space below 32 GiB is free (ASan keeps its
+ * shadow memory there; other systems map their own images and libraries
+ * there). `platform` is a target platform (`linux`, `darwin`, `win32`,
+ * `wasi`). */
+export declare function lowRegionTarget(platform: string, sanitize: boolean): boolean;
 export declare function emitLlvmModule(input: IrModule, options?: LlvmTargetOptions): string;
 /** Keep large translation units below the host's single-string limit. */
 export declare function emitLlvmModuleSource(input: IrModule, options?: LlvmTargetOptions): string | readonly string[];
@@ -207,6 +219,13 @@ export declare class LlEmitter {
     integerArrayBindings: Set<string>;
     readonly fieldAliasTags: Map<string, number>;
     readonly fieldPointerTags: Map<string, number>;
+    /** The field pointers (classFieldPtr) of this function whose fields hold
+     * 32-bit references to compact class instances (LlClassMeta.compressed):
+     * loadField/loadRef decode them and storeField/storeRef encode them. */
+    readonly compressedFieldPtrs: Set<string>;
+    /** Whether a class has compressed fields: main reserves the region before
+     * compiled code runs (scr_plr_init). */
+    usesCompactRefs: boolean;
     /** Native class fields with different property names cannot occupy the
      * same slot of one object. Inherited views of the same property share a
      * tag. Array storage has its own disjoint categories; untagged runtime
@@ -370,6 +389,12 @@ export declare class LlEmitter {
     readonly callLifetimes: CallLifetimes;
     readonly constantCallbacks: Map<string, Map<string, string>>;
     currentConstantCallbacks: ReadonlyMap<string, string>;
+    /** Callback bindings whose closures an enclosing callback loop version
+     * proved to hold their known function: calls take the direct entry with
+     * no fallback (emitCallbackVersionedLoop). */
+    knownCallbacks: Set<string>;
+    readonly callbackVersioning: Set<IrStmt>;
+    callbackVersionsEnabled: boolean;
     readonly stackCallbacks: StackCallbacks;
     readonly receiverReaders: AmbientReceiverReaders;
     readonly stackCaptures: StackCaptures;
@@ -451,9 +476,15 @@ export declare class LlEmitter {
     /** Fiberless async functions a stackless coroutine body awaits directly;
      * each gets an inline await entry (emitCoroInlineAwait). */
     readonly inlineAwaitCallees: Set<string>;
+    /** Stackless async functions some coroutine body awaits directly: each
+     * gets a direct spawn entry (emitCoroDirectAwait). */
+    readonly directAwaitCallees: Set<string>;
     /** The async functions whose bodies never suspend and that a direct
      * await may enter in place (selectStacklessAsync). */
     private inlineAwaitable;
+    /** Locals whose array literal emitStmts left for the `await Promise.all`
+     * that reads them (deferredPromiseAllLocal). */
+    private readonly deferredPromiseAllEntries;
     /** The promise a `return` emitted past its finally regions already
      * produced for its adopting await (borrowed from the return's parked
      * slot); that await takes it instead of evaluating its operand. */
@@ -465,7 +496,10 @@ export declare class LlEmitter {
     /** The program calls mock.timers members (moduleUsesMockTimers): timer
      * calls emit scr_test.c's mock-aware entry points. */
     readonly mockTimers: boolean;
-    private schedulesInContextValue;
+    private runtimeFeaturesValue;
+    /** The module's runtime features (moduleRuntimeFeatures), found with one
+     * walk of the module the first time any of them is read. */
+    get runtimeFeatures(): RuntimeFeatures;
     /** Whether timer and tick scheduling goes through the *_als entry
      * points (RuntimeFeatures asyncContext). */
     get schedulesInContext(): boolean;
@@ -483,7 +517,6 @@ export declare class LlEmitter {
     /** Identity-preserving static→dyn capsules for program classes and Web
      * APIs whose values remain directly observable. */
     readonly liveDynRefAdapters: Map<string, LlStreamTypedRefAdapter>;
-    private dynBuiltinStreamUse;
     /** See moduleUsesDynBuiltinStream. */
     get usesDynBuiltinStream(): boolean;
     /** Runtime-arm dispatchers for live union values. */
@@ -626,6 +659,19 @@ export declare class LlEmitter {
             max: number;
         };
     }>;
+    /** Constant number locals whose latest emitted declaration stored an
+     * exact integer beside the double, such as `const j = i * 4` in a
+     * typed-array loop version: an i64 slot and the integer's range. */
+    integerTemps: Map<string, {
+        slot: string;
+        type: "i64";
+        signed: true;
+        range: IntegerRange;
+    }>;
+    /** Integer temps are kept only in optimized synchronous functions: an
+     * async or generator body resumes with its locals in its frame, which
+     * an entry alloca is not part of. */
+    integerTempsEnabled: boolean;
     countedLoopsEnabled: boolean;
     /** Speculative integer loops (speculative-integers.ts) run in this function. */
     speculativeLoopsEnabled: boolean;
@@ -636,12 +682,23 @@ export declare class LlEmitter {
         resume: Map<IrStmt, string>;
         /** Globals whose double is written back only when the copy is left. */
         deferred: Set<string>;
+        /** The loop site's count of bailing entries in a row (a global), and
+         * whether this entry completed a speculated write (a slot). A proven
+         * integer loop has neither. */
+        bails?: string;
+        ran?: string;
     } | null;
+    /** Speculative loop sites numbered so far in the module. */
+    speculativeLoopSites: number;
     /** The ordinary copy being emitted: resume labels still to place. */
     speculationResume: Map<IrStmt, {
         label: string;
         placed: boolean;
     }> | null;
+    /** Run once at the top of the next loop copy's header
+     * (`enterLoopHeader`): records the ordinary copy's header, or sends the
+     * third copy's header there. */
+    speculationHeader: ((header: string) => void) | null;
     /** The function being emitted, for speculative globals. */
     speculativeFunction: string;
     /** Every function that writes each number global (computed on demand). */
@@ -673,6 +730,9 @@ export declare class LlEmitter {
      * guard already passed. */
     readonly provenCountedGuards: Set<IrStmt>;
     bytesBounds: ReadonlySet<IrExpr | IrStmt>;
+    /** Worker programs: typed-array accesses whose views an enclosing version
+     * guard proved thread-owned. */
+    bytesOwned: ReadonlySet<IrExpr | IrStmt>;
     integerViews: Map<string, string>;
     /** Module globals the current function owns outright (initializer
      * bindings): their function-local slot, which stands in for the global. */
@@ -808,10 +868,19 @@ export declare class LlEmitter {
      * fiberless, and module evaluation bodies and `dyn` results keep fibers
      * as they do there. The runtime traps if a stackless body ever parks. */
     selectStacklessAsync(fnDefs: string[]): void;
+    /** Whether a fiberless body running on its caller's stack needs the
+     * frame scr_async_inline_enter/exit keep: it isolates the Error.stack
+     * frame chain, which only stack-observing programs push, as a fresh fiber
+     * would. Other programs run the body with a plain call. The body runs in
+     * its caller's AsyncLocalStorage context either way, as Node runs an async
+     * body up to its first await. The frame also counts the bodies running on
+     * a fiber's stack for the runtime's trap on a fiberless body that
+     * suspends. */
+    get fiberlessFrames(): boolean;
     /** The spawn wrapper of a fiberless async function: runs the body on the
-     * caller's stack between scr_async_inline_enter/leave and settles the
-     * fresh promise from its outcome — the fiber trampoline's epilogue,
-     * without the fiber. */
+     * caller's stack (between scr_async_inline_enter/leave when
+     * fiberlessFrames) and settles a fresh promise from its outcome — the
+     * fiber trampoline's epilogue, without the fiber. */
     emitFiberlessAsyncSpawn(fn: IrFunction, spawnParams: string[]): string[];
     /** Whether `await f(...)` may enter f through its await-call entry. The
      * entry's result is the awaited value of f's own body type; direct calls
@@ -821,10 +890,23 @@ export declare class LlEmitter {
      * place (emitCoroInlineAwait): f never suspends, and its direct call is
      * one an await-call entry could take. */
     inlineAwaitEligible(fnName: string): boolean;
+    /** Whether a stackless coroutine body's `await f(...)` may await f's
+     * fiber record instead of its promise (emitCoroDirectAwait): f is a
+     * stackless async function whose direct call an await-call entry could
+     * take. The await consumes the promise, so nothing else can observe it.
+     * Worker programs keep the promise for their stop checkpoint. */
+    directAwaitEligible(fnName: string): boolean;
+    /** A stackless coroutine body's `await f(...)` of a stackless f, without
+     * f's promise object: f's prefix runs as the spawn of a fiber record that
+     * keeps the promise inside. A body still running wakes this coroutine
+     * when it finishes, where its promise's settlement would wake its one
+     * waiter; a finished one takes the settled await's turn. The result (or
+     * the rejection, re-thrown) comes out of the record, which goes. */
+    emitCoroDirectAwait(call: ExprOf<"call">, type: IrType): LlValue;
     /** The inline await entry of a fiberless async function (`sc_ai_*`): its
-     * body on the caller's stack between scr_async_inline_enter/exit, as in
-     * its spawn wrapper, returning the result and leaving a throw pending for
-     * the awaiting coroutine (emitCoroInlineAwait). */
+     * body on the caller's stack (between scr_async_inline_enter/exit when
+     * fiberlessFrames), as in its spawn wrapper, returning the result and
+     * leaving a throw pending for the awaiting coroutine (emitCoroInlineAwait). */
     emitAsyncInlineAwaitCall(fn: IrFunction): string[];
     /** A stackless coroutine body's `await f(...)` of a fiberless f, the
      * await-call entry's turns without its promise: the body runs in place,
@@ -833,6 +915,32 @@ export declare class LlEmitter {
      * the spawn wrapper's promise would. An adopting await (`return f(...)`)
      * first takes the adoption's then-job turn either way. */
     emitCoroInlineAwait(call: ExprOf<"call">, adopt: boolean): LlValue;
+    /** The entries of `Promise.all(arg)` that a stackless coroutine body's
+     * await may run in place (emitCoroInlinePromiseAll): `arg` is a non-empty
+     * array literal, or the local whose declaration emitStmts deferred to this
+     * await (deferredPromiseAllEntries), whose every entry is a call to a
+     * never-suspending async function, and the result is an array. Null
+     * otherwise. Consumes a deferred local's entries. */
+    inlinePromiseAllEntries(all: ExprOf<"intrinsic">): ExprOf<"arrayLit"> | null;
+    /** Whether every entry of `entries` is a call an await could run in place
+     * (inlineAwaitEligible) that yields its promise's inner type. */
+    private promiseAllInlineable;
+    /** Whether `stmts[i]` declares a local holding an array literal that only
+     * `stmts[i + 1]` reads, as the operand of `await Promise.all(local)` that
+     * runs first in that statement and may run its entries in place. Nothing
+     * runs between the literal and the await, so the await evaluates the
+     * literal itself (inlinePromiseAllEntries). Debug builds keep the local. */
+    deferredPromiseAllLocal(stmts: readonly IrStmt[], i: number): ExprOf<"arrayLit"> | null;
+    /** A stackless coroutine body's `await Promise.all([f(...), ...])` of
+     * never-suspending calls, with Promise.all's turns and without its
+     * promises: the entries run in place in order and their values fill the
+     * result array. Promise.all queues one reaction job per entry, back to
+     * back, and the last of them settles the result, whose await then takes a
+     * turn: here one turn stands for the entries' jobs and a second for the
+     * await. A throwing entry becomes the rejection the await re-throws from
+     * its turn; the remaining entries still run, and later throws are handled
+     * rejections, as Promise.all's subscriptions make them. */
+    emitCoroInlinePromiseAll(entries: ExprOf<"arrayLit">, type: IrType): LlValue;
     emitAsyncAwaitCall(fn: IrFunction, argPackLines: string[] | null, adopt?: boolean): string[];
     emitAsyncScaffolding(): string[];
     /** Whether `fn`'s body is emitted as an LLVM switched coroutine: every
@@ -975,11 +1083,13 @@ export declare class LlEmitter {
      * 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). `poll` marks a worker termination poll
-     * (function entry or loop budget), whose test must stay ordered. */
+     * (function entry or loop budget), whose test must stay ordered. A
+     * `guard` (an i1) limits the test to the paths where it is true: false
+     * where the joined call could not have left anything pending. */
     emitPendingCheck(passThrough?: {
         name: string;
         type: IrType;
-    }, poll?: boolean): void;
+    }, poll?: boolean, guard?: string): 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
@@ -1068,11 +1178,19 @@ export declare class LlEmitter {
      * 1 on hierarchy members, then the flattened field list. Runtime error
      * classes GEP through %ScrError (their structs live in the runtime; the
      * def's [name, message, %code, %cause] order matches the layout). */
-    classFieldPtr(objName: string, className: string, field: string): {
+    classFieldPtr(objName: string, className: string, field: string, refs?: "pointer" | "compressed"): {
         ptr: string;
         type: IrType;
         inline: boolean;
+        compressed: boolean;
     };
+    /** Loads the reference a field pointer addresses: a pointer, or the
+     * decoded 32-bit reference of a compressed field (compressedFieldPtrs).
+     * `tagged`: the load carries the field's alias tags. */
+    loadRef(ptr: string, tagged?: boolean): string;
+    /** Stores `value` (a pointer) through a field pointer: as is, or encoded
+     * as the 32-bit reference of a compressed field. */
+    storeRef(ptr: string, value: string): void;
     /** The dynamic class's preorder number (borrowed object; the static class
      * names the struct spelling and where the number is, classPreLines). */
     loadVtPre(objName: string, staticClassName: string): string;
@@ -1139,6 +1257,13 @@ export declare class LlEmitter {
     emitDebugLocal(local: IrLocal, slot: string, arg?: number, captured?: boolean): void;
     /** Loads a boxed binding's box pointer out of its slot. */
     loadBox(slot: string): string;
+    /** The function a call through `callee` is known to reach (a literal
+     * closure, or a binding the constant-callback census resolves) and the
+     * entry it calls directly. Async and generator functions stay indirect. */
+    knownCallbackTarget(callee: IrExpr): {
+        known: IrFunction;
+        direct: string;
+    } | undefined;
     /** The payload slot of a capture box (ScrBox.slot, field 5). */
     boxSlot(box: string): string;
     boxGet(box: string, t: IrType): string;
@@ -1454,8 +1579,9 @@ export declare class LlEmitter {
     private emitPublish;
     /** Branches on "`obj` is published" (rc == SIZE_MAX, or a count of
      * UINT32_MAX in the low half for `count` i32: classes.ts
-     * LlClassMeta.idInRc); leaves the builder in the cold block and answers
-     * the continuation label. */
+     * LlClassMeta.idInRc, or the top bit of a compact header word for
+     * "compact": classes.ts COMPACT_PUBLISHED); leaves the builder in the cold
+     * block and answers the continuation label. */
     private emitPublishedTest;
     private publishedNamesSym;
     /** The class-name table the hierarchy field guards index by preorder. */
@@ -1630,7 +1756,7 @@ export declare class LlEmitter {
     emitBytesIndex(receiver: string, index: LlValue, expr?: IrExpr, inBounds?: boolean): string;
     emitBytesData(receiver: string): string;
     emitBytesLength(elem: IrBytesElem, receiver: string, bytes: boolean): LlValue;
-    emitBytesGet(elem: IrBytesElem, receiver: string, index: LlValue, expr?: IrExpr, inBounds?: boolean, invalidNaN?: boolean): LlValue;
+    emitBytesGet(elem: IrBytesElem, receiver: string, index: LlValue, expr?: IrExpr, inBounds?: boolean, invalidNaN?: boolean, owned?: boolean): LlValue;
     emitToUint32(value: string, expr?: IrExpr, uint32?: string): string;
     /** Stores a number into its int32-stored local, when it is one. The
      * value is proven to be in the local's range, so its low 32 bits are the
@@ -1641,7 +1767,7 @@ export declare class LlEmitter {
      * as its incoming double, which is the same number. */
     int32LocalValue(localId: string, bits: string, type: IrType): LlValue;
     storeIntegerView(localId: string, value: LlValue, expr?: IrExpr): void;
-    emitBytesSet(elem: IrBytesElem, receiver: string, index: LlValue, value: LlValue, indexExpr?: IrExpr, expr?: IrExpr, inBounds?: boolean): void;
+    emitBytesSet(elem: IrBytesElem, receiver: string, index: LlValue, value: LlValue, indexExpr?: IrExpr, expr?: IrExpr, inBounds?: boolean, owned?: boolean): void;
     emitBytesIntrinsic(e: IrExpr & {
         kind: "bytesIntrinsic";
     }): LlValue;