@adobe/ecs 0.0.0-stage → 0.2.0

package/dist/implementation/world/reclaim.js

@@ -0,0 +1,176 @@
+import { bump, noShared, release } from './archetype.js';
+import { createArrivals, membershipWord } from './arrivals.js';
+import { forgetTexts } from './layout-directory.js';
+import { holdShared, releaseShared, sweepShared } from './shared.js';
+// Reclaiming archetypes of shared values (design.md, "Reclaiming"): one found empty at a sync point is reclaimed once
+// it stayed empty for `emptyFor` sync points and every joined thread finalized past it. Reclaimed, it leaves the
+// world's lookup by key and systems' match lists, lets go of its arrays and of each value only it held, and the edges
+// cached to and from it are cleared. It waits in its component set's pool, under its id, until an archetype of those
+// components and other values is wanted: then it's reused for them, its id and storages kept, so what's cached by id of
+// its components stays true, and everything that read its values reads them again.
+/**
+ * Sync points an archetype stays empty before it's reclaimed, so one emptied and filled again soon, as a cell is while
+ * entities cross it, isn't reclaimed and reused over and over: a reclaim and reuse costs a sync point about 1.7 µs
+ * (perf.md), and each walker leaves at most this many empty behind it. A tail ends before the second sync point after
+ * the one it reads, so none reads a reclaimed archetype's rows.
+ */
+export const emptyFor = 8;
+/** The component set an archetype's pool is found by: its components, whatever its values. */
+const poolKeyOf = (components) => components.join(",");
+/** The membership log's length past which it's trimmed by half: a reader further behind reads every archetype again. */
+const membershipLog = 4096;
+/** Notes a change of archetype's membership, reclaimed or reused, for systems' match lists and joined threads. */
+const noteMembership = (state, archetype) => {
+    const { membership } = state;
+    membership.log.push(archetype);
+    state.reshapes++;
+    if (membership.log.length > membershipLog) {
+        const dropped = membership.log.length >> 1;
+        membership.log.splice(0, dropped);
+        membership.base += dropped;
+    }
+    if (state.memory.shared) {
+        const ring = state.arrivalRing ??= createArrivals(state.memory);
+        Atomics.add(ring.control, membershipWord, 1);
+    }
+};
+/** Archetypes whose rows left in the sync point just applied that are now empty, with shared values, as candidates. */
+export const noteEmptied = (state) => {
+    const { plan, archetypes } = state;
+    for (let entry = 0; entry < plan.count; entry++) {
+        const from = plan.from[entry];
+        if (from < 0)
+            continue;
+        const archetype = archetypes[from];
+        if (archetype.shared === noShared || archetype.emptiedAt >= 0 || archetype.count !== 0 || archetype.reclaimed)
+            continue;
+        archetype.emptiedAt = state.syncs;
+        archetype.emptiedTick = state.tick;
+        state.emptied.push(archetype);
+    }
+};
+/**
+ * Whether every joined thread acknowledged its stop lists through the sync point of `tick`, an archetype's last with
+ * rows: a stop list names its stops' archetypes, whose values the thread reads by id as it finalizes them.
+ */
+const stopsSettledThrough = (state, tick) => {
+    for (const channel of state.channels) {
+        for (const block of channel.stops.written)
+            if (((block.sync - (tick >>> 0)) | 0) <= 0 && !block.acknowledged)
+                return false;
+    }
+    return true;
+};
+/**
+ * At the end of a sync point: reclaims the candidates that stayed empty long enough, keeps those that may be later,
+ * drops those filled again, then drops the values interned since the last sync point that nothing came to hold.
+ */
+export const reclaimEmptied = (state) => {
+    const { emptied } = state;
+    let kept = 0;
+    for (let k = 0; k < emptied.length; k++) {
+        const archetype = emptied[k];
+        if (archetype.reclaimed)
+            continue;
+        if (archetype.count > 0) {
+            archetype.emptiedAt = -1;
+            continue;
+        }
+        // An archetype holding a joined thread's objects is kept: its rows' moves are in that thread's log, by its id.
+        if (state.syncs - archetype.emptiedAt < emptyFor || archetype.logs !== null || !stopsSettledThrough(state, archetype.emptiedTick)) {
+            emptied[kept++] = archetype;
+            continue;
+        }
+        reclaim(state, archetype);
+    }
+    emptied.length = kept;
+    for (const values of state.sharedList)
+        if (values.fresh.length > 0)
+            sweepShared(values);
+};
+/** Clears each edge cached to or from an archetype, removing it from the other end's. */
+const clearEdges = (archetype) => {
+    const { edges } = archetype;
+    if (edges === null)
+        return;
+    archetype.edges = null;
+    for (const edge of edges) {
+        if (Reflect.get(edge.holder, edge.key) !== undefined)
+            Reflect.set(edge.holder, edge.key, edge.cleared);
+        for (const end of edge.ends) {
+            if (end === archetype || end.edges === null)
+                continue;
+            const at = end.edges.indexOf(edge);
+            if (at >= 0)
+                end.edges.splice(at, 1);
+        }
+    }
+};
+/**
+ * Notes an edge `holder[key]` cached between archetypes `from` and `to`, so it's cleared, set to `cleared`, once either
+ * is reclaimed. Only edges with an end of shared values are kept, so worlds without them keep none.
+ */
+export const noteEdge = (holder, key, cleared, from, to) => {
+    const toShared = to !== from && to.shared !== noShared;
+    if (from.shared === noShared && !toShared)
+        return;
+    const ends = from.shared === noShared ? [to] : toShared ? [from, to] : [from];
+    const edge = { holder, key, cleared, ends };
+    for (const end of ends)
+        (end.edges ??= []).push(edge);
+};
+const reclaim = (state, archetype) => {
+    archetype.reclaimed = true;
+    archetype.emptiedAt = -1;
+    state.archetypeByKey.delete(archetype.key);
+    clearEdges(archetype);
+    archetype.adding.length = archetype.removing.length = archetype.sharing.length = 0;
+    release(state.memory, archetype);
+    state.gpu?.forget(archetype);
+    const pool = state.pools.get(poolKeyOf(archetype.components));
+    if (pool === undefined)
+        state.pools.set(poolKeyOf(archetype.components), [archetype]);
+    else
+        pool.push(archetype);
+    for (const id of archetype.components) {
+        const number = archetype.shared[id];
+        const values = state.shared[id];
+        if (number !== undefined && values !== undefined)
+            releaseShared(values, number);
+    }
+    // Listed, so the record is written flagged; its version moved on as its arrays went.
+    bump(archetype);
+    noteMembership(state, archetype);
+};
+/**
+ * A reclaimed archetype of `components` reused for the shared values `held` holds, their layouts and texts by
+ * component id; null where its component set's pool is empty.
+ */
+export const reuseArchetype = (state, key, components, held, layouts, texts) => {
+    const archetype = state.pools.get(poolKeyOf(components))?.pop();
+    if (archetype === undefined)
+        return null;
+    archetype.reclaimed = false;
+    archetype.generation++;
+    archetype.key = key;
+    archetype.shared = held.length === 0 ? noShared : held;
+    archetype.texts = texts;
+    for (const storage of archetype.storages) {
+        const layout = layouts[storage.component];
+        if (layout !== undefined)
+            storage.layout = layout;
+    }
+    for (const id of components) {
+        const number = held[id];
+        const values = state.shared[id];
+        if (number !== undefined && values !== undefined)
+            holdShared(values, number);
+    }
+    if (state.directory !== null)
+        forgetTexts(state.directory, archetype);
+    // Its values changed: what read them by its version reads them again, and the directory writes its record.
+    bump(archetype);
+    noteMembership(state, archetype);
+    return archetype;
+};
+//# sourceMappingURL=reclaim.js.map

package/dist/implementation/world/reclaim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reclaim.js","sourceRoot":"","sources":["../../../src/implementation/world/reclaim.ts"],"names":[],"mappings":"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"}

package/dist/implementation/world/reductions.d.ts

@@ -0,0 +1,33 @@
+import type { Reduction } from '../../interface/resource/reduction.js';
+import type { Resolved } from '../../interface/system/declaration.js';
+import type { Layout, Path, View } from '../../interface/registry/layout.js';
+import { type Key, type State } from './state.js';
+/** A resource a system reduces into: its operator, and the scalar leaves of its value. */
+export type ReductionTarget = {
+    readonly key: Key;
+    readonly operator: Reduction;
+    readonly leaves: readonly {
+        readonly path: Path;
+        readonly view: View;
+        readonly boolean: boolean;
+    }[];
+};
+/**
+ * The resources a system reduces into, with their operators, their `reduce` traits, and their layouts' leaves.
+ * Creating the system checked each has a trait, which registering the resource checked against its schema, so a throw
+ * here is an invariant broken.
+ */
+export declare const reductionTargets: (state: State, name: string, declaration: Resolved) => readonly ReductionTarget[];
+/** The resources a system `name` reduces into, by `layoutFor`, each resource's layout. */
+export declare const reductionTargetsOf: (layoutFor: (key: Key) => Layout | undefined, name: string, declaration: Resolved) => readonly ReductionTarget[];
+/** Each operator's identity, as a fold starts from it, and what an empty fold gives. */
+export declare const identityOf: (operator: Reduction) => number;
+/** One step of a fold, with JS semantics. Partials are f64; a result rounds or wraps once, when it's stored. */
+export declare const combine: (operator: Reduction, a: number, b: number) => number;
+/** The value a fold contributes to a leaf: booleans as 0 or 1. */
+export declare const contributed: (value: unknown, path: Path) => number;
+/**
+ * Writes a target's folded leaves, `values[offset + i]` for leaf `i`, and stamps the resource changed at `tick` only
+ * if a stored leaf differs, so readers filtering on it run only when it does.
+ */
+export declare const writeReduction: (state: State, target: ReductionTarget, values: ArrayLike<number>, offset: number, tick: number) => void;

package/dist/implementation/world/reductions.js

@@ -0,0 +1,92 @@
+import { isReduction } from '../../interface/registry/reduction.js';
+import { stampChanged } from './archetype.js';
+import { readCell, writeCell } from './cells.js';
+import { resourceCell } from './resources.js';
+import { idOf } from './state.js';
+import { declarationOf, labelOf } from '../../interface/registry/index.js';
+const bitwise = new Set(["&", "|", "^"]);
+/**
+ * The resources a system reduces into, with their operators, their `reduce` traits, and their layouts' leaves.
+ * Creating the system checked each has a trait, which registering the resource checked against its schema, so a throw
+ * here is an invariant broken.
+ */
+export const reductionTargets = (state, name, declaration) => reductionTargetsOf(key => state.layouts[idOf(state, key)], name, declaration);
+/** The resources a system `name` reduces into, by `layoutFor`, each resource's layout. */
+export const reductionTargetsOf = (layoutFor, name, declaration) => {
+    const reduce = declaration.resources?.reduce;
+    if (reduce === undefined)
+        return [];
+    return reduce.map((key) => {
+        const operator = declarationOf(key)?.reduce;
+        if (!isReduction(operator))
+            throw new Error(`System "${name}" reduces "${labelOf(key)}" with "${labelOf(operator)}", which isn't an operator.`);
+        const layout = layoutFor(key);
+        if (layout?.kind !== "linear")
+            throw new Error(`System "${name}" reduces "${labelOf(key)}", which isn't stored in linear memory.`);
+        const leaves = layout.leaves.map(leaf => ({ path: leaf.path, view: leaf.view, boolean: leaf.scalar === "boolean" }));
+        if (leaves.some(leaf => leaf.boolean) && !bitwise.has(operator)) {
+            throw new Error(`System "${name}" reduces "${labelOf(key)}", which has boolean values, with "${operator}"; booleans reduce with "&", "|" or "^".`);
+        }
+        return { key, operator, leaves };
+    });
+};
+/** Each operator's identity, as a fold starts from it, and what an empty fold gives. */
+export const identityOf = (operator) => {
+    switch (operator) {
+        case "+":
+        case "|":
+        case "^": return 0;
+        case "*": return 1;
+        case "&": return -1;
+        case "min": return Infinity;
+        case "max": return -Infinity;
+    }
+};
+/** One step of a fold, with JS semantics. Partials are f64; a result rounds or wraps once, when it's stored. */
+export const combine = (operator, a, b) => {
+    switch (operator) {
+        case "+": return a + b;
+        case "*": return a * b;
+        case "&": return a & b;
+        case "|": return a | b;
+        case "^": return a ^ b;
+        case "min": return Math.min(a, b);
+        case "max": return Math.max(a, b);
+    }
+};
+const integerRange = {
+    u8: [0, 255], i32: [-(2 ** 31), 2 ** 31 - 1], u32: [0, 2 ** 32 - 1],
+};
+/** A folded leaf in its stored form: a boolean, or an empty `min` or `max` of integers as the type's own extreme. */
+const stored = (value, operator, view, boolean) => {
+    if (boolean)
+        return (value & 1) !== 0;
+    const range = integerRange[view];
+    const empty = (operator === "min" && value === Infinity) || (operator === "max" && value === -Infinity);
+    return range !== undefined && empty ? (value > 0 ? range[1] : range[0]) : value;
+};
+const withLeaf = (value, path, leaf) => {
+    const [first, ...rest] = path;
+    if (first === undefined)
+        return leaf;
+    const copy = Array.isArray(value) ? [...value] : { ...Object(value) };
+    Reflect.set(Object(copy), first, withLeaf(Reflect.get(Object(value), first), rest, leaf));
+    return copy;
+};
+const leafOf = (value, path) => path.reduce((item, key) => Reflect.get(Object(item), key), value);
+/** The value a fold contributes to a leaf: booleans as 0 or 1. */
+export const contributed = (value, path) => Number(leafOf(value, path));
+/**
+ * Writes a target's folded leaves, `values[offset + i]` for leaf `i`, and stamps the resource changed at `tick` only
+ * if a stored leaf differs, so readers filtering on it run only when it does.
+ */
+export const writeReduction = (state, target, values, offset, tick) => {
+    const { storage, row } = resourceCell(state, target.key);
+    const before = readCell(storage, row);
+    const next = target.leaves.reduce((value, leaf, i) => withLeaf(value, leaf.path, stored(values[offset + i] ?? NaN, target.operator, leaf.view, leaf.boolean)), before);
+    writeCell(storage, row, next);
+    const after = readCell(storage, row);
+    if (target.leaves.some(leaf => !Object.is(leafOf(before, leaf.path), leafOf(after, leaf.path))))
+        stampChanged(storage, row, tick);
+};
+//# sourceMappingURL=reductions.js.map

package/dist/implementation/world/reductions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reductions.js","sourceRoot":"","sources":["../../../src/implementation/world/reductions.ts"],"names":[],"mappings":"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"}

package/dist/implementation/world/register.d.ts

@@ -0,0 +1,64 @@
+import type { Leaf } from '../../interface/system/leaf.js';
+import { type Definition } from '../../interface/registry/index.js';
+import { type Runner } from './runner.js';
+import { type Schedule } from '../../interface/registry/schedule.js';
+import { type Key, type State } from './state.js';
+/** What a registration still has to do asynchronously: add resources, then load kernels; `rollback` undoes it if that fails. */
+/**
+ * `ticked`: components the new systems filter on or hold GPU copies of, which must keep ticks before they run;
+ * `resident`: those they hold GPU copies of.
+ */
+export type Registration = {
+    readonly resources: readonly Key[];
+    readonly ticked: readonly number[];
+    readonly resident: readonly number[];
+    readonly kernels: readonly Runner[];
+    readonly rollback: () => void;
+};
+export type Registrar = {
+    /** Validates and records a system with all its members. Throws without recording anything on failure. */
+    readonly register: (system: Definition) => Registration;
+    /** A registered system's schedule; undefined for one not registered, or holding a system forgotten since. */
+    readonly registered: (system: Definition) => Schedule | undefined;
+    /** A leaf's runner, or one that runs nothing for a leaf not registered, as a system removed during a run is. */
+    readonly runnerOf: (leaf: Leaf) => Runner;
+    /**
+     * Forgets systems, as removing them does: their schedules, and leaves' runners, which no run calls again once this
+     * returns. Returns what releases what the runners held, for once no run in progress uses them.
+     */
+    readonly forget: (systems: readonly Definition[]) => () => void;
+    /** Every system in a tree, the root included. */
+    readonly systemsOf: (root: Definition) => readonly Definition[];
+    /** A kernel runner's index, as workers know it. */
+    readonly kernelIndexOf: (runner: Runner) => number;
+    /** Every registered kernel runner. */
+    readonly kernels: () => readonly Runner[];
+    /** Rebuilds the runners of `kernel: "gpu"` systems for the world's current device, or for the CPU without one; returns them to load. */
+    readonly placeGpuKernels: () => readonly Runner[];
+    /**
+     * Why a joined thread that imported the systems of ids `imported` can't claim `threads`: a registered system on one
+     * it didn't import, or one without an id, or naming a key without one, or one that can't run on a joined thread;
+     * null when every one can run there.
+     */
+    readonly crossing: (threads: readonly string[], imported: ReadonlySet<string>) => string | null;
+    /** Places each registered system again, as claims were made or released: on its joined thread, or here. */
+    readonly place: () => void;
+    /**
+     * Registers a forgotten observer leaf again at once, with the runner it had, run again as a new runner would be:
+     * registering it before found every key and resource it names, so nothing is left to do asynchronously. False when
+     * it can't, as for one never registered, or whose runner a run in progress may still read as removed.
+     */
+    readonly reregister: (leaf: Leaf) => boolean;
+    /** For tests of what a world holds: how many schedules, runners and kernel indexes it keeps. */
+    readonly sizes: () => {
+        readonly schedules: number;
+        readonly runners: number;
+        readonly kernels: number;
+    };
+};
+/**
+ * What a world keeps of each system it registered lives as long as the system's value: schedules and runners by
+ * system, held weakly, so a system nothing references any more is collected, and with it its runner, its command
+ * buffers and its `lastRun`. What a runner holds beyond its JS values is released once its system is collected.
+ */
+export declare const createRegistrar: (state: State) => Registrar;