all: Add DataBroker and Signals concepts

TODO:
- Add documentation on how to use it.
- Add tests using them.

Author: Martin Henselmeyer <[email protected]>

Author: cassava

engine/lua/cloe-engine/init.lua

@@ -34,6 +34,12 @@ local engine = {
 
         --- @type number Number of triggers processed from the initial input.
         triggers_processed = 0,
+
+        --- @type table<string, string> Map of signal names to regular expression matches.
+        signal_aliases = {},
+
+        --- @type string[] List of signals to make available during simulation.
+        signal_requires = {},
     },
 
     --- Contains engine state for a simulation.
@@ -80,6 +86,9 @@ local engine = {
 
     --- @type table<string, table> Namespaced Lua interfaces of instantiated plugins.
     plugins = {},
+
+    --- @type table<string, userdata> Table of required signals.
+    signals = {},
 }
 
 require("cloe-engine.types")

engine/lua/cloe/engine.lua

@@ -124,6 +124,158 @@ function engine.log(level, fmt, ...)
     api.log(level, "lua", msg)
 end
 
+--- Alias a set of signals in the Cloe data broker.
+---
+--- @param list table<string, string> # regular expression to alias key
+--- @return table<string, string> # current signal aliases table
+function engine.alias_signals(list)
+    -- TODO: Throw an error if simulation already started.
+    api.initial_input.signal_aliases = luax.tbl_extend("force", api.initial_input.signal_aliases, list)
+    return api.initial_input.signal_aliases
+end
+
+--- Require a set of signals to be made available via the Cloe data broker.
+---
+--- @param list string[] signals to merge into main list of required signals
+--- @return string[] # merged list of signals
+function engine.require_signals(list)
+    -- TODO: Throw an error if simulation already started.
+    api.initial_input.signal_requires = luax.tbl_extend("force", api.initial_input.signal_requires, list)
+    return api.initial_input.signal_requires
+end
+
+--- Optionally alias and require a set of signals from a signals enum list.
+---
+--- This allows you to make an enum somewhere which the language server
+--- can use for autocompletion and which you can use as an alias:
+---
+---     ---@enum Sig
+---     local Sig = {
+---         DriverDoorLatch = "vehicle::framework::chassis::.*driver_door::latch",
+---         VehicleMps = "vehicle::sensors::chassis::velocity",
+---     }
+---     cloe.require_signals_enum(Sig, true)
+---
+--- Later, you can use the enum with `cloe.signal()`:
+---
+---     cloe.signal(Sig.DriverDoorLatch)
+---
+--- @param enum table<string, string> input mappging from enum name to signal name
+--- @param alias boolean whether to treat signal names as alias regular expressions
+--- @return nil
+function engine.require_signals_enum(enum, alias)
+    -- TODO: Throw an error if simulation already started.
+    local signals = {}
+    if alias then
+        local aliases = {}
+        for key, sigregex in pairs(enum) do
+            table.insert(aliases, { sigregex, key })
+            table.insert(signals, key)
+        end
+        engine.alias_signals(aliases)
+    else
+        for _, signame in pairs(enum) do
+            table.insert(signals, signame)
+        end
+    end
+    engine.require_signals(signals)
+end
+
+--- Return full list of loaded signals.
+---
+--- Example:
+---
+---     local signals = cloe.signals()
+---     signals[SigName] = value
+---
+--- @return table
+function engine.signals()
+    return api.signals
+end
+
+--- Return the specified signal.
+---
+--- If the signal does not exist, nil is returned.
+---
+--- If you want to set the signal, you need to use `cloe.set_signal()`
+--- or access the value via `cloe.signals()`.
+---
+--- @param name string signal name
+--- @return any|nil # signal value
+function engine.signal(name)
+    return api.signals[name]
+end
+
+--- Set the specified signal with a value.
+---
+--- @param name string signal name
+--- @param value any signal value
+--- @return nil
+function engine.set_signal(name, value)
+    api.signals[name] = value
+end
+
+--- Record the given list of signals into the report.
+---
+--- This can be called multiple times, but if the signal is already
+--- being recorded, then an error will be raised.
+---
+--- This should be called before simulation starts,
+--- so not from a scheduled callback.
+---
+--- You can pass it a list of signals to record, or a mapping
+--- from name to
+---
+--- @param mapping table<number|string, string|fun():any> mapping from signal names
+--- @return nil
+function engine.record_signals(mapping)
+    validate("cloe.record_signals(table)", mapping)
+    api.state.report.signals = api.state.report.signals or {}
+    local signals = api.state.report.signals
+    signals.time = signals.time or {}
+    for sig, getter in pairs(mapping) do
+        if type(sig) == "number" then
+            if type(getter) ~= "string" then
+                error("positional signals can only be signal names")
+            end
+            sig = getter
+        end
+        if signals[sig] then
+            error("signal already exists: " .. sig)
+        end
+        signals[sig] = {}
+    end
+
+    engine.schedule({
+        on = "loop",
+        pin = true,
+        run = function(sync)
+            local last_time = signals.time[#signals.time]
+            local cur_time = sync:time():ms()
+            if last_time ~= cur_time then
+                table.insert(signals.time, cur_time)
+            end
+
+            for name, getter in pairs(mapping) do
+                local value
+                if type(name) == "number" then
+                    name = getter
+                end
+                if type(getter) == "string" then
+                    value = engine.signal(getter)
+                else
+                    value = getter()
+                end
+                if value == nil then
+                    -- TODO: Improve error message!
+                    error("nil value received as signal value")
+                end
+                table.insert(signals[name], value)
+            end
+        end,
+    })
+end
+
 --- Schedule a trigger.
 ---
 --- It is not recommended to use this low-level function, as it is viable to change.

engine/src/coordinator.cpp

@@ -56,8 +56,8 @@ void to_json(Json& j, const HistoryTrigger& t) {
   j["at"] = t.when;
 }
 
-Coordinator::Coordinator(sol::state_view lua)
-    : lua_(lua), executer_registrar_(trigger_registrar(Source::TRIGGER)) {}
+Coordinator::Coordinator(sol::state_view lua, cloe::DataBroker* db)
+    : lua_(lua), executer_registrar_(trigger_registrar(Source::TRIGGER)), db_(db) {}
 
 class TriggerRegistrar : public cloe::TriggerRegistrar {
  public:

engine/src/coordinator.hpp

@@ -98,7 +98,7 @@ struct HistoryTrigger {
  */
 class Coordinator {
  public:
-  Coordinator(sol::state_view lua);
+  Coordinator(sol::state_view lua, cloe::DataBroker* db);
 
   const std::vector<HistoryTrigger>& history() const { return history_; }
 
@@ -109,6 +109,8 @@ class Coordinator {
 
   sol::table register_lua_table(const std::string& field);
 
+  cloe::DataBroker* data_broker() const { return db_; }
+
   std::shared_ptr<cloe::TriggerRegistrar> trigger_registrar(cloe::Source s);
 
   void enroll(cloe::Registrar& r);
@@ -149,6 +151,7 @@ class Coordinator {
   std::map<std::string, cloe::ActionFactoryPtr> actions_;
   std::map<std::string, cloe::EventFactoryPtr> events_;
   sol::state_view lua_;
+  cloe::DataBroker* db_;  // non-owning
 
   // Execution:
   std::shared_ptr<cloe::TriggerRegistrar> executer_registrar_;

engine/src/registrar.hpp

@@ -33,14 +33,14 @@ namespace engine {
 
 class Registrar : public cloe::Registrar {
  public:
-  Registrar(std::unique_ptr<ServerRegistrar> r, Coordinator* c)
-      : server_registrar_(std::move(r)), coordinator_(c) {}
+  Registrar(std::unique_ptr<ServerRegistrar> r, Coordinator* c, cloe::DataBroker* db)
+      : server_registrar_(std::move(r)), coordinator_(c), data_broker_(db) {}
 
   Registrar(const Registrar& ar,
             const std::string& trigger_prefix,
             const std::string& static_prefix,
             const std::string& api_prefix)
-      : coordinator_(ar.coordinator_) {
+      : coordinator_(ar.coordinator_), data_broker_(ar.data_broker_) {
     if (trigger_prefix.empty()) {
       trigger_prefix_ = ar.trigger_prefix_;
     } else {
@@ -107,9 +107,15 @@ class Registrar : public cloe::Registrar {
     return coordinator_->register_lua_table(trigger_prefix_);
   }
 
+  cloe::DataBroker& data_broker() const override {
+    assert(data_broker_ != nullptr);
+    return *data_broker_;
+  }
+
  private:
   std::unique_ptr<ServerRegistrar> server_registrar_;
   Coordinator* coordinator_;       // non-owning
+  cloe::DataBroker* data_broker_;  // non-owning
   std::string trigger_prefix_;
 };