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.

5.3 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    AotModule.hpp
 * @brief   A built module of compiled systems, opened by a host that links.
 *
 * @details The wasm road ships a manifest beside the module because a browser
 *          cannot read a data section out of one. A host that LOADS a library
 *          has no such problem: the declaration table is in the artifact, so
 *          the names, the queries, the resources and the handshake all come
 *          from the thing being run rather than from a file beside it that can
 *          be swapped for another.
 *
 *          Refuses rather than degrades. A module built for other offsets does
 *          not produce a wrong answer, it produces a read of a different field,
 *          so `open` is not "did the platform load it" — it is also "does it
 *          agree about the engine and the address width".
 *
 *          Owns the handle. Moving transfers it; copying is refused, because
 *          two owners closing one library is the bug this exists to not have.
 */
#pragma once

#include <cstdint>
#include <cstring>
#include <span>
#include <string>
#include <utility>

#include "esengine/aot/AotHost.hpp"   // abiHash — the width half of the handshake
#include "esengine/core/DynamicLibrary.hpp"

namespace esengine::aot {

class Module {
public:
    Module() = default;
    ~Module() { close(); }
    Module(const Module&) = delete;
    Module& operator=(const Module&) = delete;
    Module(Module&& other) noexcept { *this = std::move(other); }
    Module& operator=(Module&& other) noexcept {
        if (this != &other) {
            close();
            handle_ = std::exchange(other.handle_, nullptr);
            systems_ = std::exchange(other.systems_, {});
            contract_ = std::exchange(other.contract_, 0);
        }
        return *this;
    }

    /**
     * Open a module and check it says what `expected` says (see `abiHash`).
     *
     * `why` is filled on every false: the ways this fails want different fixes —
     * the file is absent, it carries no declaration table, or it was built for
     * another engine.
     */
    bool open(const char* path, std::uint64_t expected, std::string* why = nullptr) {
        const auto fail = [why](const char* msg) { if (why != nullptr) *why = msg; return false; };
        Module next;
        next.handle_ = core::openLibrary(path);
        if (next.handle_ == nullptr) return fail("the platform could not load it");

        const auto* hash = static_cast<const std::uint64_t*>(core::librarySymbol(next.handle_, "es_abi_hash"));
        const auto* count = static_cast<const std::uint32_t*>(core::librarySymbol(next.handle_, "es_system_count"));
        const auto* decls = static_cast<const EsSystemDecl*>(core::librarySymbol(next.handle_, "es_systems"));
        if (hash == nullptr || count == nullptr || decls == nullptr) {
            // A wasm module is built WITHOUT the declaration table on purpose;
            // handing one to a linking host lands exactly here.
            return fail("it carries no declaration table — built for a host that shares memory?");
        }
        if (*hash != expected) {
            return fail("it was built against a different engine or address width");
        }
        next.systems_ = std::span<const EsSystemDecl>(decls, *count);
        next.contract_ = next.readContract_();
        // The candidate owns its handle until every check passed. Failed loads
        // leave this owner's declarations and their library alive.
        *this = std::move(next);
        return true;
    }

    /**
     * Which BUILD this module is, for a caller holding the sidecar written
     * beside it. Zero where the module predates it — which the caller must read
     * as "cannot say", never as "paired".
     */
    std::uint64_t contract() const { return contract_; }

    bool isOpen() const { return handle_ != nullptr; }

    /** Every system this module carries, as the artifact declares them. */
    std::span<const EsSystemDecl> systems() const { return systems_; }

    /** One by the name the schedule knows, or nullptr. */
    const EsSystemDecl* find(const char* name) const {
        for (const auto& decl : systems_) {
            if (decl.name != nullptr && std::strcmp(decl.name, name) == 0) return &decl;
        }
        return nullptr;
    }

    void close() {
        // The declarations live IN the library, so they stop existing with it.
        systems_ = {};
        contract_ = 0;
        core::closeLibrary(handle_);
        handle_ = nullptr;
    }

private:
    /**
     * Two functions rather than one constant: a module that shares the engine's
     * memory may carry no data section, and the same translation unit serves
     * both roads. Absent means a module built before pairing existed.
     */
    std::uint64_t readContract_() const {
        using Half = std::uint32_t (*)();
        auto* lo = reinterpret_cast<Half>(core::librarySymbol(handle_, "es_module_contract_lo"));
        auto* hi = reinterpret_cast<Half>(core::librarySymbol(handle_, "es_module_contract_hi"));
        if (lo == nullptr || hi == nullptr) return 0;
        return (static_cast<std::uint64_t>(hi()) << 32) | lo();
    }

    void* handle_ = nullptr;
    std::span<const EsSystemDecl> systems_{};
    std::uint64_t contract_ = 0;
};

}  // namespace esengine::aot