ScriptEngine.h

//
//  ScriptEngine.h
//  libraries/script-engine/src
//
//  Created by Brad Hefta-Gaub on 12/14/13.
//  Copyright 2013 High Fidelity, Inc.
//  Copyright 2020 Vircadia contributors.
//  Copyright 2023 Overte e.V.
//
//  Distributed under the Apache License, Version 2.0.
//  See the accompanying file LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html
//  SPDX-License-Identifier: Apache-2.0
//
 
 
#ifndef hifi_ScriptEngine_h
#define hifi_ScriptEngine_h
 
#include <memory>
 
#include <QtCore/QFlags>
#include <QtCore/QObject>
 
#include "ScriptValue.h"
#include "ScriptException.h"
 
// These are used for debugging memory leaks caused by persistent handles
//#define OVERTE_V8_MEMORY_DEBUG
 
class QByteArray;
class QLatin1String;
class QString;
class QThread;
class QVariant;
class ScriptContext;
class ScriptEngine;
class ScriptManager;
class ScriptProgram;
using ScriptEnginePointer = std::shared_ptr<ScriptEngine>;
using ScriptProgramPointer = std::shared_ptr<ScriptProgram>;
 
Q_DECLARE_METATYPE(ScriptEnginePointer);
 
template <typename T>
inline ScriptValue
 
scriptValueFromValue(ScriptEngine* engine, const T& t);
 
template <typename T>
inline T scriptvalue_cast(const ScriptValue& value);
 
class ScriptEngineMemoryStatistics {
public:
    size_t totalHeapSize;
    size_t usedHeapSize;
    size_t totalAvailableSize;
    size_t totalGlobalHandlesSize;
    size_t usedGlobalHandlesSize;
#ifdef OVERTE_V8_MEMORY_DEBUG
    size_t scriptValueCount;
    size_t scriptValueProxyCount;
    size_t qObjectCount;
    //size_t qVariantProxyCount;
#endif
};
 
class ScriptEngine : public QObject {
    Q_OBJECT
public:
 
    ScriptEngine(ScriptManager *manager = nullptr) : _manager(manager) {
 
    }
 
    typedef ScriptValue (*FunctionSignature)(ScriptContext*, ScriptEngine*);
    typedef ScriptValue (*MarshalFunction)(ScriptEngine*, const void*);
    typedef bool (*DemarshalFunction)(const ScriptValue&, QVariant &dest);
 
    enum ValueOwnership {
        QtOwnership = 0,
 
        ScriptOwnership = 1,
 
        AutoOwnership = 2,
    };
 
    enum QObjectWrapOption {
 
        //ExcludeChildObjects   = 0x0001,
 
        ExcludeSuperClassMethods = 0x0002,
 
        ExcludeSuperClassProperties = 0x0004,
 
        ExcludeSuperClassContents = ExcludeSuperClassMethods | ExcludeSuperClassProperties,
 
        //ExcludeDeleteLater = 0x0010,
 
        ExcludeSlots = 0x0020,
 
        AutoCreateDynamicProperties = 0x0100,
 
        PreferExistingWrapperObject = 0x0200,
 
        SkipMethodsInEnumeration = 0x0008,
    };
    Q_DECLARE_FLAGS(QObjectWrapOptions, QObjectWrapOption);
 
public:
 
    class ScriptEngineScopeGuard {
    protected:
        ScriptEngineScopeGuard() = default;
 
        // prevent copy and move
        ScriptEngineScopeGuard(const ScriptEngineScopeGuard&) = delete;
        ScriptEngineScopeGuard(ScriptEngineScopeGuard&&) = delete;
        ScriptEngineScopeGuard& operator=(const ScriptEngineScopeGuard&) = delete;
        ScriptEngineScopeGuard& operator=(ScriptEngineScopeGuard&&) = delete;
    public:
        virtual ~ScriptEngineScopeGuard() = default;
    };
 
    virtual std::unique_ptr<ScriptEngineScopeGuard> getScopeGuard() = 0;
 
    virtual void abortEvaluation() = 0;
 
    virtual void clearExceptions() = 0;
 
    virtual ScriptContext* currentContext() const = 0;
 
    virtual ScriptValue evaluate(const QString& program, const QString& fileName = QString()) = 0;
 
    virtual ScriptValue evaluate(const ScriptProgramPointer &program) = 0;
 
 
    virtual ScriptValue evaluateInClosure(const ScriptValue& locals, const ScriptProgramPointer& program) = 0;
 
    virtual ScriptValue globalObject() {
        Q_ASSERT(false);
        return ScriptValue();
    }
 
    virtual bool hasUncaughtException() const = 0;
 
    virtual bool isEvaluating() const = 0;
    //virtual ScriptValue lintScript(const QString& sourceCode, const QString& fileName, const int lineNumber = 1) = 0;
 
    virtual ScriptValue checkScriptSyntax(ScriptProgramPointer program) = 0;
 
    ScriptManager* manager() const { return _manager; }
 
    virtual ScriptValue newArray(uint length = 0) = 0;
    virtual ScriptValue newArrayBuffer(const QByteArray& message) = 0;
    virtual ScriptValue newFunction(FunctionSignature fun, int length = 0) {
        Q_ASSERT(false);
        return ScriptValue();
    }
    virtual ScriptValue newObject() = 0;
    virtual ScriptProgramPointer newProgram(const QString& sourceCode, const QString& fileName) = 0;
    virtual ScriptValue newQObject(QObject *object, ValueOwnership ownership = QtOwnership, const QObjectWrapOptions &options = QObjectWrapOptions()) = 0;
    virtual ScriptValue newValue(bool value) = 0;
    virtual ScriptValue newValue(int value) = 0;
    virtual ScriptValue newValue(uint value) = 0;
    virtual ScriptValue newValue(double value) = 0;
    virtual ScriptValue newValue(const QString& value) = 0;
    virtual ScriptValue newValue(const QLatin1String& value) = 0;
    virtual ScriptValue newValue(const char* value) = 0;
    virtual ScriptValue newVariant(const QVariant& value) = 0;
    virtual ScriptValue nullValue() = 0;
 
 
    virtual ScriptValue makeError(const ScriptValue& other, const QString& type = "Error") = 0;
 
 
    virtual bool raiseException(const ScriptValue& exception, const QString &reason = QString()) = 0;
 
    virtual bool raiseException(const QString& error, const QString &reason = QString()) = 0;
 
 
    virtual void registerEnum(ScriptEngineScopeGuard* scopeGuard, const QString& enumName, QMetaEnum newEnum) = 0;
    virtual void registerFunction(ScriptEngineScopeGuard* scopeGuard, const QString& name, FunctionSignature fun, int numArguments = -1) = 0;
    virtual void registerFunction(ScriptEngineScopeGuard* scopeGuard, const QString& parent, const QString& name, FunctionSignature fun, int numArguments = -1) = 0;
    virtual void registerGetterSetter(ScriptEngineScopeGuard* scopeGuard, const QString& name, FunctionSignature getter, FunctionSignature setter, const QString& parent = QString("")) = 0;
    virtual void registerGlobalObject(ScriptEngineScopeGuard* scopeGuard, const QString& name, QObject* object, ScriptEngine::ValueOwnership = ScriptEngine::QtOwnership) = 0;
    virtual void setDefaultPrototype(int metaTypeId, const ScriptValue& prototype) = 0;
    virtual void setObjectName(const QString& name) = 0;
    virtual bool setProperty(const char* name, const QVariant& value) = 0;
    virtual void setProcessEventsInterval(int interval) = 0;
    virtual QThread* thread() const = 0;
    virtual void setThread(QThread* thread) = 0;
    //Q_INVOKABLE virtual void enterIsolateOnThisThread() = 0;
    virtual ScriptValue undefinedValue() = 0;
 
    virtual std::shared_ptr<ScriptException> uncaughtException() const = 0;
 
    virtual void updateMemoryCost(const qint64& deltaSize) = 0;
    virtual void requestCollectGarbage() = 0;
 
    virtual void processEvents() = 0;
 
    virtual void compileTest() = 0;
    virtual QString scriptValueDebugDetails(const ScriptValue &value) = 0;
    virtual QString scriptValueDebugListMembers(const ScriptValue &value) = 0;
 
    virtual void logBacktrace(const QString &title) = 0;
 
    virtual ScriptEngineMemoryStatistics getMemoryUsageStatistics() = 0;
 
    virtual void startCollectingObjectStatistics() = 0;
 
    virtual void dumpHeapObjectStatistics() = 0;
 
    virtual void startProfiling() = 0;
 
    virtual void stopProfilingAndSave() = 0;
 
    virtual void disconnectSignalProxies() = 0;
 
public:
    // helper to detect and log warnings when other code invokes QScriptEngine/BaseScriptEngine in thread-unsafe ways
    bool IS_THREADSAFE_INVOCATION(const QString& method);
 
public:
    template <typename T>
    inline T fromScriptValue(const ScriptValue& value) {
        return scriptvalue_cast<T>(value);
    }
 
    template <typename T>
    inline ScriptValue toScriptValue(const T& value) {
        return scriptValueFromValue(this, value);
    }
 
public: // not for public use, but I don't like how Qt strings this along with private friend functions
    virtual ScriptValue create(int type, const void* ptr) = 0;
    virtual QVariant convert(const ScriptValue& value, int type) = 0;
    virtual void registerCustomType(int type, MarshalFunction mf, DemarshalFunction df) = 0;
    virtual QStringList getCurrentScriptURLs() const = 0;
    virtual void perManagerLoopIterationCleanup() = 0;
 
signals:
    void exception(std::shared_ptr<ScriptException> exception);
 
protected:
    virtual ~ScriptEngine() {}  // prevent explicit deletion of base class
 
    ScriptManager *_manager;
};
Q_DECLARE_OPERATORS_FOR_FLAGS(ScriptEngine::QObjectWrapOptions);
 
ScriptEnginePointer newScriptEngine(ScriptManager* manager = nullptr);
 
// Standardized CPS callback helpers (see: http://fredkschott.com/post/2014/03/understanding-error-first-callbacks-in-node-js/)
// These two helpers allow async JS APIs that use a callback parameter to be more friendly to scripters by accepting thisObject
// context and adopting a consistent and intuitable callback signature:
//   function callback(err, result) { if (err) { ... } else { /* do stuff with result */ } }
//
// To use, first pass the user-specified callback args in the same order used with optionally-scoped  Qt signal connections:
//   auto handler = makeScopedHandlerObject(scopeOrCallback, optionalMethodOrName);
// And then invoke the scoped handler later per CPS conventions:
//   auto result = callScopedHandlerObject(handler, err, result);
ScriptValue makeScopedHandlerObject(const ScriptValue& scopeOrCallback, const ScriptValue& methodOrName);
ScriptValue callScopedHandlerObject(const ScriptValue& handler, const ScriptValue& err, const ScriptValue& result);
 
// Inline implementations
/*
QThread* ScriptEngine::thread() const {
    QObject* qobject = toQObject();
    if (qobject == nullptr) {
        return nullptr;
    }
    return qobject->thread();
}
*/
 
#endif  // hifi_ScriptEngine_h