A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(asset): a load that lost the key still wrote to it
esengined0a1da3ffa4b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ee8cf033d..0e45dcf7a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -37,6 +37,20 @@ published separately; it ships inside the editor.### Fixed+- **A hot reload could leave an asset loading three times, or fail the reload with+ the old file's error.** `AsyncCache.invalidate()` aborts the in-flight load and+ drops its pending record, and hot reload asks for the same key again right away,+ so a second load registers under it. When the first one then finished it deleted+ `pending[key]` without checking whose record that had become — evicting the+ second load's, so the next request found nothing pending and started a third+ load of the same asset, with its own GPU allocation. On the failure path the+ dead request also wrote the failure cooldown that `invalidate()` had just+ cleared, so callers waiting on the new bytes were rejected with the old file's+ error. A timeout leaves the same window between the deadline firing and the+ request cleaning up after itself. A finishing load now touches the shared+ records only while it is still the one the key points at. A timeout that was+ never superseded still records its cooldown.+- **`Removed()` reported despawns from before anything was watching.** Losing acomponent reaches the change tracker two ways — by definition for an explicit`remove()` and for builtins on despawn, by component id for script components ondiff --git a/sdk/src/asset/AsyncCache.ts b/sdk/src/asset/AsyncCache.tsindex 4621b5566..56bc3b030 100644--- a/sdk/src/asset/AsyncCache.ts+++ b/sdk/src/asset/AsyncCache.ts@@ -52,7 +52,7 @@ export class AsyncCache<T> {if (timeout <= 0) {const result = await loaderPromise;if (!entry.aborted) this.cache_.set(key, result);- this.pending_.delete(key);+ this.clearPendingIfCurrent_(key, entry);return result;}@@ -81,7 +81,7 @@ export class AsyncCache<T> {// the fact, then cache (unless invalidate() aborted it in-flight).clearTimeout(timer);if (!entry.aborted) this.cache_.set(key, result);- this.pending_.delete(key);+ this.clearPendingIfCurrent_(key, entry);return result;})();@@ -90,17 +90,33 @@ export class AsyncCache<T> {try {return await entry.promise;} catch (err) {- this.pending_.delete(key);- if (err instanceof Error) {- this.failed_.set(key, { error: err, expiry: Date.now() + RuntimeConfig.assetFailureCooldown });- if (err.message.startsWith('AsyncCache timeout:')) {- log.warn('asset', err.message);+ // Only the request the map still points at may write the shared+ // records: if a newer load owns the key now, this failure is about+ // bytes nobody asked for any more.+ const current = this.pending_.get(key) === entry;+ if (current) {+ this.pending_.delete(key);+ if (err instanceof Error) {+ this.failed_.set(key, { error: err, expiry: Date.now() + RuntimeConfig.assetFailureCooldown });}}+ if (err instanceof Error && err.message.startsWith('AsyncCache timeout:')) {+ log.warn('asset', err.message);+ }throw err;}}+ /**+ * Drop this key's pending record only if it is still THIS request's. A load+ * that finishes after invalidate() replaced it would otherwise delete its+ * successor's record, and the next getOrLoad would start a third load of the+ * same asset instead of joining the second.+ */+ private clearPendingIfCurrent_(key: string, entry: PendingEntry<T>): void {+ if (this.pending_.get(key) === entry) this.pending_.delete(key);+ }+/** Release a value that was abandoned by a timeout; never throws upward. */private disposeAbandoned_(key: string, value: T): void {if (!this.dispose_) return;diff --git a/sdk/tests/AsyncCache-race.test.ts b/sdk/tests/AsyncCache-race.test.tsnew file mode 100644index 000000000..514d49598--- /dev/null+++ b/sdk/tests/AsyncCache-race.test.ts@@ -0,0 +1,200 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file AsyncCache-race.test.ts+ * @brief A load that finishes after it stopped being the current one must not+ * write the shared records.+ *+ * invalidate() aborts the in-flight load and drops its pending record,+ * and hot reload immediately asks for the same key again — so a second+ * load is registered under it. The first one then finished and deleted+ * `pending[key]` without checking whose record that now was, evicting+ * the second load's; the next request saw no pending entry and started a+ * THIRD load of the same asset. On the failure path it also wrote the+ * cooldown, so a dead request's error rejected callers waiting on bytes+ * that had already been replaced. A timeout leaves the same window.+ *+ * Every case here drives the interleaving by hand — no real timers on+ * the load path, no sleeps — so the ordering is the test, not the luck.+ */+import { describe, it, expect, vi, beforeEach } from 'vitest';+import { AsyncCache } from '../src/asset/AsyncCache';+import { RuntimeConfig } from '../src/defaults';++interface Deferred<T> {+ promise: Promise<T>;+ resolve: (value: T) => void;+ reject: (error: unknown) => void;+}++function deferred<T>(): Deferred<T> {+ let resolve!: (value: T) => void;+ let reject!: (error: unknown) => void;+ const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej; });+ return { promise, resolve, reject };+}++/** Let every already-queued microtask run before asserting. */+const settle = () => new Promise<void>(r => setTimeout(r, 0));++describe('a superseded load does not write the current one\'s records', () => {+ let cache: AsyncCache<string>;++ beforeEach(() => {+ cache = new AsyncCache<string>();+ });++ it('finishing after invalidate() leaves the newer load joinable', async () => {+ const first = deferred<string>();+ const second = deferred<string>();++ const a = cache.getOrLoad('k', () => first.promise);+ cache.invalidate('k');++ const loaderB = vi.fn(() => second.promise);+ const b = cache.getOrLoad('k', loaderB);++ first.resolve('old bytes');+ await expect(a).resolves.toBe('old bytes'); // the caller still gets its value+ await settle();++ // If the stale load evicted B's pending record, this starts a third load.+ const loaderC = vi.fn(() => deferred<string>().promise);+ const c = cache.getOrLoad('k', loaderC);+ expect(loaderC).not.toHaveBeenCalled();++ second.resolve('new bytes');+ await expect(b).resolves.toBe('new bytes');+ await expect(c).resolves.toBe('new bytes');+ expect(loaderB).toHaveBeenCalledTimes(1);+ });++ it('a superseded load does not cache its value', async () => {+ const first = deferred<string>();+ const a = cache.getOrLoad('k', () => first.promise);+ cache.invalidate('k');++ first.resolve('old bytes');+ await a;+ await settle();++ expect(cache.get('k')).toBeUndefined();+ });++ it('failing after invalidate() does not put the key in cooldown', async () => {+ const first = deferred<string>();+ const second = deferred<string>();++ const a = cache.getOrLoad('k', () => first.promise);+ cache.invalidate('k');+ const b = cache.getOrLoad('k', () => second.promise);++ first.reject(new Error('stale failure'));+ await expect(a).rejects.toThrow('stale failure');+ await settle();++ // The replacement must still be able to succeed, and a later request must+ // not be rejected with the dead load's error.+ const c = cache.getOrLoad('k', () => deferred<string>().promise);+ second.resolve('new bytes');+ await expect(b).resolves.toBe('new bytes');+ await expect(c).resolves.toBe('new bytes');+ expect(cache.get('k')).toBe('new bytes');+ });++ it('failing after invalidate() with no replacement leaves no cooldown', async () => {+ const first = deferred<string>();+ const a = cache.getOrLoad('k', () => first.promise);+ cache.invalidate('k');++ first.reject(new Error('stale failure'));+ await expect(a).rejects.toThrow('stale failure');+ await settle();++ // invalidate() cleared the failure record; the dead load must not restore it.+ const retry = deferred<string>();+ const b = cache.getOrLoad('k', () => retry.promise);+ retry.resolve('fresh');+ await expect(b).resolves.toBe('fresh');+ });++ it('the same window opens on timeout, not only on invalidate', async () => {+ vi.useFakeTimers();+ // The timeout's own cooldown would refuse the retry before it could reach+ // the window this is about; the window outlives the cooldown in real use.+ const original = RuntimeConfig.assetFailureCooldown;+ RuntimeConfig.assetFailureCooldown = 0;+ try {+ const first = deferred<string>();+ const a = cache.getOrLoad('k', () => first.promise, 10);+ const rejected = expect(a).rejects.toThrow('AsyncCache timeout');++ // Synchronous: fires the deadline without flushing microtasks, so the+ // request has aborted but its catch has not run. That is the window —+ // a retry registers under the key before the dead one cleans up.+ vi.advanceTimersByTime(20);++ const second = deferred<string>();+ const loaderB = vi.fn(() => second.promise);+ const b = cache.getOrLoad('k', loaderB, 0);+ expect(loaderB).toHaveBeenCalledTimes(1);++ await rejected; // now the dead request's catch runs+ first.resolve('late bytes'); // and its loader lands even later+ await vi.advanceTimersByTimeAsync(0); // settle() would hang on fake timers++ const loaderC = vi.fn(() => deferred<string>().promise);+ const c = cache.getOrLoad('k', loaderC, 0);+ expect(loaderC).not.toHaveBeenCalled();++ second.resolve('new bytes');+ await expect(b).resolves.toBe('new bytes');+ await expect(c).resolves.toBe('new bytes');+ } finally {+ RuntimeConfig.assetFailureCooldown = original;+ vi.useRealTimers();+ }+ });++ it('a timeout that was never superseded still writes the cooldown', async () => {+ vi.useFakeTimers();+ const original = RuntimeConfig.assetFailureCooldown;+ RuntimeConfig.assetFailureCooldown = 5000;+ try {+ const first = deferred<string>();+ const a = cache.getOrLoad('k', () => first.promise, 10);+ const rejected = expect(a).rejects.toThrow('AsyncCache timeout');+ await vi.advanceTimersByTimeAsync(20);+ await rejected;++ // Still inside the cooldown: the next request is refused without+ // touching the loader.+ const loader = vi.fn(() => deferred<string>().promise);+ await expect(cache.getOrLoad('k', loader, 0)).rejects.toThrow('AsyncCache timeout');+ expect(loader).not.toHaveBeenCalled();+ } finally {+ RuntimeConfig.assetFailureCooldown = original;+ vi.useRealTimers();+ }+ });++ it('a value abandoned by timeout is still released', async () => {+ vi.useFakeTimers();+ try {+ const dispose = vi.fn();+ const disposing = new AsyncCache<string>(dispose);+ const first = deferred<string>();++ const a = disposing.getOrLoad('k', () => first.promise, 10);+ const rejected = expect(a).rejects.toThrow('AsyncCache timeout');+ await vi.advanceTimersByTimeAsync(20);+ await rejected;++ first.resolve('late bytes');+ await vi.advanceTimersByTimeAsync(0);+ expect(dispose).toHaveBeenCalledWith('late bytes');+ } finally {+ vi.useRealTimers();+ }+ });+});