Runtime.h

浏览该文件的文档.

#pragma once
 
#include "common/Export.h"
 
#include <simplesquirrel/simplesquirrel.hpp>
 
#include <cstdio>
#include <cstdint>
#include <functional>
#include <limits>
#include <memory>
#include <stdexcept>
#include <string>
#include <unordered_map>
#include <vector>
 
namespace eve {
 
namespace script {
class ScriptCompiler;
class ScriptModuleResolver;
struct ScriptErrorContext;
}  // namespace script
 
inline std::string reflectedFloatString(double value) {
    char buf[64];
    std::snprintf(buf, sizeof(buf), "%.*g",
                  std::numeric_limits<double>::max_digits10, value);
    return buf;
}
 
enum class ScriptState {
    Compiled,
    Running,
    Loaded,
    Unloading,
    Unloaded,
    Failed,
};
 
enum class ScriptStage {
    Compile,
    Execute,
    Reflect,
    Unload,
    Shutdown,
};
 
class EVENGINE_API_FOUNDATION ScriptException : public std::runtime_error {
public:
    ScriptException(ScriptStage stage, std::string source, uint64_t scriptId,
                    const std::string& message);
    ScriptException(ScriptStage stage, std::string source, uint64_t scriptId,
                    const script::ScriptErrorContext& context);
 
    ScriptStage stage() const noexcept { return stage_; }
    const std::string& source() const noexcept { return source_; }
    uint64_t scriptId() const noexcept { return script_id_; }
    bool hasLocation() const noexcept { return line_ > 0; }
    int line() const noexcept { return line_; }
    int column() const noexcept { return column_; }
    const std::string& function() const noexcept { return function_; }
    const std::string& stackTrace() const noexcept { return stack_trace_; }
    bool reported() const noexcept { return reported_; }
 
private:
    ScriptStage stage_;
    std::string source_;
    uint64_t script_id_;
    int line_ = -1;
    int column_ = -1;
    std::string function_;
    std::string stack_trace_;
    bool reported_ = false;
};
 
struct EVENGINE_API_FOUNDATION_INLINE ReflectedAttribute {
    std::string name;
    ssq::Type type = ssq::Type::NULLPTR;
    std::string value;
};
 
enum class EVENGINE_API_FOUNDATION ReflectedValueKind : uint8_t {
    None     = 0, 
    Bool     = 1, 
    Integer  = 2, 
    Float    = 3, 
    String   = 4, 
    Array    = 5, 
    Table    = 6, 
    Instance = 7, 
    Other    = 8, 
};
 
struct EVENGINE_API_FOUNDATION_INLINE ReflectedValue {
    ReflectedValueKind kind = ReflectedValueKind::None;
    bool boolean = false;
    int64_t integer = 0;
    double floating = 0.0;
    std::string text;
 
    bool empty() const noexcept { return kind == ReflectedValueKind::None; }
    bool asBool() const noexcept { return boolean; }
    int64_t asInt() const noexcept { return integer; }
    double asFloat() const noexcept { return floating; }
    const std::string& asString() const noexcept { return text; }
};
 
struct EVENGINE_API_FOUNDATION ReflectedMember {
    std::string name;
    ssq::Type type = ssq::Type::NULLPTR;
    bool method = false;
    std::vector<ReflectedAttribute> attributes;
    ReflectedValue value;  
    const ReflectedAttribute* findAttribute(const std::string& name) const noexcept;
    float attrFloat(const std::string& name, float def = 0.f) const noexcept;
    bool attrBool(const std::string& name, bool def = false) const noexcept;
    std::string attrString(const std::string& name, const std::string& def = {}) const;
    std::vector<std::string> attrOptions(const std::string& name) const;
};
 
struct EVENGINE_API_FOUNDATION_INLINE ReflectedClass {
    std::string name;
    std::string source;
    std::string base;
    std::vector<ReflectedMember> members;
};
 
struct EVENGINE_API_FOUNDATION_INLINE ScriptInfo {
    uint64_t id = 0;
    std::string source;
    ScriptState state = ScriptState::Compiled;
    std::vector<std::string> classes;
    std::string error;
};
 
class EVENGINE_API_FOUNDATION Runtime {
public:
    using ScriptId = uint64_t;
    using ErrorHandler = std::function<void(const ScriptException&)>;
    using LifecycleHandler = std::function<void(const ScriptInfo&)>;
 
    class EVENGINE_API_FOUNDATION StackGuard {
    public:
        explicit StackGuard(Runtime& runtime) noexcept;
        ~StackGuard();
        StackGuard(StackGuard&& other) noexcept;
        StackGuard& operator=(StackGuard&& other) noexcept;
        StackGuard(const StackGuard&) = delete;
        StackGuard& operator=(const StackGuard&) = delete;
 
        int top() const noexcept { return static_cast<int>(top_); }
        void dismiss() noexcept { vm_ = nullptr; }
 
    private:
        HSQUIRRELVM vm_ = nullptr;
        SQInteger top_ = 0;
    };
 
    class EVENGINE_API_FOUNDATION Scope {
    public:
        explicit Scope(Runtime& runtime);
        ~Scope();
        Scope(Scope&& other) noexcept;
        Scope& operator=(Scope&& other) = delete;
        Scope(const Scope&) = delete;
        Scope& operator=(const Scope&) = delete;
 
    private:
        Runtime* runtime_ = nullptr;
    };
 
    explicit Runtime(size_t stackSize = 2048, ssq::Libs::Flag libraries = ssq::Libs::ALL);
    ~Runtime();
    Runtime(Runtime&&) = delete;
    Runtime& operator=(Runtime&&) = delete;
    Runtime(const Runtime&) = delete;
    Runtime& operator=(const Runtime&) = delete;
 
    void initialize();
    void shutdown() noexcept;
    bool initialized() const noexcept;
 
    ssq::VM& vm() noexcept;
    const ssq::VM& vm() const noexcept;
    HSQUIRRELVM handle() const noexcept;
    script::ScriptModuleResolver& scriptModules() noexcept;
    const script::ScriptModuleResolver& scriptModules() const noexcept;
    script::ScriptCompiler& scriptCompiler() noexcept;
    const script::ScriptCompiler& scriptCompiler() const noexcept;
    ssq::Table root() const;
    ssq::Table table(const char* name) const;
 
    StackGuard guard() noexcept { return StackGuard(*this); }
    Scope enter() { return Scope(*this); }
    static Runtime* current() noexcept;
    static size_t stackDepth() noexcept;
 
    ScriptId compileSource(std::string source, std::string sourceName = "buffer");
    ScriptId compileFile(const std::string& path);
    const ScriptInfo& execute(ScriptId id);
    ScriptId runSource(std::string source, std::string sourceName = "buffer");
    ScriptId runFile(const std::string& path);
    ScriptId reflectFile(const std::string& path) { return runFile(path); }
    const ReflectedClass& reflectClass(const std::string& name,
                                       const std::string& source = {});
    ssq::Object createInstance(const std::string& name, const std::string& source = {});
    std::vector<ReflectedMember> reflectInstance(const ssq::Object& instance) const;
    ReflectedValue readProperty(const ssq::Object& instance,
                                const std::string& name) const;
    bool writeProperty(const ssq::Object& instance, const std::string& name,
                       const ReflectedValue& value) const;
    ssq::Object readObjectProperty(const ssq::Object& instance,
                                   const std::string& name) const;
 
    // ---- array member editing ---------------------------------------------
    size_t arraySize(const ssq::Object& instance, const std::string& name) const;
    ReflectedValue arrayGet(const ssq::Object& instance, const std::string& name,
                            size_t index) const;
    bool arraySet(const ssq::Object& instance, const std::string& name, size_t index,
                  const ReflectedValue& value) const;
    bool arrayAppend(const ssq::Object& instance, const std::string& name,
                     const ReflectedValue& value) const;
    bool arrayRemove(const ssq::Object& instance, const std::string& name,
                     size_t index) const;
 
    // ---- table member editing ---------------------------------------------
    std::vector<std::string> tableKeys(const ssq::Object& instance,
                                       const std::string& name) const;
    ReflectedValue tableGet(const ssq::Object& instance, const std::string& name,
                            const std::string& key) const;
    bool tableSet(const ssq::Object& instance, const std::string& name,
                  const std::string& key, const ReflectedValue& value) const;
    bool tableRemove(const ssq::Object& instance, const std::string& name,
                     const std::string& key) const;
    ScriptId reload(ScriptId id);
    bool unload(ScriptId id);
    void unloadAll() noexcept;
 
    bool contains(ScriptId id) const noexcept;
    const ScriptInfo* script(ScriptId id) const noexcept;
    std::vector<ScriptInfo> scripts() const;
    const ReflectedClass* reflectedClass(const std::string& name) const noexcept;
    std::vector<ReflectedClass> reflectedClasses() const;
    size_t scanClasses();
    ssq::Class findClass(const std::string& name) const;
    std::string classNameOf(const ssq::Object& instance) const;
 
    void setErrorHandler(ErrorHandler handler) { error_handler_ = std::move(handler); }
    void setLifecycleHandler(LifecycleHandler handler) { lifecycle_handler_ = std::move(handler); }
 
private:
    struct ScriptRecord;
 
    void installErrorHandler();
 
    std::unique_ptr<ssq::VM> vm_;
    std::unique_ptr<script::ScriptModuleResolver> script_modules_;
    std::unique_ptr<script::ScriptCompiler> script_compiler_;
    std::unordered_map<ScriptId, std::unique_ptr<ScriptRecord>> scripts_;
    std::unordered_map<std::string, ReflectedClass> classes_;
    std::unordered_map<std::string, ScriptId> class_owners_;
    std::unordered_map<std::string, SQUserPointer> class_identities_;
    ScriptId next_script_id_ = 1;
    bool initialized_ = false;
    bool shutting_down_ = false;
    bool stopped_ = false;
    ErrorHandler error_handler_;
    LifecycleHandler lifecycle_handler_;
 
    void notifyLifecycle(const ScriptInfo& info) noexcept;
    script::ScriptErrorContext compileErrorContext(const std::string& what,
                                                   const std::string& sourceText);
    [[noreturn]] void fail(ScriptStage stage, const std::string& source, ScriptId id,
                           const std::exception& error);
    [[noreturn]] void fail(ScriptStage stage, const std::string& source, ScriptId id,
                           script::ScriptErrorContext context);
    void discoverClasses(ScriptRecord& record,
                         const std::unordered_map<std::string, SQUserPointer>& before);
    std::unordered_map<std::string, SQUserPointer> rootClasses() const;
    ReflectedClass inspectClass(const std::string& name, const ssq::Class& cls,
                                const std::string& source) const;
    std::vector<ReflectedMember> collectClassMembers(const ssq::Class& cls) const;
};
 
}  // namespace eve