shared data API

Author: acolombier

CMakeLists.txt

@@ -1133,6 +1133,7 @@ add_library(
   src/controllers/controlpickermenu.cpp
   src/controllers/legacycontrollermappingfilehandler.cpp
   src/controllers/legacycontrollermapping.cpp
+  src/controllers/controllershareddata.cpp
   src/controllers/delegates/controldelegate.cpp
   src/controllers/delegates/midibytedelegate.cpp
   src/controllers/delegates/midichanneldelegate.cpp
@@ -2598,6 +2599,7 @@ if(BUILD_TESTING)
     src/test/controller_mapping_settings_test.cpp
     src/test/controllers/controller_columnid_regression_test.cpp
     src/test/controllerscriptenginelegacy_test.cpp
+    src/test/controllershareddata_test.cpp
     src/test/controlobjecttest.cpp
     src/test/controlobjectaliastest.cpp
     src/test/controlobjectscripttest.cpp

res/controllers/engine-api.d.ts

@@ -125,6 +125,7 @@ declare namespace engine {
     function getPlayer(group: string): Player | undefined
 
     type SettingValue = string | number | boolean;
+    type SharedDataValue = string | number | boolean | object | array | undefined;
     /**
      * Gets the value of a controller setting
      * The value is either set in the preferences dialog,
@@ -172,6 +173,28 @@ declare namespace engine {
      */
     function setParameter(group: string, name: string, newValue: number): void;
 
+    /**
+     * Gets the shared runtime data.
+     * @returns Runtime shared data value
+     */
+    function getSharedData(): SharedDataValue;
+
+    /**
+     * Override the the shared runtime data with a new value.
+     *
+     * It is suggested to make additive changes (e.g add new attribute to existing object) in order to ease integration with other controller mapping
+     * @param newValue Runtime shared data value to be set
+     */
+   function setSharedData(newValue: SharedDataValue): void;
+
+    /**
+     * Sets the control value specified with normalized range of 0..1
+     * @param group Group of the control e.g. "[Channel1]"
+     * @param name Name of the control e.g. "play_indicator"
+     * @param newValue Value to be set, normalized to a range of 0..1
+     */
+    function setParameter(group: string, name: string, newValue: number): void;
+
     /**
      * Normalizes a specified value using the range of the given control,
      * to the range of 0..1
@@ -212,6 +235,7 @@ declare namespace engine {
     function getDefaultParameter(group: string, name: string): number;
 
     type CoCallback = (value: number, group: string, name: string) => void
+    type RuntimeSharedDataCallback = (value: SharedDataValue) => void
 
     /**
      * Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes
@@ -221,10 +245,19 @@ declare namespace engine {
      * @param group Group of the control e.g. "[Channel1]"
      * @param name Name of the control e.g. "play_indicator"
      * @param callback JS function, which will be called every time, the value of the connected control changes.
-     * @returns Returns script connection object on success, otherwise 'undefined''
+     * @returns Returns script connection object on success, otherwise 'undefined'
      */
     function makeConnection(group: string, name: string, callback: CoCallback): ScriptConnection | undefined;
 
+    /**
+     * Register callback function to be triggered when the shared data is updated
+     *
+     * Note that local update will also trigger the callback. Make sure to make your callback safe against recursion.
+     * @param callback JS function, which will be called every time, the shared controller value changes.
+     * @returns Returns script connection object on success, otherwise 'undefined'
+     */
+    function makeSharedDataConnection(callback: RuntimeSharedDataCallback): ScriptConnection | undefined;
+
     /**
      * Connects a specified Mixxx Control with a callback function, which is executed if the value of the control changes
      *

src/controllers/bulk/bulkcontroller.cpp

@@ -1,6 +1,7 @@
 #include "controllers/bulk/bulkcontroller.h"
 
 #include <libusb.h>
+#include <qstringliteral.h>
 
 #include <algorithm>
 
@@ -116,6 +117,13 @@ QList<std::shared_ptr<AbstractLegacyControllerSetting>> BulkController::getMappi
     return m_pMapping->getSettings();
 }
 
+const QString& BulkController::getSharedDataNamespace() {
+    if (!m_pMapping) {
+        return QStringLiteral("");
+    }
+    return m_pMapping->sharedDataNamespace();
+}
+
 #ifdef MIXXX_USE_QML
 QList<LegacyControllerMapping::QMLModuleInfo> BulkController::getMappingModules() {
     if (!m_pMapping) {
@@ -164,7 +172,8 @@ bool BulkController::matchProductInfo(const ProductInfo& product) {
     return true;
 }
 
-int BulkController::open(const QString& resourcePath) {
+int BulkController::open(const QString& resourcePath,
+            std::shared_ptr<ControllerSharedData> runtimeData) {
     if (isOpen()) {
         qCWarning(m_logBase) << "USB Bulk device" << getName() << "already open";
         return -1;
@@ -230,7 +239,7 @@ int BulkController::open(const QString& resourcePath) {
         // audio directly, like when scratching
         m_pReader->start(QThread::HighPriority);
     }
-    applyMapping(resourcePath);
+    applyMapping(resourcePath, runtimeData);
     setOpen(true);
     return 0;
 }

src/controllers/bulk/bulkcontroller.h

@@ -46,6 +46,7 @@ class BulkController : public Controller {
 
     QList<LegacyControllerMapping::ScriptFileInfo> getMappingScriptFiles() override;
     QList<std::shared_ptr<AbstractLegacyControllerSetting>> getMappingSettings() override;
+    const QString& getSharedDataNamespace() override;
 #ifdef MIXXX_USE_QML
     QList<LegacyControllerMapping::QMLModuleInfo> getMappingModules() override;
     QList<LegacyControllerMapping::ScreenInfo> getMappingInfoScreens() override;
@@ -89,7 +90,8 @@ class BulkController : public Controller {
     void send(const QList<int>& data, unsigned int length) override;
 
   private:
-    int open(const QString& resourcePath) override;
+    int open(const QString& resourcePath,
+            std::shared_ptr<ControllerSharedData> runtimeData) override;
     int close() override;
 
     // For devices which only support a single report, reportID must be set to

src/controllers/controller.cpp

@@ -3,6 +3,7 @@
 #include <QJSEngine>
 #include <algorithm>
 
+#include "controllers/controllershareddata.h"
 #include "controllers/scripting/legacy/controllerscriptenginelegacy.h"
 #include "moc_controller.cpp"
 #include "util/cmdlineargs.h"
@@ -16,8 +17,7 @@ QString loggingCategoryPrefix(const QString& deviceName) {
 } // namespace
 
 Controller::Controller(const QString& deviceName)
-        : m_sDeviceName(deviceName),
-          m_logBase(loggingCategoryPrefix(deviceName)),
+        : m_sDeviceName(deviceName),m_logBase(loggingCategoryPrefix(deviceName)),
           m_logInput(loggingCategoryPrefix(deviceName) + QStringLiteral(".input")),
           m_logOutput(loggingCategoryPrefix(deviceName) + QStringLiteral(".output")),
           m_pScriptEngineLegacy(nullptr),
@@ -79,7 +79,8 @@ void Controller::stopEngine() {
     emit engineStopped();
 }
 
-bool Controller::applyMapping(const QString& resourcePath) {
+bool Controller::applyMapping(const QString& resourcePath,
+        std::shared_ptr<ControllerSharedData> runtimeData) {
     qCInfo(m_logBase) << "Applying controller mapping...";
 
     // Load the script code into the engine
@@ -106,6 +107,10 @@ bool Controller::applyMapping(const QString& resourcePath) {
 #else
     Q_UNUSED(resourcePath);
 #endif
+
+    if (runtimeData != nullptr) {
+        m_pScriptEngineLegacy->setSharedData(runtimeData->namespaced(getSharedDataNamespace()));
+    }
     return m_pScriptEngineLegacy->initialize();
 }
 

src/controllers/controller.h

@@ -9,6 +9,7 @@
 
 class ControllerJSProxy;
 class ControllerScriptEngineLegacy;
+class ControllerSharedData;
 
 enum class PhysicalTransportProtocol {
     UNKNOWN,
@@ -53,6 +54,7 @@ class Controller : public QObject {
 
     virtual QList<LegacyControllerMapping::ScriptFileInfo> getMappingScriptFiles() = 0;
     virtual QList<std::shared_ptr<AbstractLegacyControllerSetting>> getMappingSettings() = 0;
+    virtual const QString& getSharedDataNamespace() = 0;
 #ifdef MIXXX_USE_QML
     virtual QList<LegacyControllerMapping::QMLModuleInfo> getMappingModules() = 0;
     virtual QList<LegacyControllerMapping::ScreenInfo> getMappingInfoScreens() = 0;
@@ -119,7 +121,8 @@ class Controller : public QObject {
     void stopLearning();
 
   protected:
-    virtual bool applyMapping(const QString& resourcePath);
+    virtual bool applyMapping(const QString& resourcePath,
+        std::shared_ptr<ControllerSharedData> runtimeData);
 
     template<typename SpecificMappingType>
         requires(std::is_final_v<SpecificMappingType> == true)
@@ -177,7 +180,8 @@ class Controller : public QObject {
     virtual bool sendBytes(const QByteArray& data) = 0;
 
   private: // but used by ControllerManager
-    virtual int open(const QString& resourcePath) = 0;
+    virtual int open(const QString& resourcePath,
+            std::shared_ptr<ControllerSharedData> runtimeData) = 0;
     virtual int close() = 0;
     // Requests that the device poll if it is a polling device. Returns true
     // if events were handled.

src/controllers/controllermanager.cpp

@@ -6,7 +6,9 @@
 #include "controllers/controller.h"
 #include "controllers/controllerlearningeventfilter.h"
 #include "controllers/controllermappinginfoenumerator.h"
+#include "controllers/controllershareddata.h"
 #include "controllers/defs_controllers.h"
+#include "controllers/scripting/legacy/controllerscriptenginelegacy.h"
 #include "moc_controllermanager.cpp"
 #include "util/cmdlineargs.h"
 #include "util/compatibility/qmutex.h"
@@ -95,7 +97,8 @@ ControllerManager::ControllerManager(UserSettingsPointer pConfig)
           // its own event loop.
           m_pControllerLearningEventFilter(new ControllerLearningEventFilter()),
           m_pollTimer(this),
-          m_skipPoll(false) {
+          m_skipPoll(false),
+          m_pRuntimeData(std::make_shared<ControllerSharedData>(this)) {
     qRegisterMetaType<std::shared_ptr<LegacyControllerMapping>>(
             "std::shared_ptr<LegacyControllerMapping>");
 
@@ -297,7 +300,7 @@ void ControllerManager::slotSetUpDevices() {
 
         qDebug() << "Opening controller:" << name;
 
-        int value = pController->open(m_pConfig->getResourcePath());
+        int value = pController->open(m_pConfig->getResourcePath(), m_pRuntimeData);
         if (value != 0) {
             qWarning() << "There was a problem opening" << name;
             continue;
@@ -388,7 +391,7 @@ void ControllerManager::openController(Controller* pController) {
     if (pController->isOpen()) {
         pController->close();
     }
-    int result = pController->open(m_pConfig->getResourcePath());
+    int result = pController->open(m_pConfig->getResourcePath(), m_pRuntimeData);
     pollIfAnyControllersOpen();
 
     // If successfully opened the device, apply the mapping and save the

src/controllers/controllermanager.h

@@ -14,6 +14,7 @@ class Controller;
 class ControllerLearningEventFilter;
 class MappingInfoEnumerator;
 class LegacyControllerMapping;
+class ControllerSharedData;
 class ControllerEnumerator;
 
 /// Function to sort controllers by name
@@ -86,4 +87,5 @@ class ControllerManager : public QObject {
     QSharedPointer<MappingInfoEnumerator> m_pMainThreadUserMappingEnumerator;
     QSharedPointer<MappingInfoEnumerator> m_pMainThreadSystemMappingEnumerator;
     bool m_skipPoll;
+    std::shared_ptr<ControllerSharedData> m_pRuntimeData;
 };

src/controllers/controllershareddata.cpp

@@ -0,0 +1,22 @@
+#include <controllers/controllershareddata.h>
+
+#include "moc_controllershareddata.cpp"
+
+ControllerNamespacedSharedData* ControllerSharedData::namespaced(const QString& ns) {
+    return new ControllerNamespacedSharedData(this, ns);
+}
+
+ControllerNamespacedSharedData::ControllerNamespacedSharedData(
+        ControllerSharedData* parent, const QString& ns)
+        : QObject(parent),
+          m_namespace(ns) {
+    connect(parent,
+            &ControllerSharedData::updated,
+            this,
+            [this](const QString& ns, const QVariant& value) {
+                if (ns != m_namespace) {
+                    return;
+                }
+                emit updated(value);
+            });
+}

src/controllers/controllershareddata.h

@@ -0,0 +1,68 @@
+#pragma once
+
+#include <QVariant>
+
+#include "util/assert.h"
+
+class ControllerNamespacedSharedData;
+
+/// ControllerSharedData is a wrapper that allows controllers script runtimes
+/// to share arbitrary data via a the JavaScript interface. Controllers don't
+/// access this object directly, and instead uses the
+/// ControllerNamespacedSharedData wrapper to isolate a specific namespace and
+/// prevent potential clash
+class ControllerSharedData : public QObject {
+    Q_OBJECT
+  public:
+    ControllerSharedData(QObject* parent)
+            : QObject(parent),
+              m_value() {
+    }
+
+    QVariant get(const QString& ns) const {
+        return m_value.value(ns);
+    }
+
+    /// @brief Create a a namespace wrapper that can be used by a controller.
+    /// The caller is owning the wrapper
+    /// @param ns The namespace to restrict access to
+    /// @return The pointer to the newly allocated wrapper
+    ControllerNamespacedSharedData* namespaced(const QString& ns);
+
+  public slots:
+    void set(const QString& ns, const QVariant& value) {
+        m_value[ns] = value;
+        emit updated(ns, m_value[ns]);
+    }
+
+  signals:
+    void updated(const QString& ns, const QVariant& value);
+
+  private:
+    QHash<QString, QVariant> m_value;
+};
+
+/// ControllerNamespacedSharedData is a wrapper that restrict access to a given
+/// namespace. It doesn't hold any data and can safely be deleted at all time,
+/// but only provide the namespace abstraction for controller to interact with
+/// via a the JavaScript interface
+class ControllerNamespacedSharedData : public QObject {
+    Q_OBJECT
+  public:
+    ControllerNamespacedSharedData(ControllerSharedData* parent, const QString& ns);
+
+    QVariant get() const {
+        return static_cast<ControllerSharedData*>(parent())->get(m_namespace);
+    }
+
+  public slots:
+    void set(const QVariant& value) {
+        static_cast<ControllerSharedData*>(parent())->set(m_namespace, value);
+    }
+
+  signals:
+    void updated(const QVariant& value);
+
+  private:
+    QString m_namespace;
+};