@swf2es/player 0.0.0-stage → 0.1.0

package/src/workers/thread.ts

@@ -0,0 +1,188 @@
+// A background worker's thread (docs/workers.md): a VM of its own, codegen,
+// runtime and playerglobal, playing the SWF createWorker was given with no
+// renderer, sound or input. Its frames run on a timer at the SWF's rate,
+// so that its timers, enterFrame and the events it is sent fire. A host
+// runs this in a Web Worker or a node worker_threads Worker; nothing here
+// knows which.
+import { createCodegen } from "@swf2es/codegen";
+import { avm2 } from "@swf2es/runtime";
+import { Player } from "../player.js";
+import { Scripting } from "../scripting.js";
+import type { FromWorker, ToWorker, WorkerInit } from "./protocol.js";
+
+/** What a thread is posted first: codegen's compiled module, and the worker to run. */
+export interface ThreadStart {
+  codegen: WebAssembly.Module;
+  init: WorkerInit;
+}
+
+/** How a thread talks to the thread that started it: a Web Worker's global scope, or node's parentPort. */
+export interface ThreadPort {
+  post(message: FromWorker): void;
+  /** Takes each message from the parent, in order: a ThreadStart first, then the rest. */
+  listen(receive: (message: ThreadStart | ToWorker) => void): void;
+}
+
+/** Run the worker the parent posts, on this thread, until the parent terminates it. */
+export function runWorkerThread(port: ThreadPort): void {
+  let scripting: Scripting | null = null;
+  // Messages that came while the VM was being made, applied once it is.
+  const early: ToWorker[] = [];
+  // How many of the parent's messages have been applied, the start the first.
+  let applied = 0;
+  let idled = 0;
+  let player: Player | null = null;
+  let stopped = false;
+
+  /**
+   * Once its worker is terminated, stop it for good, between frames, so
+   * that none of its code runs again, then say so in the shared memory: the
+   * Mutexes it held are free to take from then on. A lock or wait it asks
+   * for after it was terminated is refused, but the frame that asked plays
+   * on, its other listeners too, so this waits for the frame's end.
+   */
+  const stopIfTerminated = (): boolean => {
+    if (stopped || !scripting || !avm2.syncOf(scripting.rt).terminated) {
+      return stopped;
+    }
+
+    stopped = true;
+    try {
+      player?.destroy();
+      scripting.destroy();
+    } catch (error) {
+      if (!(error instanceof avm2.SyncTerminated)) {
+        port.post({ type: "uncaught", text: describe(error) });
+      }
+    } finally {
+      avm2.syncOf(scripting.rt).end(id);
+    }
+
+    return true;
+  };
+  let id = 0;
+
+  const describe = (error: unknown): string => {
+    if (error instanceof Error) {
+      return `${error.name}: ${error.message}`;
+    }
+
+    try {
+      return scripting ? scripting.rt.toString(error as never) : String(error);
+    } catch {
+      return "an error that could not be described";
+    }
+  };
+
+  const boot = async ({ codegen, init }: ThreadStart): Promise<void> => {
+    id = init.id;
+    // What the embedder gave the primordial lives on its thread, as
+    // functions no message carries: a worker gets none of it, and none of
+    // the defaults that would reach past the primordial's (docs/workers.md).
+    const storage = new Map<string, Uint8Array>();
+    const s = new Scripting(await createCodegen(codegen), {
+      handedModules: init.modules,
+      url: init.url,
+      sandboxType: init.sandboxType,
+      air: init.air,
+      print: (line) => port.post({ type: "trace", line }),
+      onUncaught: (error) => port.post({ type: "uncaught", text: describe(error) }),
+      workerParent: { id: init.id, post: (message) => port.post(message), shared: init.shared },
+      // Its Mutexes, Conditions and channels' queues are among the primordial's.
+      sync: { memory: init.sync, thread: init.id },
+      audio: null,
+      navigate: null,
+      fileHost: null,
+      clipboard: null,
+      webSocket: null,
+      sendToUrl: false,
+      storage: {
+        get: (key) => storage.get(key) ?? null,
+        set: (key, bytes) => {
+          storage.set(key, bytes.slice());
+        },
+        remove: (key) => {
+          storage.delete(key);
+        },
+      },
+    });
+    await s.loadLibraries(init.libraries);
+    player = new Player(init.swf, s);
+    const playing = player;
+    scripting = s;
+    applied++;
+    for (const message of early.splice(0)) {
+      s.workers.fromParent(message);
+      applied++;
+    }
+
+    // Running, which the worker that made it sees at once.
+    avm2.syncOf(s.rt).start(init.id);
+    port.post({ type: "running" });
+    await playing.start();
+    if (stopIfTerminated()) {
+      return;
+    }
+
+    // Between frames none of its code runs: it stops there at once.
+    const watch = setInterval(() => {
+      if (stopIfTerminated()) {
+        clearInterval(watch);
+      }
+    }, 10);
+
+    // What was applied before a frame has had its events in it: the parent's settled() waits for that.
+    let last = performance.now();
+    const frame = () => {
+      if (stopIfTerminated()) {
+        return;
+      }
+
+      const upTo = applied;
+      const now = performance.now();
+      const played = playing.advance(now - last);
+      last = now;
+      if (stopIfTerminated()) {
+        return;
+      }
+
+      if (played > 0 && upTo > idled) {
+        idled = upTo;
+        port.post({ type: "idle", received: upTo });
+      }
+
+      setTimeout(frame, 1000 / playing.frameRate);
+    };
+    setTimeout(frame, 1000 / playing.frameRate);
+  };
+
+  port.listen((message) => {
+    if ("codegen" in message) {
+      boot(message).catch((error) => {
+        // A worker terminated while it started, its constructor waiting or
+        // its VM still being made, stops quietly.
+        if (stopIfTerminated()) {
+          return;
+        }
+
+        if (error instanceof avm2.SyncTerminated) {
+          stopped = true;
+          new avm2.Sync(message.init.sync, message.init.id).end(message.init.id);
+          return;
+        }
+
+        port.post({ type: "uncaught", text: describe(error) });
+        port.post({ type: "terminate" });
+      });
+      return;
+    }
+
+    if (!scripting) {
+      early.push(message);
+      return;
+    }
+
+    scripting.workers.fromParent(message);
+    applied++;
+  });
+}

package/src/workers/wire.ts

@@ -0,0 +1,263 @@
+// A WireValue as bytes, for a channel's queue in the memory the workers
+// share (docs/workers.md): what a worker blocked in receive(true) takes
+// without returning to its event loop, so nothing in it may be memory
+// only a posted message could bring. A Mutex, a Condition and a channel
+// are addresses in the shared heap, which every worker has; a shareable
+// ByteArray's memory goes by its id, and comes to each worker with the
+// message's notice.
+import type { ChannelRef, WireValue } from "./protocol.js";
+
+/** A WireValue as it is queued: a shareable ByteArray's memory by its id. */
+export type PackedValue =
+  | Exclude<WireValue, { kind: "shared" }>
+  | { kind: "shared"; id: number; memory?: undefined };
+
+const NUMBER = 0;
+const TRUE = 1;
+const FALSE = 2;
+const STRING = 3;
+const NULL = 4;
+const AMF = 5;
+const BYTES = 6;
+const SHARED = 7;
+const CHANNEL = 8;
+const MUTEX = 9;
+const CONDITION = 10;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function tagged(tag: number, length: number): { out: Uint8Array; view: DataView } {
+  const out = new Uint8Array(1 + length);
+  out[0] = tag;
+  return { out, view: new DataView(out.buffer) };
+}
+
+function withBytes(tag: number, bytes: Uint8Array): Uint8Array {
+  const { out } = tagged(tag, bytes.length);
+  out.set(bytes, 1);
+  return out;
+}
+
+export function pack(wire: WireValue): Uint8Array {
+  switch (wire.kind) {
+    case "value": {
+      const v = wire.value;
+      if (v === null) {
+        return tagged(NULL, 0).out;
+      }
+
+      if (typeof v === "boolean") {
+        return tagged(v ? TRUE : FALSE, 0).out;
+      }
+
+      if (typeof v === "string") {
+        return withBytes(STRING, encoder.encode(v));
+      }
+
+      const { out, view } = tagged(NUMBER, 8);
+      view.setFloat64(1, v, true);
+      return out;
+    }
+    case "amf":
+      return withBytes(AMF, wire.bytes);
+    case "bytes":
+      return withBytes(BYTES, wire.bytes);
+    case "shared": {
+      const { out, view } = tagged(SHARED, 8);
+      view.setFloat64(1, wire.memory.id, true);
+      return out;
+    }
+    case "channel": {
+      const { out, view } = tagged(CHANNEL, 20);
+      view.setFloat64(1, wire.channel.id, true);
+      view.setInt32(9, wire.channel.sender, true);
+      view.setInt32(13, wire.channel.receiver, true);
+      view.setInt32(17, wire.channel.queue, true);
+      return out;
+    }
+    case "sync": {
+      const { out, view } = tagged(wire.ref.kind === "mutex" ? MUTEX : CONDITION, 4);
+      view.setInt32(1, wire.ref.address, true);
+      return out;
+    }
+  }
+}
+
+export function unpack(bytes: Uint8Array): PackedValue {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const rest = () => bytes.slice(1);
+  switch (bytes[0]) {
+    case NUMBER:
+      return { kind: "value", value: view.getFloat64(1, true) };
+    case TRUE:
+    case FALSE:
+      return { kind: "value", value: bytes[0] === TRUE };
+    case STRING:
+      return { kind: "value", value: decoder.decode(bytes.subarray(1)) };
+    case NULL:
+      return { kind: "value", value: null };
+    case AMF:
+      return { kind: "amf", bytes: rest() };
+    case BYTES:
+      return { kind: "bytes", bytes: rest() };
+    case SHARED:
+      return { kind: "shared", id: view.getFloat64(1, true) };
+    case CHANNEL: {
+      const channel: ChannelRef = {
+        id: view.getFloat64(1, true),
+        sender: view.getInt32(9, true),
+        receiver: view.getInt32(13, true),
+        queue: view.getInt32(17, true),
+      };
+      return { kind: "channel", channel };
+    }
+    default:
+      return {
+        kind: "sync",
+        ref: { kind: bytes[0] === MUTEX ? "mutex" : "condition", address: view.getInt32(1, true) },
+      };
+  }
+}
+
+/** A shared property as the table in shared memory keeps it. */
+export interface TableEntry {
+  worker: number;
+  key: string | null;
+  /** Unique to this set, by which a worker knows the value it set itself. */
+  token: number;
+  value: Uint8Array;
+}
+
+export function packTable(entries: Iterable<TableEntry>): Uint8Array {
+  const parts: Uint8Array[] = [];
+  for (const e of entries) {
+    const key = e.key === null ? null : encoder.encode(e.key);
+    const head = new DataView(new ArrayBuffer(16));
+    head.setInt32(0, e.worker, true);
+    head.setInt32(4, key === null ? -1 : key.length, true);
+    head.setInt32(8, e.token, true);
+    head.setUint32(12, e.value.length, true);
+    parts.push(new Uint8Array(head.buffer), key ?? new Uint8Array(0), e.value);
+  }
+
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) {
+    out.set(p, at);
+    at += p.length;
+  }
+
+  return out;
+}
+
+export function unpackTable(bytes: Uint8Array): TableEntry[] {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const entries: TableEntry[] = [];
+  let at = 0;
+  while (at < bytes.length) {
+    const worker = view.getInt32(at, true);
+    const keyLength = view.getInt32(at + 4, true);
+    const token = view.getInt32(at + 8, true);
+    const valueLength = view.getUint32(at + 12, true);
+    at += 16;
+    const key = keyLength < 0 ? null : decoder.decode(bytes.subarray(at, at + keyLength));
+    at += Math.max(keyLength, 0);
+    entries.push({ worker, key, token, value: bytes.slice(at, at + valueLength) });
+    at += valueLength;
+  }
+
+  return entries;
+}
+
+/**
+ * A worker a background worker made, for the primordial to start: its
+ * number, its maker's, its SWF, and its shared properties as its maker
+ * had them, which the maker's own messages may not have brought yet.
+ */
+export interface Job {
+  id: number;
+  creator: number;
+  swf: Uint8Array<ArrayBuffer>;
+  shared: { worker: number; key: string | null; value: PackedValue }[];
+}
+
+/** A request for the primordial: a worker a background worker made, to start or to terminate. */
+export type Request = { type: "start"; job: Job } | { type: "end"; id: number; creator: number };
+
+const START = 0;
+const END = 1;
+
+export function packEnd(id: number, creator: number): Uint8Array {
+  const out = new DataView(new ArrayBuffer(9));
+  out.setUint8(0, END);
+  out.setInt32(1, id, true);
+  out.setInt32(5, creator, true);
+  return new Uint8Array(out.buffer);
+}
+
+export function unpackRequest(bytes: Uint8Array): Request {
+  if (bytes[0] === END) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return { type: "end", id: view.getInt32(1, true), creator: view.getInt32(5, true) };
+  }
+
+  return { type: "start", job: unpackJob(bytes.subarray(1)) };
+}
+
+export function packJob(
+  id: number,
+  creator: number,
+  swf: Uint8Array,
+  shared: { worker: number; key: string | null; value: WireValue }[],
+): Uint8Array {
+  const head = new DataView(new ArrayBuffer(16));
+  head.setInt32(0, id, true);
+  head.setInt32(4, creator, true);
+  head.setUint32(8, swf.length, true);
+  head.setUint32(12, shared.length, true);
+  const parts: Uint8Array[] = [new Uint8Array([START]), new Uint8Array(head.buffer), swf];
+  for (const p of shared) {
+    const key = p.key === null ? null : encoder.encode(p.key);
+    const value = pack(p.value);
+    const entry = new DataView(new ArrayBuffer(12));
+    entry.setInt32(0, p.worker, true);
+    entry.setInt32(4, key === null ? -1 : key.length, true);
+    entry.setUint32(8, value.length, true);
+    parts.push(new Uint8Array(entry.buffer), key ?? new Uint8Array(0), value);
+  }
+
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const p of parts) {
+    out.set(p, at);
+    at += p.length;
+  }
+
+  return out;
+}
+
+function unpackJob(bytes: Uint8Array): Job {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const swfLength = view.getUint32(8, true);
+  const count = view.getUint32(12, true);
+  let at = 16 + swfLength;
+  const shared: Job["shared"] = [];
+  for (let i = 0; i < count; i++) {
+    const worker = view.getInt32(at, true);
+    const keyLength = view.getInt32(at + 4, true);
+    const valueLength = view.getUint32(at + 8, true);
+    at += 12;
+    const key = keyLength < 0 ? null : decoder.decode(bytes.subarray(at, at + keyLength));
+    at += Math.max(keyLength, 0);
+    shared.push({ worker, key, value: unpack(bytes.slice(at, at + valueLength)) });
+    at += valueLength;
+  }
+
+  return {
+    id: view.getInt32(0, true),
+    creator: view.getInt32(4, true),
+    swf: bytes.slice(16, 16 + swfLength),
+    shared,
+  };
+}