@swf2es/runtime 0.0.0-stage → 0.1.0

package/src/avm2/traits.ts

@@ -0,0 +1,584 @@
+// The layout model: an object's traits, its bindings and slots as the
+// module's descriptor gives them, and the references by which a module
+// names a class or a Vector type before it exists.
+
+import type {
+  AsObject,
+  ClassDesc,
+  Metadata,
+  Signature,
+  SlotFill,
+  TraitsDesc,
+  TypeRef,
+  Value,
+} from "./descriptors.js";
+import type { Domain } from "./domain.js";
+import { DynamicProperties } from "./dynamic-properties.js";
+import type { ClassHook, IndexHook, PropertyHook } from "./hooks.js";
+import type { Multiname, Namespace } from "./names.js";
+import { invalidate } from "./property-cache.js";
+
+// Binding kinds, as the compiler encodes them: kind | id << 3.
+export const BIND_Method = 1;
+export const BIND_Var = 2;
+export const BIND_Const = 3;
+export const BIND_Get = 5;
+export const BIND_Set = 6;
+export const BIND_GetSet = 7;
+
+/**
+ * Set class `cls`'s own static variable `name`, in whatever namespace, to
+ * `value`: for a class hook setting what the VM keeps there, as a private
+ * static the class reads.
+ */
+export function setStaticVar(cls: AsObject, name: string, value: Value): void {
+  for (const [, , n, b] of (cls.$desc as ClassDesc).static.bindings) {
+    if (n === name && (b & 7) === BIND_Var) {
+      cls[`$${b >> 3}`] = value;
+    }
+  }
+}
+
+/**
+ * The field that holds class `cls`'s own instance variable `name`, in
+ * whatever namespace, or null if it declares none: for a player that reads
+ * or writes a private field its playerglobal's AS3 keeps.
+ */
+export function instanceVarField(cls: AsObject, name: string): string | null {
+  // A class no module describes, as a host's stand-in, declares none.
+  const desc = cls?.$desc as ClassDesc | undefined;
+  for (const [, , n, b] of desc?.instance.bindings ?? []) {
+    if (n === name && (b & 7) === BIND_Var) {
+      return `$${b >> 3}`;
+    }
+  }
+
+  return null;
+}
+
+/** The builtins besides Object whose type tests isInstanceOf answers from the value, not its traits. */
+export const VALUE_TESTS = new Set(["float", "Number", "int", "uint", "String", "Boolean"]);
+
+/** Trait kinds as the ABC has them, which the descriptors' metadata is keyed by. */
+const TRAIT_Slot = 0;
+const TRAIT_Getter = 2;
+const TRAIT_Setter = 3;
+const TRAIT_Class = 4;
+const TRAIT_Const = 6;
+
+interface Binding {
+  ns: Namespace;
+  version: number;
+  value: number;
+}
+
+/**
+ * The traits of an object: its own bindings by local name, and its own
+ * slots' types and initial values; lookups continue in the base's, as
+ * avmplus' do, so a base described after its subclass was made (Object,
+ * Class and Function, during the bootstrap) is still seen.
+ */
+export class Traits {
+  bindings = new Map<string, Binding[]>();
+  slotTypes: TypeRef[] = [];
+  own: [string, Value][] = [];
+  /** Every slot field and its initial value, the base's first, once an instance is made. */
+  private allDefaults: [string, Value][] | null = null;
+  /** What the module compiled to set the slots by name, if it did (TraitsDesc.fill). */
+  private fill: SlotFill | null = null;
+  /** Once an instance is made: the fill these traits' objects use, if any, and its values by slot. */
+  private filler: SlotFill | null = null;
+  private slotValues: Value[] = [];
+  /** The JavaScript prototype of objects with these traits. */
+  proto: AsObject;
+  /** The object its methods go into now (methodHome): its prototype, or one chained below it. */
+  private home: AsObject | null = null;
+  /** How many properties `home` has taken, a few counted in advance for the prototype's own. */
+  private homeSize = HOME_SLACK;
+  /** Whether it declares a slot its objects keep in their array `$S` (SPILL_SLOTS). */
+  private spills = false;
+  /** The class whose instances these are the traits of, once it exists. */
+  cls: AsObject | null = null;
+  interfaces = new Set<Traits>();
+  dynamic = false;
+  /** Whether it is a script's global object's, as System.isGlobal asks. */
+  isGlobal = false;
+  /**
+   * Whether a dynamic class's instances refuse any name but their own and
+   * an index, getting it or setting it, as a Vector's do: they delete one,
+   * or have one in, as any dynamic object, which it never has.
+   */
+  refusesNames = false;
+  /** How to allocate an instance, for classes whose instances hold native state. */
+  create: ((traits: Traits) => AsObject) | null;
+  /** The class's own hook, a builtin's or a player's; not inherited, but a specialized Vector has its base's. */
+  hooks: ClassHook | null = null;
+  /** How its instances resolve the names it does not bind, if not as dynamic properties. */
+  properties: PropertyHook | null = null;
+  /** Its own slots with [Transient] metadata, if any. */
+  transientSlots: Set<number> | null = null;
+  /** Its own accessors with metadata, if any, by dispatch id: whether any of it is [Transient]. */
+  accessorMetadata: Map<number, boolean> | null = null;
+  /** Its own methods' signatures, by dispatch id, for describeType. */
+  signatures = new Map<number, Signature>();
+  /** Its own slots' and methods' metadata, by slot id and by dispatch id, for describeType. */
+  slotMetadata: Map<number, Metadata[]> | null = null;
+  methodMetadata: Map<number, Metadata[]> | null = null;
+  /** The class's: whether it is final or an interface, its constructor's parameters, its own metadata. */
+  final = false;
+  isInterface = false;
+  /** The ABC that defines the class, whether it is restricted, and whether that makes it one nothing constructs. */
+  abc: object | null = null;
+  restricted = false;
+  uninstantiable = false;
+  ctor: [TypeRef[], number] | null = null;
+  metadata: Metadata[] | null = null;
+  getIndex?: IndexHook["getIndex"];
+  setIndex?: IndexHook["setIndex"];
+  hasIndex?: IndexHook["hasIndex"];
+  index?: IndexHook["index"];
+  /**
+   * Whether a type test against these traits looks at more than an object's
+   * traits, as one against Object, a number type, String or Boolean does,
+   * which takes primitives: those builtins' own, not a class named as one.
+   */
+  testsValues = false;
+  /**
+   * Object.prototype.toString's "[object Name]" for its instances, once
+   * made: the same string each time, whose hash V8 keeps, so that looking
+   * it up, as `in` a Dictionary does for each object key it misses, does
+   * not hash it anew.
+   */
+  objectString: string | null = null;
+  /**
+   * The keys of the methods its instances are called by through each
+   * interface, as Runtime.interfaceKey finds them: by the interface's
+   * traits, an array by the interface's dispatch ids. The last interface
+   * looked up, and its keys, are kept apart, as most receivers are called
+   * through one.
+   */
+  interfaceKeys: Map<Traits, (string | undefined)[]> | null = null;
+  lastInterface: Traits | null = null;
+  lastInterfaceKeys: (string | undefined)[] = [];
+
+  constructor(
+    readonly name: string,
+    readonly base: Traits | null,
+    proto?: AsObject,
+  ) {
+    this.proto = proto ?? Object.create(base ? base.proto : null);
+    this.proto.$traits = this;
+    this.create = base ? base.create : null;
+    this.properties = base ? base.properties : null;
+    this.getIndex = base?.getIndex;
+    this.setIndex = base?.setIndex;
+    this.hasIndex = base?.hasIndex;
+    this.index = base?.index;
+    if (base) {
+      for (const i of base.interfaces) {
+        this.interfaces.add(i);
+      }
+    }
+  }
+
+  /**
+   * The object a method and its entries, `count` properties, go into:
+   * the prototype, till it holds HOME_PROPERTIES, then an object chained
+   * below it, above the base's, and so on. V8 keeps an object of more
+   * than 1020 properties as a dictionary, which hashes every name looked
+   * up in it: a script of thousands of functions, as Crossbridge compiles
+   * C, called each through such a prototype ran five times as slow as
+   * through one that is not. A prototype chain of objects V8 keeps fast
+   * looks a name up as fast as one object.
+   */
+  methodHome(count: number): AsObject {
+    let home = this.home ?? this.proto;
+    if (this.homeSize + count > HOME_PROPERTIES) {
+      // Chained before it takes its methods: V8 keeps an object fast that is a prototype first.
+      const below = Object.create(Object.getPrototypeOf(home));
+      Object.setPrototypeOf(home, below);
+      home = below;
+      this.homeSize = 0;
+    }
+
+    this.home = home;
+    this.homeSize += count;
+    return home;
+  }
+
+  /** Add a traits' own bindings and slots from its descriptor. */
+  describe(desc: TraitsDesc): void {
+    invalidate();
+    for (const [ns, version, name, value] of desc.bindings) {
+      let list = this.bindings.get(name);
+      if (!list) {
+        list = [];
+        this.bindings.set(name, list);
+      }
+
+      list.push({ ns, version, value });
+    }
+
+    for (const [slot, value, type] of desc.defaults) {
+      this.slotTypes[slot] = type;
+      this.own.push([slotKey(slot), value]);
+      if (slot >= SPILL_SLOTS) {
+        this.spills = true;
+        spilledSlot(this.methodHome(1), slot);
+      }
+    }
+
+    for (const [d, , , returnType, params, required] of desc.methods) {
+      this.signatures.set(d, [returnType, params, required]);
+    }
+
+    if (desc.meta) {
+      this.annotate(desc.meta);
+    }
+
+    this.fill = desc.fill ?? null;
+    this.allDefaults = null;
+  }
+
+  /**
+   * Keep the traits' metadata, and what AMF and JSON ask of it: the slots
+   * with [Transient], and for each accessor with metadata whether any of
+   * it is [Transient], since an accessor's metadata hides its base's, as
+   * avmplus' getMethodMetadataPos finds it.
+   */
+  private annotate(meta: [number, number, Metadata[]][]): void {
+    const transient = (entries: Metadata[]) => entries.some(([name]) => name === "Transient");
+    for (const [kind, id, entries] of meta) {
+      if (kind === TRAIT_Slot || kind === TRAIT_Const || kind === TRAIT_Class) {
+        this.slotMetadata ??= new Map();
+        this.slotMetadata.set(id, entries);
+        if (transient(entries)) {
+          this.transientSlots ??= new Set();
+          this.transientSlots.add(id);
+        }
+      } else {
+        this.methodMetadata ??= new Map();
+        this.methodMetadata.set(id, entries);
+        if (kind === TRAIT_Getter || kind === TRAIT_Setter) {
+          this.accessorMetadata ??= new Map();
+          this.accessorMetadata.set(id, transient(entries));
+        }
+      }
+    }
+  }
+
+  /**
+   * Whether the member binding `b` names is [Transient], which AMF and
+   * JSON leave out: a slot, or either accessor of a pair, whose metadata,
+   * found as avmplus' TraitsMetadata finds it, has it.
+   */
+  isTransient(b: number): boolean {
+    const kind = b & 7;
+    const id = b >> 3;
+    if (kind === BIND_Var || kind === BIND_Const) {
+      for (let t: Traits | null = this; t; t = t.base) {
+        if (t.transientSlots?.has(id)) {
+          return true;
+        }
+      }
+
+      return false;
+    }
+
+    return (
+      ((kind === BIND_Get || kind === BIND_GetSet) && this.transientAccessor(id)) ||
+      ((kind === BIND_Set || kind === BIND_GetSet) && this.transientAccessor(id + 1))
+    );
+  }
+
+  /** Whether accessor `id`'s metadata, the nearest traits' that has any, is [Transient]. */
+  private transientAccessor(id: number): boolean {
+    for (let t: Traits | null = this; t; t = t.base) {
+      const transient = t.accessorMetadata?.get(id);
+      if (transient !== undefined) {
+        return transient;
+      }
+    }
+
+    return false;
+  }
+
+  /** Whether it or a base declares a slot kept in the array `$S`. */
+  private spillsAny(): boolean {
+    for (let t: Traits | null = this; t; t = t.base) {
+      if (t.spills) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /** The type of slot `id`, declared here or by a base. */
+  slotType(id: number): TypeRef {
+    for (let t: Traits | null = this; t; t = t.base) {
+      if (id in t.slotTypes) {
+        return t.slotTypes[id];
+      }
+    }
+
+    return null;
+  }
+
+  /** The binding `mn` names, or 0: the first of its namespaces that binds it at its version. */
+  find(mn: Multiname): number {
+    const name = mn.name;
+    if (name === null) {
+      return 0;
+    }
+
+    const namespaces = mn.namespaces;
+    for (let t: Traits | null = this; t; t = t.base) {
+      const list = t.bindings.get(name);
+      if (!list) {
+        continue;
+      }
+
+      // Indexes, not for-of: compiled code looks its names up here.
+      for (let i = 0; i < namespaces.length; i++) {
+        const ns = namespaces[i];
+        for (let k = 0; k < list.length; k++) {
+          const b = list[k];
+          if (b.ns === ns && b.version <= mn.versions[i]) {
+            return b.value;
+          }
+        }
+      }
+    }
+
+    return 0;
+  }
+
+  /** A new object with these traits, its slots at their initial values. */
+  instance(): AsObject {
+    const o = this.create ? this.create(this) : Object.create(this.proto);
+    o.$d = this.dynamic ? new DynamicProperties() : null;
+    if (!this.allDefaults) {
+      this.allDefaults = this.base ? [...this.base.defaultsOf(), ...this.own] : this.own.slice();
+      this.filler = this.fillOf();
+      this.slotValues = this.filler ? valuesBySlot(this.allDefaults) : [];
+    }
+
+    if (this.filler) {
+      this.filler(o, this.slotValues);
+    } else {
+      // Those past SPILL_SLOTS through their accessors, into the array.
+      if (this.spillsAny()) {
+        o.$S = [];
+      }
+
+      // Traits no module compiled a fill for: a catch scope's, or past
+      // FILL_SLOTS, where V8 keeps no object fast anyway.
+      const defaults = this.allDefaults;
+      for (let i = 0; i < defaults.length; i++) {
+        o[defaults[i][0]] = defaults[i][1];
+      }
+    }
+
+    return o;
+  }
+
+  /** The fill for these traits' objects: their module's, or a base's that has all their slots, as a Vector.<T>'s. */
+  private fillOf(): SlotFill | null {
+    if (this.fill || this.own.length) {
+      return this.fill;
+    }
+
+    return this.base ? this.base.fillOf() : null;
+  }
+
+  defaultsOf(): [string, Value][] {
+    return this.allDefaults ?? (this.base ? [...this.base.defaultsOf(), ...this.own] : this.own);
+  }
+
+  /**
+   * Interfaces named by a class made before them, as a script may define a
+   * class before an interface it implements: each gives the interface's
+   * traits once its class exists, or null before. avmplus takes interfaces
+   * from traits, which exist from loading; these are settled when a type
+   * test first needs them.
+   */
+  pendingInterfaces: (() => Traits | null)[] | null = null;
+
+  /** Add the interfaces now made that were pending, here and in the bases. */
+  settleInterfaces(): void {
+    for (let c: Traits | null = this; c; c = c.base) {
+      const pending = c.pendingInterfaces;
+      if (!pending) {
+        continue;
+      }
+
+      c.pendingInterfaces = pending.filter((get) => {
+        const iface = get();
+        if (!iface) {
+          return true;
+        }
+
+        iface.settleInterfaces();
+        c.interfaces.add(iface);
+        for (const i of iface.interfaces) {
+          c.interfaces.add(i);
+        }
+
+        return false;
+      });
+      if (!c.pendingInterfaces.length) {
+        c.pendingInterfaces = null;
+      }
+    }
+  }
+
+  /**
+   * The interfaces of this class and its bases, once none of them has one
+   * pending: from then on what isSubtypeOf answers no more changes, and
+   * a class that is not t answers by this alone, as `is` on a 3D
+   * engine's scene nodes asks every frame.
+   */
+  private allInterfaces: Set<Traits> | null = null;
+
+  isSubtypeOf(t: Traits): boolean {
+    for (let c: Traits | null = this; c; c = c.base) {
+      if (c === t) {
+        return true;
+      }
+    }
+
+    // A class is a supertype only as a base; only interfaces are in the sets below.
+    if (!t.isInterface) {
+      return false;
+    }
+
+    if (this.allInterfaces !== null) {
+      return this.allInterfaces.has(t);
+    }
+
+    if (this.interfaces.has(t)) {
+      return true;
+    }
+
+    // An interface a base settled after this class copied its interfaces.
+    this.settleInterfaces();
+    let settled = true;
+    const all = new Set<Traits>();
+    for (let c: Traits | null = this; c; c = c.base) {
+      if (c.pendingInterfaces) {
+        settled = false;
+      }
+
+      for (const i of c.interfaces) {
+        all.add(i);
+      }
+    }
+
+    if (settled) {
+      this.allInterfaces = all;
+    }
+
+    return all.has(t);
+  }
+}
+
+/** A class named in a module, resolved the first time it is needed. */
+export class ClassRef {
+  cls: AsObject | null = null;
+  /**
+   * Its instances' traits, once coerceTo has found them; a compiled
+   * method's parameter of the type reads them by name on entry.
+   */
+  traits: Traits | null = null;
+
+  constructor(
+    readonly ns: Namespace,
+    readonly name: string,
+    /** The domain its module was loaded into, which it is resolved in. */
+    readonly domain: Domain,
+  ) {}
+}
+
+/** Vector.<T>, resolved the first time it is needed. */
+export class VectorRef {
+  cls: AsObject | null = null;
+  /**
+   * Its instances' traits, once coerceTo has found them; a compiled
+   * method's parameter of the type reads them by name on entry.
+   */
+  traits: Traits | null = null;
+
+  constructor(readonly param: TypeRef) {}
+}
+
+/** The initial values of `defaults` by slot id, the last of a slot listed twice, as they are set. */
+function valuesBySlot(defaults: [string, Value][]): Value[] {
+  let count = 0;
+  for (const [key] of defaults) {
+    count = Math.max(count, Number(key.slice(1)) + 1);
+  }
+
+  const values: Value[] = new Array(count).fill(undefined);
+  for (const [key, value] of defaults) {
+    values[Number(key.slice(1))] = value;
+  }
+
+  return values;
+}
+
+/**
+ * The properties a prototype object takes before its traits' methods go
+ * on in another below it (Traits.methodHome), well short of V8's 1020; a
+ * few counted in advance for the prototype's own ($traits, $p, $init).
+ */
+const HOME_PROPERTIES = 768;
+const HOME_SLACK = 16;
+
+/**
+ * The first slot an object keeps in its array `$S` rather than in a
+ * property of its own, as the codegen's SPILL_SLOTS (emit/refs.ts), which
+ * compiled code reads and writes there (`o.$S[n - SPILL_SLOTS]`): V8
+ * keeps an object of more than 1020 properties as a dictionary, which
+ * hashes every name looked up in it. A Crossbridge program's global, of
+ * thousands of slots, its stack pointer and registers among the first,
+ * ran five times as slow as one that is not. The slot's name reaches the
+ * array through an accessor on the prototype (spilledSlot), so that what
+ * looks slots up by name finds them as any other.
+ */
+export const SPILL_SLOTS = 900;
+
+/** Slot `slot`'s accessor in `home`, a prototype of its objects: the object's `$S` at its place. */
+function spilledSlot(home: AsObject, slot: number): void {
+  const at = slot - SPILL_SLOTS;
+  Object.defineProperty(home, slotKey(slot), {
+    get(this: AsObject) {
+      return this.$S[at];
+    },
+    set(this: AsObject, v: Value) {
+      this.$S[at] = v;
+    },
+    configurable: true,
+  });
+}
+
+// The names of slot and method properties by id, made once each, for the
+// runtime's dynamic paths; generated code names them itself.
+const slotKeys: string[] = [];
+const methodKeys: string[] = [];
+export const slotKey = (id: number): string => (slotKeys[id] ??= `$${id}`);
+export const methodKey = (id: number): string => (methodKeys[id] ??= `$m${id}`);
+const untypedSetKeys: string[] = [];
+/**
+ * Where a native's setter, dispatch id `id`, is kept as an untyped set
+ * calls it, its value coerced (installMethod); a setter with none is
+ * called as it is.
+ */
+export const untypedSetKey = (id: number): string => (untypedSetKeys[id] ??= `$u${id}`);
+const boundKeys: string[] = [];
+/**
+ * Where a method, dispatch id `id`, is kept as calls the compiler bound
+ * call it, their arguments coerced and counted already: its entry for
+ * them if it has one (a compiled method's `$bound`), else itself.
+ */
+export const boundKey = (id: number): string => (boundKeys[id] ??= `$b${id}`);

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Language runtime that generated code calls into. Only AS2/AS3 semantics
+ * live here; playerglobal belongs to @swf2es/player, so this package runs in
+ * node next to avmshell for conformance tests.
+ */
+
+export * as avm1 from "./avm1/index.js";
+export * as avm2 from "./avm2/index.js";