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.

7.1 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    HeapBindings.cpp
 * @brief   The linear heap a `uintptr_t` argument addresses on a device.
 * @details See heap.hpp for why this exists. The allocator is a plain implicit
 *          block list with first fit and lazy coalescing — the traffic is a
 *          handful of scratch buffers per frame (tile arrays, polygon vertices,
 *          the readback slots), not a general-purpose workload, and being simple
 *          enough to audit matters more here than fitting a pathological pattern:
 *          a wrong offset is memory corruption on the wrong side of the boundary.
 *
 *          Registering the arena with `BoundarySpan` is the point of having ONE
 *          region: a JS-supplied span is range-checked on a device exactly as it
 *          is against wasm's linear memory, instead of degrading to a null check.
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @copyright Copyright (c) 2026 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */
#include "Bindings.hpp"
#include "heap.hpp"
#include "esn_shim.hpp"

#include "esengine/bindings/BoundarySpan.hpp"

#include <cstdlib>
#include <cstring>

namespace eshost {
namespace {

// 32 MiB of address space. It has to hold the largest single buffer any
// subsystem marshals — a full tilemap layer's tile array is the big one — and
// pages that are never written never become resident, so the reservation is
// cheap. Exhaustion is logged, never silent.
constexpr size_t kHeapBytes = 32u * 1024u * 1024u;

// Payload alignment. 8 keeps a Float64Array view valid at any allocated offset,
// which is also what emscripten's malloc guarantees.
constexpr uint32_t kAlign = 8;

/** Block header. `size` is the payload size; the payload follows immediately, so
 *  the next header sits at `header + 8 + size`. */
struct Block {
    uint32_t size;
    uint32_t used;
};

uint8_t* g_base = nullptr;
size_t g_highWater = 0;
bool g_failed = false;

Block* blockAt(uint32_t headerOffset) {
    return reinterpret_cast<Block*>(g_base + headerOffset);
}

uint32_t roundUp(size_t n) {
    return static_cast<uint32_t>((n + kAlign - 1) & ~static_cast<size_t>(kAlign - 1));
}

}  // namespace

uint8_t* heapBase() {
    if (g_base || g_failed) return g_base;
    g_base = static_cast<uint8_t*>(std::malloc(kHeapBytes));
    if (!g_base) {
        g_failed = true;
        ESHOST_LOGE("heap: could not reserve %zu bytes — subsystems that marshal buffers "
                    "(physics, tilemaps, spine) will not run", kHeapBytes);
        return nullptr;
    }
    // One free block spanning everything. Offset 0 is the first header, so no
    // payload can ever live there and 0 keeps its null meaning.
    Block* first = blockAt(0);
    first->size = static_cast<uint32_t>(kHeapBytes - sizeof(Block));
    first->used = 0;
    // Same guarantee as the sandbox: a span from JS must land inside this region.
    esengine::setBoundaryRegion(reinterpret_cast<uintptr_t>(g_base), kHeapBytes);
    ESHOST_LOGI("heap: %zu KiB arena at %p (JS sees it as one ArrayBuffer)",
                kHeapBytes / 1024, static_cast<void*>(g_base));
    return g_base;
}

size_t heapSize() { return kHeapBytes; }

size_t heapHighWater() { return g_highWater; }

uint32_t heapAlloc(size_t bytes) {
    if (bytes == 0 || !heapBase()) return 0;
    const uint32_t want = roundUp(bytes);
    if (want > kHeapBytes) return 0;

    uint32_t offset = 0;
    while (offset + sizeof(Block) <= kHeapBytes) {
        Block* block = blockAt(offset);
        if (!block->used) {
            // Coalesce free neighbours as we pass them, which is the only
            // defragmentation this allocator does — enough for scratch traffic
            // that frees what it allocates.
            for (;;) {
                const uint32_t nextHeader = offset + static_cast<uint32_t>(sizeof(Block)) + block->size;
                if (nextHeader + sizeof(Block) > kHeapBytes) break;
                Block* next = blockAt(nextHeader);
                if (next->used) break;
                block->size += static_cast<uint32_t>(sizeof(Block)) + next->size;
            }
            if (block->size >= want) {
                // Split when the tail can still hold a header plus one aligned unit.
                if (block->size - want >= sizeof(Block) + kAlign) {
                    const uint32_t tail = offset + static_cast<uint32_t>(sizeof(Block)) + want;
                    Block* rest = blockAt(tail);
                    rest->size = block->size - want - static_cast<uint32_t>(sizeof(Block));
                    rest->used = 0;
                    block->size = want;
                }
                block->used = 1;
                const uint32_t payload = offset + static_cast<uint32_t>(sizeof(Block));
                if (payload + block->size > g_highWater) g_highWater = payload + block->size;
                return payload;
            }
        }
        offset += static_cast<uint32_t>(sizeof(Block)) + block->size;
    }
    ESHOST_LOGE("heap: out of memory (wanted %u bytes, arena is %zu KiB, high water %zu KiB)",
                want, kHeapBytes / 1024, g_highWater / 1024);
    return 0;
}

void heapFree(uint32_t offset) {
    if (offset == 0 || !g_base) return;
    if (offset < sizeof(Block) || offset >= kHeapBytes || (offset % kAlign) != 0) {
        ESHOST_LOGE("heap: free(%u) is not an allocated offset", offset);
        return;
    }
    Block* block = blockAt(offset - static_cast<uint32_t>(sizeof(Block)));
    if (!block->used) {
        ESHOST_LOGE("heap: double free at offset %u", offset);
        return;
    }
    block->used = 0;
}

void* heapPtr(uint32_t offset, size_t bytes) {
    if (offset == 0 || !g_base) return nullptr;
    if (offset >= kHeapBytes || bytes > kHeapBytes - offset) {
        ESHOST_LOGE("heap: offset %u (+%zu bytes) is outside the arena", offset, bytes);
        return nullptr;
    }
    return g_base + offset;
}

namespace {

// es_heap() -> ArrayBuffer over the whole arena. The SDK builds its typed-array
// views on this once (`createNativeHeap`); the arena never moves, so unlike a
// growable wasm heap the views stay valid for the process lifetime.
esjs::Val js_heap(const esjs::Args& a) {
    uint8_t* base = heapBase();
    if (!base) return esjs::null();
    return esn_arraybuffer(base, heapSize());
}

// es_malloc(bytes) -> offset (0 when full, which reads as null like _malloc).
esjs::Val js_malloc(const esjs::Args& a) {
    if (a.size() < 1) return esjs::uint32(0);
    int64_t bytes = 0;
    bytes = esjs::toInt64(a[0]);
    if (bytes <= 0) return esjs::uint32(0);
    return esjs::uint32(heapAlloc(static_cast<size_t>(bytes)));
}

// es_free(offset).
esjs::Val js_free(const esjs::Args& a) {
    if (a.size() < 1) return esjs::undefined();
    uint32_t offset = 0;
    offset = esjs::toUint32(a[0]);
    heapFree(offset);
    return esjs::undefined();
}

}  // namespace

void registerHeapBindings(HostState& h, esjs::Val global) {
    (void)h;
    bindGlobal(global, "es_heap", js_heap, 0);
    bindGlobal(global, "es_malloc", js_malloc, 1);
    bindGlobal(global, "es_free", js_free, 1);
}

}  // namespace eshost