mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +00:00
Serialize engine and shell transitions through the scene host
Move engine request ordering and the single rollback decision into the scene host. Run handoff, renderer release, candidate acquisition, attachment, restoration and settling in one transaction. Pass that transaction to nested parts so unrelated calls wait without putting nested work behind itself. Keep the engine-switch entry point as a delegating adapter. Route direct shell attachment and detachment through the same host and remove the shell queue. Serialize late part registration with attachment and release. Keep failed-attachment cleanup and renderer release inside the transaction, including failed restoration. Replacement applications share the transition owner with fresh parts, and retired applications release their part registry. A shell used alone creates its own scene host. Preserve Cesium's picker and history ordering, single recovery, retained layer session, cockpit restoration, hidden-tab settling and parked-renderer policy. Navara keeps the same behavior. No user-visible change is intended on either engine. Keep the existing behavioral assertions and cover concurrent operations, failed cleanup followed by recovery, retired transaction handles, replacement startup failure and parked expiry during a switch. All eleven coupling counts remain unchanged; none fell or grew. Renderer lines remain 0 and 189, external Cesium import files 3, viewer lines 891, Navara kind checks 1, engine-sniff calls 0, extension reads 3, ground passes 1, SDK loads 3, screen-handler files 4 and engine-name lines 32. Checked on the keyless production build: the engine, Director and layer handoff switches, app-once, and the rapid, hidden-tab, context-loss, parked-release, failure-matrix and soak scenarios pass.
This commit is contained in:
1 parent
c1e857f798
commit
7f3754d812
23 files changed
+771
-287
No files matched your search
+277
-25
@@ -1,8 +1,11 @@
|
||||
import { ENGINE_CHOICES } from './engineChoice.js';
|
||||
|
||||
// The page's scene host: the application is created once per page, and only
|
||||
// the parts bound to a globe engine (its viewer, canvas, camera and frames)
|
||||
// detach from the outgoing engine and attach to the incoming one.
|
||||
//
|
||||
// A part is `{ name, attachScene(scene, { signal, defer }), detachScene({ handoff }) }`.
|
||||
// A part is `{ name, attachScene(scene, { signal, defer, transaction }),
|
||||
// detachScene({ handoff }, transaction) }`.
|
||||
// Parts attach in registration order and detach in reverse. `signal` belongs
|
||||
// to one attachment: it aborts when that attachment detaches, so work a part
|
||||
// started for one engine never lands on the next. `defer(cleanup)` registers
|
||||
@@ -18,9 +21,14 @@ export class SceneSwitchingError extends Error {
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {{onError?: (error: unknown, part: string) => void}} [options]
|
||||
* `transitionHost` shares the queue with a replacement application's fresh
|
||||
* parts. Transactions are valid only while their enclosing work runs.
|
||||
* @param {{onError?: (error: unknown, part: string) => void, transitionHost?: object}} [options]
|
||||
*/
|
||||
export function createSceneHost({ onError = null } = {}) {
|
||||
export function createSceneHost({
|
||||
onError = null,
|
||||
transitionHost = null,
|
||||
} = {}) {
|
||||
const parts = [];
|
||||
const listeners = new Set();
|
||||
let state = 'detached';
|
||||
@@ -29,6 +37,8 @@ export function createSceneHost({ onError = null } = {}) {
|
||||
let attachment = null;
|
||||
// The attach or detach under way, so a later call waits for it.
|
||||
let transition = Promise.resolve();
|
||||
const active = new Set();
|
||||
let scheduled = 0;
|
||||
|
||||
function publish() {
|
||||
for (const listener of [...listeners]) {
|
||||
@@ -40,12 +50,13 @@ export function createSceneHost({ onError = null } = {}) {
|
||||
}
|
||||
}
|
||||
|
||||
async function attachPart(part, target, current) {
|
||||
async function attachPart(part, target, current, transaction) {
|
||||
const defers = [];
|
||||
const entry = { part, defers };
|
||||
current.attached.push(entry);
|
||||
await part.attachScene?.(target, {
|
||||
signal: current.controller.signal,
|
||||
transaction,
|
||||
defer(cleanup) {
|
||||
if (typeof cleanup !== 'function')
|
||||
throw new TypeError('A scene part defers a function');
|
||||
@@ -55,7 +66,7 @@ export function createSceneHost({ onError = null } = {}) {
|
||||
current.controller.signal.throwIfAborted();
|
||||
}
|
||||
|
||||
async function detachEntry(entry, options, errors) {
|
||||
async function detachEntry(entry, options, errors, transaction) {
|
||||
while (entry.defers.length) {
|
||||
const cleanup = entry.defers.pop();
|
||||
try {
|
||||
@@ -66,18 +77,18 @@ export function createSceneHost({ onError = null } = {}) {
|
||||
}
|
||||
}
|
||||
try {
|
||||
await entry.part.detachScene?.(options);
|
||||
await entry.part.detachScene?.(options, transaction);
|
||||
} catch (error) {
|
||||
errors.push(error);
|
||||
onError?.(error, entry.part.name);
|
||||
}
|
||||
}
|
||||
|
||||
async function release(current, options) {
|
||||
async function release(current, options, transaction) {
|
||||
current.controller.abort();
|
||||
const errors = [];
|
||||
while (current.attached.length)
|
||||
await detachEntry(current.attached.pop(), options, errors);
|
||||
await detachEntry(current.attached.pop(), options, errors, transaction);
|
||||
return errors;
|
||||
}
|
||||
|
||||
@@ -88,29 +99,59 @@ export function createSceneHost({ onError = null } = {}) {
|
||||
return () => listeners.delete(listener);
|
||||
}
|
||||
|
||||
function queue(work) {
|
||||
const run = transition.then(work, work);
|
||||
transition = run.catch(() => {});
|
||||
return run;
|
||||
// Nested steps receive the current transaction explicitly. Unrelated calls
|
||||
// always wait, even while a part is awaiting attachment or release.
|
||||
function run(work, transaction, immediate = false) {
|
||||
if (transitionHost) return transitionHost.run(work, transaction, immediate);
|
||||
if (transaction && active.has(transaction)) return work(transaction);
|
||||
const execute = async () => {
|
||||
const current = Object.freeze({ host });
|
||||
active.add(current);
|
||||
try {
|
||||
return await work(current);
|
||||
} finally {
|
||||
active.delete(current);
|
||||
scheduled--;
|
||||
}
|
||||
};
|
||||
const idle = scheduled++ === 0;
|
||||
const previous = transition;
|
||||
let start;
|
||||
const result = new Promise((resolve, reject) => {
|
||||
start = () => execute().then(resolve, reject);
|
||||
});
|
||||
transition = result.catch(() => {});
|
||||
if (immediate && idle) start();
|
||||
else previous.then(start, start);
|
||||
return result;
|
||||
}
|
||||
|
||||
return Object.freeze({
|
||||
const host = Object.freeze({
|
||||
run,
|
||||
createSwitcher: (options) =>
|
||||
createSceneRequests({
|
||||
...options,
|
||||
run: (work) => run(work, null, true),
|
||||
}),
|
||||
/**
|
||||
* Add a part. While a scene is attached the part attaches to it now, and
|
||||
* the returned promise settles with that attachment.
|
||||
*/
|
||||
register(part) {
|
||||
register(part, transaction) {
|
||||
if (!part || typeof part !== 'object' || typeof part.name !== 'string')
|
||||
throw new TypeError('A scene part needs a name');
|
||||
if (parts.includes(part)) return Promise.resolve();
|
||||
parts.push(part);
|
||||
if (state !== 'attached' || !attachment) return Promise.resolve();
|
||||
return attachPart(part, scene, attachment);
|
||||
return run(async (transaction) => {
|
||||
if (state !== 'attached' || !attachment) return;
|
||||
if (attachment.attached.some((entry) => entry.part === part)) return;
|
||||
return attachPart(part, scene, attachment, transaction);
|
||||
}, transaction);
|
||||
},
|
||||
/** Attach every part to `target`, in order. A failure detaches the parts it attached. */
|
||||
attach(target) {
|
||||
attach(target, transaction) {
|
||||
if (!target) throw new TypeError('Attach needs a scene');
|
||||
return queue(async () => {
|
||||
return run(async (transaction) => {
|
||||
if (state !== 'detached')
|
||||
throw new Error(`Cannot attach a scene while ${state}`);
|
||||
state = 'attaching';
|
||||
@@ -120,10 +161,10 @@ export function createSceneHost({ onError = null } = {}) {
|
||||
publish();
|
||||
try {
|
||||
for (const part of [...parts])
|
||||
await attachPart(part, target, current);
|
||||
await attachPart(part, target, current, transaction);
|
||||
} catch (error) {
|
||||
// The parts keep their own handoff choice; `failed` names why.
|
||||
const errors = await release(current, { failed: true });
|
||||
const errors = await release(current, { failed: true }, transaction);
|
||||
attachment = null;
|
||||
scene = null;
|
||||
state = 'detached';
|
||||
@@ -138,21 +179,21 @@ export function createSceneHost({ onError = null } = {}) {
|
||||
state = 'attached';
|
||||
publish();
|
||||
return target;
|
||||
});
|
||||
}, transaction);
|
||||
},
|
||||
/**
|
||||
* Detach every attached part, in reverse. Detaching nothing is a no-op;
|
||||
* a part that fails to detach does not stop the others.
|
||||
*/
|
||||
detach(options = {}) {
|
||||
return queue(async () => {
|
||||
detach(options = {}, transaction) {
|
||||
return run(async (transaction) => {
|
||||
if (state === 'detached' || !attachment) return;
|
||||
const current = attachment;
|
||||
state = 'detaching';
|
||||
publish();
|
||||
let errors;
|
||||
try {
|
||||
errors = await release(current, options);
|
||||
errors = await release(current, options, transaction);
|
||||
} finally {
|
||||
attachment = null;
|
||||
scene = null;
|
||||
@@ -161,7 +202,15 @@ export function createSceneHost({ onError = null } = {}) {
|
||||
}
|
||||
if (errors.length)
|
||||
throw new AggregateError(errors, 'Scene parts could not detach');
|
||||
});
|
||||
}, transaction);
|
||||
},
|
||||
/** Release a retired application's part registry after its resources. */
|
||||
dispose(transaction) {
|
||||
return run(async (transaction) => {
|
||||
await host.detach({}, transaction);
|
||||
parts.length = 0;
|
||||
listeners.clear();
|
||||
}, transaction);
|
||||
},
|
||||
/** The attached scene, or null. */
|
||||
current: () => (state === 'attached' ? scene : null),
|
||||
@@ -200,4 +249,207 @@ export function createSceneHost({ onError = null } = {}) {
|
||||
});
|
||||
},
|
||||
});
|
||||
return host;
|
||||
}
|
||||
|
||||
/**
|
||||
* Drive engine switches for one page session.
|
||||
*
|
||||
* A failed attempt rolls back to the last engine that actually started
|
||||
* (never to the one that just failed) and, when that recovery fails too,
|
||||
* leaves the page without an engine but still able to take the next request. A page lifetime abort (pagehide) stops the
|
||||
* machine: nothing starts after it.
|
||||
*
|
||||
* @param {object} options
|
||||
* @param {string} options.kind The engine already running.
|
||||
* @param {() => string} options.requested The engine the address asks for now.
|
||||
* @param {AbortSignal} options.signal The page lifetime.
|
||||
* @param {(from: string, to: string, change: {visit: boolean}) => Promise<void>} options.leave
|
||||
* Hand the session off from the running engine and release that engine.
|
||||
* @param {(kind: string, attempt: {recovery: boolean}) => Promise<void>} options.enter
|
||||
* Start an engine on the retained session. It resolves once the engine runs
|
||||
* with the session attached; when it rejects it has already released what
|
||||
* it started.
|
||||
* @param {{select: (from: ?string) => *, commit: (token: *, kind: string) => void, restore: (kind: string) => void}} options.address
|
||||
* @param {(state: {failed: boolean}) => Promise<void>|void} [options.settle] Runs
|
||||
* once the address is reconciled, before the machine reports idle.
|
||||
* @param {(kind: string) => void} [options.remember] Store a picked engine.
|
||||
* @param {(state: object) => void} [options.onChange]
|
||||
* @param {(error: unknown, outcome: {recovered: boolean, kind: ?string}) => void} [options.onFailure]
|
||||
*/
|
||||
function createSceneRequests({
|
||||
run,
|
||||
kind,
|
||||
requested,
|
||||
signal,
|
||||
leave,
|
||||
enter,
|
||||
address,
|
||||
settle,
|
||||
remember,
|
||||
onChange,
|
||||
onFailure,
|
||||
}) {
|
||||
// The engine whose session is live, null while none is.
|
||||
let current = kind;
|
||||
// The engine attached to the application or starting to attach: what a
|
||||
// history visit would leave.
|
||||
let live = kind;
|
||||
// The last engine that started successfully: the rollback target.
|
||||
let working = kind;
|
||||
let failed = false;
|
||||
let busy = false;
|
||||
// Every request (select or address visit) bumps this; a visit also bumps
|
||||
// `visits`.
|
||||
let requests = 0;
|
||||
let visits = 0;
|
||||
let queued = null;
|
||||
// The pick being started, held here rather than in the address: a visit
|
||||
// made meanwhile retires it and leaves every entry as it was.
|
||||
let pending = null;
|
||||
let running = null;
|
||||
|
||||
const state = () =>
|
||||
Object.freeze({
|
||||
kind: current ?? working,
|
||||
engine: live,
|
||||
busy,
|
||||
failed,
|
||||
});
|
||||
const publish = () => onChange?.(state());
|
||||
|
||||
function prepare(next) {
|
||||
pending = { to: next, token: address.select(current) };
|
||||
}
|
||||
|
||||
/** The picker's choice. While a switch runs it is queued, not dropped. */
|
||||
function select(next) {
|
||||
if (!ENGINE_CHOICES.includes(next) || signal.aborted) return null;
|
||||
requests++;
|
||||
if (busy) {
|
||||
queued = next;
|
||||
return running;
|
||||
}
|
||||
if (next === current) return null;
|
||||
prepare(next);
|
||||
return start();
|
||||
}
|
||||
|
||||
/** The address changed (history visit) or should be checked again. */
|
||||
function reconcile() {
|
||||
if (signal.aborted) return Promise.resolve();
|
||||
requests++;
|
||||
visits++;
|
||||
// A later visit supersedes a pick queued or starting before it.
|
||||
queued = null;
|
||||
pending = null;
|
||||
return busy ? running : start();
|
||||
}
|
||||
|
||||
function start() {
|
||||
busy = true;
|
||||
publish();
|
||||
running = run(async (transaction) => {
|
||||
try {
|
||||
await drive(transaction);
|
||||
} catch (error) {
|
||||
onFailure?.(error, { recovered: current !== null, kind: current });
|
||||
} finally {
|
||||
busy = false;
|
||||
running = null;
|
||||
publish();
|
||||
}
|
||||
});
|
||||
return running;
|
||||
}
|
||||
|
||||
async function drive(transaction) {
|
||||
for (;;) {
|
||||
await reconcileAddress(transaction);
|
||||
if (signal.aborted) return;
|
||||
const seen = requests;
|
||||
try {
|
||||
await settle?.({ failed }, transaction);
|
||||
} catch (error) {
|
||||
// Revealing the globe is cosmetic; the engine runs either way.
|
||||
console.error('The globe switch could not settle:', error);
|
||||
}
|
||||
if (signal.aborted || seen === requests) return;
|
||||
}
|
||||
}
|
||||
|
||||
async function reconcileAddress(transaction) {
|
||||
let handled = null;
|
||||
for (;;) {
|
||||
if (signal.aborted) return;
|
||||
if (queued !== null) {
|
||||
const next = queued;
|
||||
queued = null;
|
||||
if (next !== current) prepare(next);
|
||||
else pending = null;
|
||||
}
|
||||
const target = pending?.to ?? requested();
|
||||
if (target === current) return;
|
||||
// After a failed recovery, wait for the person's next request instead
|
||||
// of retrying the same address in a loop.
|
||||
if (failed && handled === requests) return;
|
||||
handled = requests;
|
||||
await attempt(target, transaction);
|
||||
}
|
||||
}
|
||||
|
||||
async function attempt(target, transaction) {
|
||||
const visitsAtStart = visits;
|
||||
const visit = pending?.to !== target;
|
||||
publish();
|
||||
try {
|
||||
if (current !== null) {
|
||||
const from = current;
|
||||
try {
|
||||
await leave(from, target, { visit }, transaction);
|
||||
} finally {
|
||||
current = null;
|
||||
}
|
||||
}
|
||||
if (signal.aborted) return;
|
||||
live = target;
|
||||
await enter(target, { recovery: false }, transaction);
|
||||
if (signal.aborted) return;
|
||||
current = working = target;
|
||||
failed = false;
|
||||
if (!visit && pending?.to === target) {
|
||||
address.commit(pending.token, target);
|
||||
remember?.(target);
|
||||
}
|
||||
pending = null;
|
||||
} catch (error) {
|
||||
if (signal.aborted) return;
|
||||
pending = null;
|
||||
// A failed pick never touched the address. A failed visit points its
|
||||
// entry at the working engine, unless the person has since moved on.
|
||||
if (visit && visits === visitsAtStart && requested() === target)
|
||||
address.restore(working);
|
||||
if (working === target) {
|
||||
live = null;
|
||||
failed = true;
|
||||
onFailure?.(error, { recovered: false, kind: null });
|
||||
return;
|
||||
}
|
||||
live = working;
|
||||
try {
|
||||
await enter(working, { recovery: true }, transaction);
|
||||
if (signal.aborted) return;
|
||||
current = working;
|
||||
failed = false;
|
||||
onFailure?.(error, { recovered: true, kind: working });
|
||||
} catch (recoveryError) {
|
||||
if (signal.aborted) return;
|
||||
live = null;
|
||||
failed = true;
|
||||
onFailure?.(recoveryError, { recovered: false, kind: null });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return Object.freeze({ select, reconcile, state });
|
||||
}
|
||||
Reference in new issue
Block a user