Skip to content

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.

fix(asset): a load that lost the key still wrote to it

esengined0a1da3ffa4b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 a
component reaches the change tracker two ways — by definition for an explicit
`remove()` and for builtins on despawn, by component id for script components on
diff --git a/sdk/src/asset/AsyncCache.ts b/sdk/src/asset/AsyncCache.ts
index 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.ts
new file mode 100644
index 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();
+ }
+ });
+});