ScriptedAlgorithm.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include "ScriptedAlgorithmHelpers.h"
#include "SplitTree.h"
#include "TilingAlgorithm.h"
#include <QJSValue>
 
#include <algorithm>
#include <atomic>
#include <functional>
#include <memory>
#include <type_traits>
 
class QJSEngine;
 
namespace PhosphorTiles {
 
class ScriptedAlgorithmWatchdog;
 
// Note: ScriptedAlgorithm is NOT thread-safe despite the base class const contract.
// All calls must occur on the main thread. QJSEngine is inherently single-threaded.
 
namespace detail {
 
template<typename T>
bool jsValueHasType(const QJSValue& v)
{
    if constexpr (std::is_same_v<T, bool>)
        return v.isBool();
    else
        return v.isNumber();
}
 
template<typename T>
T jsValueTo(const QJSValue& v)
{
    if constexpr (std::is_same_v<T, bool>)
        return v.toBool();
    else if constexpr (std::is_same_v<T, int>)
        return v.toInt();
    else
        return static_cast<T>(v.toNumber());
}
 
} // namespace detail
 
class PHOSPHORTILES_EXPORT ScriptedAlgorithm : public TilingAlgorithm
{
    Q_OBJECT
 
    // The watchdog is the only caller of interruptEngine() — it dispatches
    // the interrupt from its supervisor thread while holding the watchdog
    // mutex. Exposing that entry point publicly would tempt unrelated
    // code to call it from the main thread, which would interact badly
    // with guardedCall()'s arm-evaluate-disarm invariant.
    friend class ScriptedAlgorithmWatchdog;
 
public:
    explicit ScriptedAlgorithm(const QString& filePath, std::shared_ptr<ScriptedAlgorithmWatchdog> watchdog = nullptr,
                               QObject* parent = nullptr);
    ~ScriptedAlgorithm() override;
 
    bool isValid() const;
 
    QString filePath() const;
 
    QString scriptId() const;
 
    QString id() const;
 
    void setUserScript(bool isUser);
 
    // TilingAlgorithm interface
    // Note: name(), description(), and the JS-override accessors below lack noexcept
    // because they can theoretically call into QJSEngine (which may throw or fail).
    // Only metadata-only accessors (supportsMemory, centerLayout, etc.) are noexcept.
    QString name() const override;
    QString description() const override;
    QVector<QRect> calculateZones(const TilingParams& params) const override;
    int masterZoneIndex() const override;
    bool supportsMasterCount() const override;
    bool supportsSplitRatio() const override;
    qreal defaultSplitRatio() const override;
    int minimumWindows() const override;
    int defaultMaxWindows() const override;
    bool producesOverlappingZones() const override;
    bool supportsMinSizes() const noexcept override;
    bool supportsMemory() const noexcept override;
    QString zoneNumberDisplay() const noexcept override;
    bool centerLayout() const override;
    bool isScripted() const noexcept override;
    bool isUserScript() const noexcept override;
    void prepareTilingState(TilingState* state) const override;
 
    // Lifecycle hooks (v2)
    bool supportsLifecycleHooks() const noexcept override;
    void onWindowAdded(TilingState* state, int windowIndex) override;
    void onWindowRemoved(TilingState* state, int windowIndex) override;
 
    // Custom parameters (v2)
    bool supportsCustomParams() const noexcept override;
    QVariantList customParamDefList() const override;
    bool hasCustomParam(const QString& name) const override;
    const QVector<ScriptedHelpers::CustomParamDef>& customParamDefs() const;
 
private:
    bool loadScript(const QString& filePath);
 
    QJSValue splitNodeToJSValue(const SplitNode* node, int depth = 0) const;
 
    QJSValue splitNodeToJSValueImpl(const SplitNode* node, const QJSValue& freezeFn, int depth, int& nodeCount) const;
 
    template<typename T>
    T resolveJsOverride(const QJSValue& jsFn, T cachedValue, T metadataFallback) const
    {
        if (m_cachedValuesLoaded && jsFn.isCallable()) {
            return cachedValue;
        }
        // After loadScript() sets m_cachedValuesLoaded, all calls use the cached path above.
        // Before that, fall back to metadata — never call JS without the watchdog.
        return metadataFallback;
    }
 
    template<typename T>
    T resolveJsOverrideClamped(const QJSValue& jsFn, T cachedValue, T metadataFallback, T minVal, T maxVal) const
    {
        return std::clamp(resolveJsOverride<T>(jsFn, cachedValue, metadataFallback), minVal, maxVal);
    }
 
    QJSValue buildJsState(const TilingState* state) const;
 
    QJSValue buildJsWindowArray(const QVector<WindowInfo>& infos, int cap) const;
 
    QJSValue guardedCall(const std::function<QJSValue()>& fn) const;
 
    void interruptEngine();
 
    static constexpr int MaxTreeConversionDepth = AutotileDefaults::MaxRuntimeTreeDepth;
 
    // Owned via QObject parent; mutable because calculateZones() is const but JS evaluation mutates engine state
    mutable QJSEngine* m_engine = nullptr;
    std::shared_ptr<ScriptedAlgorithmWatchdog> m_watchdog;
    mutable QJSValue m_calculateZonesFn;
    QString m_filePath;
    QString m_scriptId;
    bool m_valid = false;
    bool m_isUserScript = false;
    mutable std::atomic<bool> m_evaluating{false}; 
    mutable bool m_lastCallTimedOut = false; 
    mutable uint32_t m_gcCounter = 0; 
    static constexpr uint32_t GcInterval = 8; 
 
    // Consolidated parsed metadata (from // @key value comments)
    ScriptedHelpers::ScriptMetadata m_metadata;
 
    // Optional JS function overrides (checked at call time)
    mutable QJSValue m_jsMasterZoneIndex;
    mutable QJSValue m_jsSupportsMasterCount;
    mutable QJSValue m_jsSupportsSplitRatio;
    mutable QJSValue m_jsDefaultSplitRatio;
    mutable QJSValue m_jsMinimumWindows;
    mutable QJSValue m_jsDefaultMaxWindows;
    mutable QJSValue m_jsProducesOverlappingZones;
    mutable QJSValue m_jsCenterLayout;
 
    // Optional lifecycle hook JS functions
    mutable QJSValue m_jsOnWindowAdded;
    mutable QJSValue m_jsOnWindowRemoved;
    bool m_hasLifecycleHooks = false; 
 
    // Cached JS virtual method overrides (loaded once at script load time)
    int m_cachedMinimumWindows = 1;
    int m_cachedDefaultMaxWindows = 6;
    int m_cachedMasterZoneIndex = -1;
    qreal m_cachedDefaultSplitRatio = AutotileDefaults::DefaultSplitRatio;
    bool m_cachedProducesOverlappingZones = false;
    bool m_cachedSupportsMasterCount = false;
    bool m_cachedSupportsSplitRatio = false;
    bool m_cachedCenterLayout = false;
    bool m_cachedValuesLoaded = false;
};
 
} // namespace PhosphorTiles