@geastack/compiler 1.0.15

package/dist/targets/cpp/emit-callable.d.ts

@@ -0,0 +1,230 @@
+import type { AllocateCallableOperation, AllocateConstructorOperation, BindCallableOperation, CallOperation, ConstructOperation, IrOperand, SuperInitializeOperation } from '../../ir/model.js';
+import type { FunctionId } from '../../identity/ids.js';
+import type { CallableAbi, Representation } from '../../representation/model.js';
+import { type CaptureAdmission, type EmitContext } from './emit-context.js';
+/** `Function.prototype.bind` preserves the native call ABI and captures only evaluated prefix values. */
+export declare const emitBindCallable: (ctx: EmitContext, lines: string[], operation: BindCallableOperation) => void;
+/**
+ * A class instance written where a structurally-compatible DECLARED SHAPE is
+ * the slot -- the interface view TypeScript's own assignability already
+ * granted, materialized.
+ *
+ * hono's `createResponseInstance(_res.body, _res)` (context.ts) hands a
+ * `Response` INSTANCE to a parameter declared `ResponseInit`. The checker
+ * accepts it structurally: `ResponseInit`'s three optional members --
+ * `status`, `statusText`, `headers` -- are all present on the class. C++ has
+ * no such rule. `gea::Ref<gea_class_...>` and `gea::Ref<gea_record_...>` are
+ * unrelated types, `derivesFrom` above answers only the nominal hierarchy the
+ * program actually wrote, and `convertedValueText` has no way to reach a
+ * class's members: a `class-ref` carries a declaration and a shape id, never a
+ * field list. This is the one place both layouts are in hand.
+ *
+ * The rebuild is `recastedRecordText`'s (emit-narrowing.ts), one carrier kind
+ * further out: read each of the TARGET's fields off the source and construct
+ * the target's struct. Both field lists come from `recordFieldsOfShape`, the
+ * same authority `records.ts` builds every struct body from, so the members
+ * read here are exactly the members that exist.
+ *
+ * What this is NOT is an alias. The result is a fresh record holding a
+ * snapshot of the instance's fields, so a callee that ASSIGNS one of them
+ * writes to the copy and the instance never sees it -- the same limit the
+ * record-to-record recast already carries, one carrier kind wider. That makes
+ * this sound for a slot the declaration shapes as a read-only bag (an options
+ * record, which is what every such interface in practice is) and wrong for one
+ * declared to be written through. A field whose own carrier is refcounted --
+ * `Response.headers`, a `Headers` instance -- still aliases, because the copy
+ * copies the reference.
+ *
+ * Fail-closed on everything it cannot account for: a target with accessors or
+ * a dynamic-property sidecar has members this aggregate cannot fill, a
+ * host-named struct is the engine's own type with a layout this compiler did
+ * not choose, and a target field with no source member of its own is a real
+ * hole -- unless the field is optional, which is the declaration's own word
+ * that absence is a value it accepts.
+ */
+/** The lambda's own names, kept out of every body-local namespace a view can be spliced into. */
+/**
+ * One argument in the carrier the frame it is being written into declares.
+ *
+ * An argument arrives in the carrier of the expression that produced it, which
+ * is not always the slot's: `setSupportedOrientations('landscape')` hands a
+ * `std::string` to a parameter declared `OrientationLock | OrientationLock[]`,
+ * a real `gea::TaggedUnion`. Writing it through unconverted is a frame
+ * mismatch, and C++ rejects it -- correctly -- at the call.
+ *
+ * This is deliberately in the emitter and not in the lowering. Only three of
+ * this file's renderings build a frame at all: a host member and a
+ * String/Array.prototype method are both spelled through a text template that
+ * never sees the declared convention (`emit-host-invoke.ts`,
+ * `emit-prototype-invoke.ts`), so an argument reaching one of those must stay
+ * exactly as its own carrier spells it -- `substring`'s optional `end` is a C++
+ * OVERLOAD there, not a `gea::Optional<double>` parameter. Which rendering a
+ * call gets is decided here, once, a few lines above; a lowering that decided
+ * it a second time would be a second authority over the same question.
+ *
+ * A slot the convention does not declare is left alone: ECMAScript lets a call
+ * pass more arguments than a signature names, and an argument past the last
+ * slot has no declared carrier to be reconciled against. So is the rest slot,
+ * which `ir/lower-operands.ts`'s `packRestArguments` has already built in
+ * exactly the carrier the convention states.
+ */
+export declare const alignedText: (ctx: EmitContext, slot: Representation | undefined, argument: IrOperand, what?: string) => string;
+export declare const receiverBoundCallableText: (ctx: EmitContext, operand: IrOperand, target: Representation, text: string) => string | null;
+/**
+ * The receiver occupies the frame's first formal, and reconciles against the
+ * slot the convention declares for it exactly as any other argument does.
+ *
+ * One extra obligation, and only for a refcounted receiver a body takes BY
+ * REFERENCE (`cppRefcountedReceiver`, translation-unit.ts): the argument must
+ * be something that survives the call. A local, a formal and a temporary all
+ * do -- a `const&` parameter extends a temporary's lifetime past the call that
+ * made it -- but a WITHHELD cell read renders as the cell's own storage, and a
+ * callee that assigns that cell drops the last count and destroys the object
+ * its own receiver names. So a withheld read is given its temporary back: the
+ * same copy passing by value would have made, in the one shape where the
+ * reference has nothing behind it.
+ */
+export declare const receiverArgumentText: (ctx: EmitContext, abi: CallableAbi, receiver: IrOperand) => string;
+export declare const emitCall: (ctx: EmitContext, lines: string[], operation: CallOperation) => void;
+/**
+ * `super(...)`: the base's initialization against the object under
+ * construction, then this class's own field initializers.
+ *
+ * Both halves are the language's, in the language's order. `super()` runs the
+ * base chain -- its field initializers and its constructor body -- against the
+ * receiver the derived construction already allocated, which is why it calls
+ * the base's *initialize* half rather than its construct: constructing would
+ * allocate a second object of the base's own type and throw the derived one
+ * away. Immediately after it returns, and before the next statement of this
+ * constructor, the derived class's own field initializers run; that is why they
+ * are here and not in `constructDefinitionsOf`, which cannot see where in the
+ * body they belong.
+ *
+ * Which class this is, is read from the projection rather than from the frame:
+ * the body's own receiver carrier names the class the *receiver* has, which for
+ * a derived constructor is the derived class either way, but only
+ * `ClassLayout.constructor` states that this body is that class's constructor
+ * at all -- a `super()` reached from a nested arrow is a different frame and is
+ * refused here rather than silently initializing the enclosing class.
+ */
+export declare const emitSuperInitialize: (ctx: EmitContext, lines: string[], operation: SuperInitializeOperation) => void;
+/**
+ * Declares a capture's box before the environment that captures it is built
+ * when no earlier binding write allocated that box.
+ *
+ * Most boxed slots already exist because the owning frame's first
+ * `binding-write` allocates them before a closure is created. Two ordinary
+ * language shapes do not: a closure can precede the first write to a
+ * declaration (`let cached; const get = () => cached; cached = value`), and a
+ * closure can hold ITSELF (`CaptureSlot.boxed` set because
+ * `closureInitialized.get(declaration) === owner`, `captures.ts`):
+ * `const loop = (ts) => { ...; requestAnimationFrame(loop) }` allocates the
+ * closure before the initializing write. In both cases the environment needs
+ * a handle to the cell immediately. So this declares an empty box exactly
+ * once, ahead of the environment build, and marks it declared; a later
+ * initializing write that follows (`emitBindingWrite`) then sees it already
+ * declared and only fills it in, exactly as any later reassignment would.
+ */
+/**
+ * The packed environment one capturing body is entered with, built in the
+ * frame that supplies its captures.
+ *
+ * `gea::packEnvironment` (gea_runtime.h) decides where the captured state
+ * physically goes, and the body's own `unpackEnvironment` reads that same
+ * decision from the same predicate, so the two cannot disagree. Where it
+ * fits, the state IS the pointer the carrier holds and nothing is allocated;
+ * where it does not, the struct is a `gea::Ref` block every holder counts on
+ * -- which is why there is no "who deletes it" question here: the last holder
+ * does.
+ *
+ * Two callers, and they are the two ways a body can be reached with state it
+ * did not declare: a `CallableObject` carries it for an allocated closure,
+ * and a record member carries it for a capturing ACCESSOR
+ * (`emit-allocation.ts`), which has no carrier of its own.
+ */
+export declare const packedEnvironmentText: (ctx: EmitContext, lines: string[], functionId: FunctionId, admission: CaptureAdmission) => string;
+/**
+ * `CallableObject{invoke, environment}` for one function-object allocation.
+ *
+ * `operation.captures` is never consulted: nothing publishes it, so it is not
+ * a source of truth for what this closure reads from an enclosing frame.
+ * `targets/cpp/captures.ts`'s whole-program `CaptureIndex` is. Each captured
+ * cell is read through `bindingReference` in *this* (allocating) context,
+ * which owns every declaration the closure captures by construction, so the
+ * ordinary branch of `bindingReference` names it correctly with no special
+ * casing. A captured receiver reads `cppReceiverName` the same way: this
+ * body's own `gea_this` formal exists whenever it has a receiver at all,
+ * whether real or itself captured (`emit-context.ts`'s `effectiveAbiOf`).
+ *
+ * A boxed slot's field copy needs no special casing here either, despite
+ * carrying a `std::shared_ptr` rather than the declaration's own value type:
+ * `bindingReference` already names the box's OWN storage for a boxed
+ * declaration (never its dereferenced pointee -- that is
+ * `emit-bindings.ts`'s `cellValueText`, used only where a value, not a
+ * handle, is wanted), so copying `.name` verbatim into the new environment
+ * struct copies the pointer, which is exactly the aliasing this closure's
+ * capture is supposed to establish.
+ */
+export declare const emitAllocateCallable: (ctx: EmitContext, lines: string[], operation: AllocateCallableOperation) => void;
+/**
+ * `new Map()` / `new Set()` / `new WeakMap()` / `new WeakSet()`, and
+ * `new Set(array)`.
+ *
+ * The third member of the `emitTypedArrayConstruct`/`emitArrayConstruct`
+ * family above, here for exactly the same structural reason: these four
+ * constructors' checker overload sets have no single physical frame. `new
+ * Map()`, `new Map(entries: readonly (readonly [K, V])[] | null)` and `new
+ * Map(iterable: Iterable<readonly [K, V]>)` are three different parameter-0
+ * shapes, so `representation/host-abi.ts`'s `widestSubsumingAbi` correctly
+ * refuses to join them and `derive.ts` leaves `.construct` null. This reads
+ * the construction's own already-resolved result carrier and argument
+ * representation instead.
+ *
+ * Only the zero-argument form, plus `new Set(T[])`, is rendered. Every other
+ * seeding form refuses by name:
+ *
+ * - a Map/WeakMap seeded from entries needs each element to be a `[K, V]`
+ *   PAIR, and this compiler carries a tuple as an ordinary record of "0"/"1"
+ *   fields (`derive.ts`'s `deriveTuple`). Reading two struct members back out
+ *   as a key and a value is a real lowering, not a spelling, and guessing at
+ *   it would be the kind of improvisation `emitArrayConstruct` already
+ *   declines for `new Array(...items)`;
+ * - a Set seeded from any iterable that is not an Array needs the dynamic
+ *   `@@iterator` protocol this backend does not lower at all
+ *   (`emit-iterator.ts`);
+ * - `new WeakSet(array)` is refused with the others rather than folded in with
+ *   `new Set(array)`: it is genuinely rare, and admitting it would mean
+ *   claiming the weak-key precondition holds for every element of an array
+ *   whose own element carrier this function would have to re-check.
+ */
+/**
+ * The four ambient constructor PROTOCOL NAMES this renderer is written for --
+ * named here, once, rather than being re-typed as a fifth copy by anything
+ * that needs to know which protocols `emitKeyedCollectionConstruct` answers
+ * for. The dispatch above is structural (`result.kind === 'keyed-collection'`),
+ * never by this name, so this table is not read by the renderer itself: it is
+ * the renderer's own restatement of the four names its comment already
+ * documents, exported for `host/native-protocols.ts` to derive a
+ * native-boundary claim from, since no host-member-table row names any of
+ * them the way most other protocols are named.
+ */
+export declare const cppKeyedCollectionConstructorProtocols: readonly string[];
+/**
+ * `new C(...)`: the construction goes through the constructor carrier's own
+ * construct pointer, exactly as a call goes through a callable's invoke
+ * pointer. `newTarget` is not consulted -- a derived construction needs the
+ * new-target to reach the field initializers of the class that was actually
+ * newed, and nothing here transports it -- so a construction whose new-target
+ * is not its own callee is refused rather than silently treated as ordinary.
+ */
+export declare const emitConstruct: (ctx: EmitContext, lines: string[], operation: ConstructOperation) => void;
+/**
+ * Class evaluation allocates a native prototype owner, even when its methods
+ * capture nothing. Constructor copies share it, while another evaluation of
+ * the same declaration gets a new owner. The evaluated superclass supplies
+ * the parent owner; looking it up by declaration would conflate factories.
+ *
+ * This state carries method identities only. Constructor body/field capture
+ * transport remains subject to the existing fail-closed admission below.
+ */
+export declare const emitAllocateConstructor: (ctx: EmitContext, lines: string[], operation: AllocateConstructorOperation) => void;