@engine262/engine262 0.0.1-01e9fa95a4e8a1c042efd00492309a2de4998fd0

package/src/host-defined/event-loop.mts

@@ -0,0 +1,311 @@
+import { callCallback } from '../utils/callback.mts';
+import {
+  Agent,
+  type GCMarker, type Job, type Markable,
+  runSingleJobInQueue,
+} from '#self';
+
+/** https://nodejs.org/learn/asynchronous-work/event-loop-timers-and-nexttick */
+export type NodeJSJobType = 'timers' | 'pending callbacks' | 'idle-prepare' | 'poll' | 'check' | 'close callbacks';
+export type EventLoopRunType = 'manual' | 'automatic';
+
+export interface EventLoop extends Markable {
+  /**
+   * Enqueue a host job (macrotask) now.
+   */
+  enqueue(type: NodeJSJobType | string, job: Job): void;
+
+  /**
+   * Enqueue a host job (macrotask) in the future.
+   * It will keep `hasPendingJobs` to be `true` until `enqueue` is called.
+   *
+   * @example
+   * ```
+   * eventLoop.enqueueAsync('timers', job, (enqueue, cancel) => {
+   *   setTimeout(() => {
+   *     enqueue();
+   *   }, timeout);
+   * });
+   * ```
+   */
+  enqueueAsync(type: NodeJSJobType | string, job: Job, executor: (enqueue: () => void, cancel: () => void) => void): void;
+
+  /** Change the automatic run type of the event loop and run it */
+  run(type: EventLoopRunType): void;
+
+  runOnce(): void;
+
+  readonly hasPendingJobs: boolean;
+  /**
+   * Register a callback to be called when there are no async queued jobs.
+   *
+   * This can be used to implement a mechanism to exit the program when all code has finished executing.
+   */
+  onNoPendingJob: Set<() => void>;
+}
+
+export abstract class AbstractEventLoop implements EventLoop {
+  protected readonly surroundingAgent: Agent;
+
+  #runType?: EventLoopRunType;
+
+  #flushState: 'idle' | 'running' | 'rerun' = 'idle';
+
+  public readonly onNoPendingJob: Set<() => void> = new Set();
+
+  constructor(surroundingAgent: Agent) {
+    this.surroundingAgent = surroundingAgent;
+  }
+
+  abstract enqueue(type: NodeJSJobType | string, job: Job): void;
+
+  protected abstract shiftNextJob(): Job | undefined;
+
+  protected abstract get hasQueuedJobs(): boolean;
+
+  protected tryScheduleAutomaticFlush() {
+    this.#tryScheduleAutomaticFlush();
+  }
+
+  #tryScheduleAutomaticFlush = () => {
+    if (this.#runType !== 'automatic') return;
+    this.runOnce();
+  };
+
+  #pendingJobs = new Set<Job>();
+
+  /**
+   * Enqueue a host job (macrotask) in the future.
+   * It will keep `hasPendingJobs` to be `true` until `enqueue` is called.
+   *
+   * @example
+   * ```
+   * eventLoop.enqueueAsync('timers', job, (enqueue, cancel) => {
+   *   setTimeout(() => {
+   *     enqueue();
+   *   }, timeout);
+   * });
+   * ```
+   */
+  enqueueAsync(type: NodeJSJobType | string, job: Job, doAsyncEnqueue: (enqueue: () => void, cancel: () => void) => void): void {
+    this.#pendingJobs.add(job);
+    doAsyncEnqueue(() => {
+      this.#pendingJobs.delete(job);
+      this.enqueue(type, job);
+      this.#callNoPendingJobsCallback();
+    }, () => {
+      this.#pendingJobs.delete(job);
+      this.#callNoPendingJobsCallback();
+    });
+  }
+
+  get hasPendingJobs(): boolean {
+    return this.#pendingJobs.size > 0;
+  }
+
+  /** Change the automatic run type of the event loop */
+  run(type: EventLoopRunType): void {
+    this.surroundingAgent.jobQueue.onNewJob.delete(this.#tryScheduleAutomaticFlush);
+    this.surroundingAgent.onNoEvaluator.delete(this.#tryScheduleAutomaticFlush);
+    this.#runType = type;
+    if (type === 'automatic') {
+      this.surroundingAgent.jobQueue.onNewJob.add(this.#tryScheduleAutomaticFlush);
+      this.surroundingAgent.onNoEvaluator.add(this.#tryScheduleAutomaticFlush);
+    }
+    this.runOnce();
+  }
+
+  runOnce() {
+    if (this.surroundingAgent.executionContextStack.length > 0 || this.surroundingAgent.isPaused()) return;
+    if (this.#flushState === 'running') {
+      this.#flushState = 'rerun';
+      return;
+    }
+    if (this.#flushState === 'rerun') return;
+    this.#flushState = 'running';
+    this.#continueFlush();
+  }
+
+  #continueFlush() {
+    let previousJobSyncFinished = true;
+    while (previousJobSyncFinished) {
+      previousJobSyncFinished = false;
+
+      const job = this.shiftNextJob();
+      if (!job) {
+        this.#finishFlush();
+        return;
+      }
+
+      let currentJobSyncFinished = true;
+      runSingleJobInQueue(job, (error) => {
+        this.surroundingAgent.hostDefinedOptions.uncaughtExceptionTrackers?.forEach((tracker) => tracker(error));
+      }, () => {
+        if (currentJobSyncFinished) {
+          previousJobSyncFinished = true;
+          return;
+        }
+        this.#continueFlush();
+      });
+      currentJobSyncFinished = false;
+    }
+  }
+
+  #finishFlush() {
+    if (this.#flushState === 'rerun') {
+      this.#flushState = 'running';
+      this.#continueFlush();
+      return;
+    }
+    this.#flushState = 'idle';
+    this.#callNoPendingJobsCallback();
+  }
+
+  #callNoPendingJobsCallback() {
+    if (this.surroundingAgent.jobQueue.length === 0 && !this.hasQueuedJobs && !this.hasPendingJobs) {
+      callCallback(this.onNoPendingJob);
+    }
+  }
+
+  mark(marker: GCMarker): void {
+    for (const job of this.#pendingJobs) {
+      marker(job.callerRealm);
+      marker(job.callerScriptOrModule);
+      marker(job.job);
+    }
+  }
+}
+
+export class MicroTaskEventLoop extends AbstractEventLoop {
+  enqueue(_type: string, job: Job): void {
+    this.surroundingAgent.jobQueue.enqueueGenericJob(job);
+    this.tryScheduleAutomaticFlush();
+  }
+
+  protected shiftNextJob(): Job | undefined {
+    return this.surroundingAgent.jobQueue.shift();
+  }
+
+  protected get hasQueuedJobs(): boolean {
+    // all jobs are microtasks, there are no jobs queued in this subclass.
+    return false;
+  }
+}
+
+/** https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide/In_depth */
+export class WebLikeEventLoop extends AbstractEventLoop {
+  protected jobsByType: Record<string, Set<Job>> = Object.create(null);
+
+  protected queuedJobs = new Map<Job, string>();
+
+  /**
+   * Enqueue a host job (macrotask) now.
+   */
+  enqueue(type: NodeJSJobType | string, job: Job): void {
+    this.jobsByType[type] ??= new Set<Job>();
+    this.jobsByType[type].add(job);
+    this.queuedJobs.set(job, type);
+    this.tryScheduleAutomaticFlush();
+  }
+
+  protected shiftNextJob(): Job | undefined {
+    const queuedJob = this.surroundingAgent.jobQueue.shift();
+    if (queuedJob) return queuedJob;
+    const macrotask = this.queuedJobs.entries().next().value;
+    if (!macrotask) return undefined;
+    this.queuedJobs.delete(macrotask[0]);
+    this.jobsByType[macrotask[1]]!.delete(macrotask[0]);
+    return macrotask[0];
+  }
+
+  protected get hasQueuedJobs(): boolean {
+    return this.queuedJobs.size > 0;
+  }
+
+  override mark(marker: GCMarker): void {
+    super.mark(marker);
+    for (const job of this.queuedJobs.keys()) {
+      marker(job.job);
+      marker(job.callerRealm);
+      marker(job.callerScriptOrModule);
+    }
+  }
+}
+
+const NODEJS_PHASES = [
+  'timers',
+  'pending callbacks',
+  'idle-prepare',
+  'poll',
+  'check',
+  'close callbacks',
+] as const satisfies readonly NodeJSJobType[];
+function isNodeJSJobType(type: NodeJSJobType | string): type is NodeJSJobType {
+  return NODEJS_PHASES.includes(type as NodeJSJobType);
+}
+
+/** https://nodejs.org/learn/asynchronous-work/event-loop-timers-and-nexttick */
+export class NodeJSLikeEventLoop extends AbstractEventLoop {
+  fallbackType: NodeJSJobType = 'poll';
+
+  protected jobsByType: Record<NodeJSJobType, Set<Job>> = {
+    'timers': new Set(),
+    'pending callbacks': new Set(),
+    'idle-prepare': new Set(),
+    'poll': new Set(),
+    'check': new Set(),
+    'close callbacks': new Set(),
+  };
+
+  protected queuedJobs = new Set<Job>();
+
+  enqueue(type: NodeJSJobType | string, job: Job): void {
+    const queueType = isNodeJSJobType(type) ? type : this.fallbackType;
+    this.jobsByType[queueType].add(job);
+    this.queuedJobs.add(job);
+    this.tryScheduleAutomaticFlush();
+  }
+
+  #phase_index = 0;
+
+  #advancePhase() {
+    this.#phase_index = (this.#phase_index + 1) % NODEJS_PHASES.length;
+  }
+
+  #shiftCurrentPhaseTask(): Job | undefined {
+    const type = NODEJS_PHASES[this.#phase_index]!;
+    const [job] = this.jobsByType[type];
+    if (!job) {
+      return undefined;
+    }
+    this.jobsByType[type].delete(job);
+    this.queuedJobs.delete(job);
+    return job;
+  }
+
+  protected shiftNextJob(): Job | undefined {
+    const queuedJob = this.surroundingAgent.jobQueue.shift();
+    if (queuedJob) return queuedJob;
+
+    for (let i = 0; i < NODEJS_PHASES.length; i += 1) {
+      const macrotask = this.#shiftCurrentPhaseTask();
+      if (macrotask) return macrotask;
+      this.#advancePhase();
+    }
+
+    return undefined;
+  }
+
+  protected get hasQueuedJobs(): boolean {
+    return this.queuedJobs.size > 0;
+  }
+
+  override mark(marker: GCMarker): void {
+    super.mark(marker);
+    for (const job of this.queuedJobs) {
+      marker(job.job);
+      marker(job.callerRealm);
+      marker(job.callerScriptOrModule);
+    }
+  }
+}

package/src/host-defined/ieee754.mts

@@ -0,0 +1,212 @@
+const FLOAT16_FRACTION_BITS = 10;
+const FLOAT16_EXPONENT_BITS = 5;
+const FLOAT16_BIAS = 15;
+const FLOAT16_CANONICAL_NAN_BITS = 0x7E00;
+
+const FLOAT32_FRACTION_BITS = 23;
+const FLOAT32_EXPONENT_BITS = 8;
+const FLOAT32_BIAS = 127;
+const FLOAT32_CANONICAL_NAN_BITS = 0x7FC00000;
+
+const FLOAT64_FRACTION_BITS = 52;
+const FLOAT64_EXPONENT_BITS = 11;
+const FLOAT64_BIAS = 1023;
+const FLOAT64_CANONICAL_NAN_BITS = 0x7FF8000000000000n;
+
+interface FloatFormat {
+  readonly fractionBits: number;
+  readonly exponentBits: number;
+  readonly exponentBias: number;
+  readonly canonicalNaNBits: bigint;
+}
+
+const FLOAT16_FORMAT: FloatFormat = {
+  fractionBits: FLOAT16_FRACTION_BITS,
+  exponentBits: FLOAT16_EXPONENT_BITS,
+  exponentBias: FLOAT16_BIAS,
+  canonicalNaNBits: BigInt(FLOAT16_CANONICAL_NAN_BITS),
+};
+
+const FLOAT32_FORMAT: FloatFormat = {
+  fractionBits: FLOAT32_FRACTION_BITS,
+  exponentBits: FLOAT32_EXPONENT_BITS,
+  exponentBias: FLOAT32_BIAS,
+  canonicalNaNBits: BigInt(FLOAT32_CANONICAL_NAN_BITS),
+};
+
+const FLOAT64_FORMAT: FloatFormat = {
+  fractionBits: FLOAT64_FRACTION_BITS,
+  exponentBits: FLOAT64_EXPONENT_BITS,
+  exponentBias: FLOAT64_BIAS,
+  canonicalNaNBits: FLOAT64_CANONICAL_NAN_BITS,
+};
+
+function bitsToLittleEndianBytes(bits: bigint, byteCount: number) {
+  const bytes = new Array<number>(byteCount);
+  for (let i = 0; i < byteCount; i += 1) {
+    bytes[i] = Number((bits >> BigInt(i * 8)) & 0xFFn);
+  }
+  return bytes;
+}
+
+function littleEndianBytesToBits(rawBytes: readonly number[]) {
+  let bits = 0n;
+  for (let i = 0; i < rawBytes.length; i += 1) {
+    bits |= BigInt(rawBytes[i]!) << BigInt(i * 8);
+  }
+  return bits;
+}
+
+function roundShiftRightToEven(value: bigint, shift: number) {
+  if (shift <= 0) {
+    return value << BigInt(-shift);
+  }
+  const quotient = value >> BigInt(shift);
+  const remainderMask = (1n << BigInt(shift)) - 1n;
+  const remainder = value & remainderMask;
+  const half = 1n << BigInt(shift - 1);
+  if (remainder > half) {
+    return quotient + 1n;
+  }
+  if (remainder < half) {
+    return quotient;
+  }
+  return quotient & 1n ? quotient + 1n : quotient;
+}
+
+function decomposeFiniteNumber(value: number) {
+  const abs = Math.abs(value);
+  if (abs < 2 ** -1022) {
+    return {
+      sign: Object.is(value, -0) || value < 0 ? 1n : 0n,
+      significand: BigInt(abs / 2 ** -1074),
+      exponent: -1074,
+    };
+  }
+
+  let exponent = Math.floor(Math.log2(abs));
+  const scaled = abs / 2 ** exponent;
+  if (scaled < 1) {
+    exponent -= 1;
+  } else if (scaled >= 2) {
+    exponent += 1;
+  }
+
+  return {
+    sign: Object.is(value, -0) || value < 0 ? 1n : 0n,
+    significand: BigInt(abs / 2 ** (exponent - FLOAT64_FRACTION_BITS)),
+    exponent: exponent - FLOAT64_FRACTION_BITS,
+  };
+}
+
+function encodeFloatBits(value: number, format: FloatFormat) {
+  const maxExponentBits = (1n << BigInt(format.exponentBits)) - 1n;
+  const signBitShift = BigInt(format.exponentBits + format.fractionBits);
+
+  if (Number.isNaN(value)) {
+    return format.canonicalNaNBits;
+  }
+
+  const sign = Object.is(value, -0) || value < 0 ? 1n : 0n;
+  if (!Number.isFinite(value)) {
+    return (sign << signBitShift) | (maxExponentBits << BigInt(format.fractionBits));
+  }
+  if (value === 0) {
+    return sign << signBitShift;
+  }
+
+  const { significand, exponent } = decomposeFiniteNumber(value);
+  const significandBits = significand.toString(2).length;
+  let unbiasedExponent = exponent + significandBits - 1;
+  const minNormalExponent = 1 - format.exponentBias;
+  const maxNormalExponent = format.exponentBias;
+  const targetPrecision = format.fractionBits + 1;
+
+  if (unbiasedExponent >= minNormalExponent) {
+    const shift = unbiasedExponent - format.fractionBits;
+    let roundedSignificand = exponent >= shift
+      ? significand << BigInt(exponent - shift)
+      : roundShiftRightToEven(significand, shift - exponent);
+
+    const roundedWidth = roundedSignificand.toString(2).length;
+    if (roundedWidth > targetPrecision) {
+      roundedSignificand >>= 1n;
+      unbiasedExponent += 1;
+    }
+
+    if (unbiasedExponent > maxNormalExponent) {
+      return (sign << signBitShift) | (maxExponentBits << BigInt(format.fractionBits));
+    }
+
+    const exponentBits = BigInt(unbiasedExponent + format.exponentBias);
+    const fractionMask = (1n << BigInt(format.fractionBits)) - 1n;
+    const fractionBits = roundedSignificand & fractionMask;
+    return (sign << signBitShift) | (exponentBits << BigInt(format.fractionBits)) | fractionBits;
+  }
+
+  const subnormalShift = minNormalExponent - format.fractionBits;
+  const subnormalSignificand = exponent >= subnormalShift
+    ? significand << BigInt(exponent - subnormalShift)
+    : roundShiftRightToEven(significand, subnormalShift - exponent);
+
+  if (subnormalSignificand === 0n) {
+    return sign << signBitShift;
+  }
+
+  const normalThreshold = 1n << BigInt(format.fractionBits);
+  if (subnormalSignificand >= normalThreshold) {
+    return (sign << signBitShift) | (1n << BigInt(format.fractionBits));
+  }
+
+  return (sign << signBitShift) | subnormalSignificand;
+}
+
+function decodeFloatBits(bits: bigint, format: FloatFormat) {
+  const signShift = BigInt(format.exponentBits + format.fractionBits);
+  const sign = (bits >> signShift) & 1n;
+  const exponentMask = (1n << BigInt(format.exponentBits)) - 1n;
+  const fractionMask = (1n << BigInt(format.fractionBits)) - 1n;
+  const exponentBits = Number((bits >> BigInt(format.fractionBits)) & exponentMask);
+  const fractionBits = bits & fractionMask;
+  const signMultiplier = sign === 0n ? 1 : -1;
+
+  if (exponentBits === Number(exponentMask)) {
+    if (fractionBits === 0n) {
+      return signMultiplier === 1 ? Infinity : -Infinity;
+    }
+    return NaN;
+  }
+
+  if (exponentBits === 0) {
+    if (fractionBits === 0n) {
+      return signMultiplier === 1 ? 0 : -0;
+    }
+    return signMultiplier * Number(fractionBits) * 2 ** (1 - format.exponentBias - format.fractionBits);
+  }
+
+  return signMultiplier * (1 + Number(fractionBits) / 2 ** format.fractionBits) * 2 ** (exponentBits - format.exponentBias);
+}
+
+export function encodeFloat16(value: number) {
+  return bitsToLittleEndianBytes(encodeFloatBits(value, FLOAT16_FORMAT), 2);
+}
+
+export function decodeFloat16(rawBytes: readonly number[]) {
+  return decodeFloatBits(littleEndianBytesToBits(rawBytes), FLOAT16_FORMAT);
+}
+
+export function encodeFloat32(value: number) {
+  return bitsToLittleEndianBytes(encodeFloatBits(value, FLOAT32_FORMAT), 4);
+}
+
+export function decodeFloat32(rawBytes: readonly number[]) {
+  return decodeFloatBits(littleEndianBytesToBits(rawBytes), FLOAT32_FORMAT);
+}
+
+export function encodeFloat64(value: number) {
+  return bitsToLittleEndianBytes(encodeFloatBits(value, FLOAT64_FORMAT), 8);
+}
+
+export function decodeFloat64(rawBytes: readonly number[]) {
+  return decodeFloatBits(littleEndianBytesToBits(rawBytes), FLOAT64_FORMAT);
+}