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.

2.4 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    wasmScratch.ts
 * @brief   Exception-safe transient allocation on the WASM heap.
 *
 * @details The boundary repeatedly does `ptr = _malloc(n); …write/​call…; _free(ptr)`.
 *          When the intervening work throws (a validation error, a module
 *          abort, an out-of-bounds write), the `_free` is skipped and the WASM
 *          heap leaks permanently. {@link withScratch} makes that structurally
 *          impossible: every allocation taken from its `alloc` callback is freed
 *          when the callback returns OR throws.
 *
 *          The callback MUST be synchronous — do not `await` between alloc and
 *          the implicit free, or the buffer is freed while still in use.
 */

/** Minimal slice of an emscripten module: just the heap allocator. */
export interface WasmAllocator {
    _malloc(size: number): number;
    _free(ptr: number): void;
}

/**
 * The callback's return type, or `never` if it is async. An `async` callback
 * returns at its first `await`, so the frees run while it is suspended and every
 * pointer it holds dangles when it resumes — corrupted data, not a crash.
 */
type Sync<R> = R extends PromiseLike<unknown> ? never : R;

/**
 * Run `fn` with a scratch allocator; free everything it allocated on exit,
 * whether `fn` returns normally or throws. Frees in reverse allocation order.
 *
 * @example
 * const offset = withScratch(module, alloc => {
 *     const ptr = alloc(pixels.length);
 *     module.HEAPU8.set(pixels, ptr);
 *     return module.uploadTexture(ptr, pixels.length); // may throw — ptr still freed
 * });
 */
export function withScratch<R>(
    mod: WasmAllocator,
    fn: (alloc: (size: number) => number) => Sync<R>,
): R {
    const ptrs: number[] = [];
    const alloc = (size: number): number => {
        const p = mod._malloc(size);
        if (p) ptrs.push(p);
        return p;
    };
    try {
        return fn(alloc) as R;
    } finally {
        for (let i = ptrs.length - 1; i >= 0; i--) {
            mod._free(ptrs[i]!);
        }
    }
}

/**
 * Convenience for the single-buffer case: allocate `size` bytes, run `fn` with
 * the pointer, and free it on exit (normal or throw).
 */
export function withMalloc<R>(
    mod: WasmAllocator,
    size: number,
    fn: (ptr: number) => Sync<R>,
): R {
    return withScratch<R>(mod, alloc => fn(alloc(size)));
}