allow specifying how to handle outputs

Author: anderspkd

include/scl/simulation/context.h

@@ -18,6 +18,7 @@
 #pragma once
 
 #include <cstddef>
+#include <functional>
 #include <type_traits>
 
 #include "scl/simulation/event.h"
@@ -40,7 +41,8 @@ class SimulatorContext final {
   static SimulatorContext create(
       std::size_t number_of_parties,
       NetworkParams network_params,
-      std::vector<Simulator::SimulationHook>&& hooks);
+      std::vector<Simulator::SimulationHook>&& hooks,
+      std::optional<Simulator::OutputHandler>&& output_handler);
 
   /**
    * @brief Get the context of a particular party in the simulation.
@@ -62,6 +64,15 @@ class SimulatorContext final {
     }
   }
 
+  /**
+   * @brief Handle a protocol output.
+   */
+  void handleOutput(std::size_t pid, std::any output) {
+    if (m_output_handler.has_value()) {
+      m_output_handler.value()(pid, output);
+    }
+  }
+
   /**
    * @brief Start the clock of party.
    */
@@ -97,6 +108,9 @@ class SimulatorContext final {
     return m_number_of_parties;
   }
 
+  /**
+   * @brief Extract result of a simulation.
+   */
   Simulator::Result toResult() {
     return Simulator::Result{std::move(m_events)};
   }
@@ -107,6 +121,8 @@ class SimulatorContext final {
   std::vector<EventList> m_events;
   std::vector<Time::TimePoint> m_clocks;
   std::vector<Simulator::SimulationHook> m_hooks;
+  std::optional<Simulator::OutputHandler> m_output_handler;
+  std::vector<bool> m_cancellation_map;
 
   SimulatorContext(NetworkParams network_params)
       : m_network_params(network_params) {}
@@ -148,6 +164,13 @@ class Context {
     m_ctx.startClock(m_id);
   }
 
+  /**
+   * @brief Handle a protocol output.
+   */
+  void output(std::any output) {
+    m_ctx.handleOutput(m_id, output);
+  }
+
   /**
    * @brief Append an event to this party's list of events.
    */

include/scl/simulation/event.h

@@ -32,6 +32,10 @@ namespace scl {
 /**
  * @brief Event types.
  * @ingroup eval-sim
+ *
+ * EventType denotes the different types of events that can be spawned by
+ * simulation. All event types, with the exception of TRANSIENT, arrise due to
+ * protocol actions of one form of another.
  */
 enum class EventType {
   /**
@@ -97,7 +101,12 @@ enum class EventType {
   /**
    * @brief Event emitted when a protocol sleeps.
    */
-  SLEEP
+  SLEEP,
+
+  /**
+   * @brief Event emitted when a protocol outputs something.
+   */
+  OUTPUT
 };
 
 /**
@@ -419,6 +428,19 @@ class SleepEvent final : public Event {
   Time::Duration m_duration;
 };
 
+/**
+ * @brief Event issued when a protocol has an output.
+ * @ingroup eval-sim
+ */
+class OutputEvent final : public Event {
+ public:
+  using Event::Event;
+  void write(std::ostream& stream) override;
+  EventType type() const override {
+    return EventType::OUTPUT;
+  }
+};
+
 /**
  * @brief Tracks events added by a party during simulation.
  * @ingroup eval-sim

include/scl/simulation/simulator.h

@@ -17,6 +17,7 @@
 
 #pragma once
 
+#include <any>
 #include <concepts>
 #include <functional>
 #include <memory>
@@ -102,6 +103,11 @@ class Simulator final {
     HookType hook;
   };
 
+  /**
+   * @brief Type for functions that can be used to process protocol outputs.
+   */
+  using OutputHandler = std::function<void(std::size_t, std::any)>;
+
   /**
    * @brief Run the simulation.
    */
@@ -129,8 +135,18 @@ class Simulator final {
     m_hooks.emplace_back(SimulationHook{.trigger = {}, .hook = hook});
   }
 
+  /**
+   * @brief Instruct the simulator how to handler protocol outputs.
+   */
+  template <typename HANDLER>
+    requires(std::convertible_to<HANDLER, OutputHandler>)
+  void addOutputHandler(HANDLER handler) {
+    m_output_handler = handler;
+  }
+
  private:
   std::vector<SimulationHook> m_hooks;
+  std::optional<OutputHandler> m_output_handler;
 
   Result run(std::vector<std::unique_ptr<Protocol>>&& protocols,
              NetworkParams network_params);

src/scl/simulation/context.cc

@@ -25,13 +25,16 @@ using namespace scl;
 details::SimulatorContext details::SimulatorContext::create(
     std::size_t number_of_parties,
     NetworkParams network_params,
-    std::vector<Simulator::SimulationHook>&& hooks) {
+    std::vector<Simulator::SimulationHook>&& hooks,
+    std::optional<Simulator::OutputHandler>&& output_handler) {
   SimulatorContext ctx{network_params};
 
   ctx.m_number_of_parties = number_of_parties;
   ctx.m_events.resize(number_of_parties);
   ctx.m_clocks.resize(number_of_parties);
   ctx.m_hooks = std::move(hooks);
+  ctx.m_output_handler = std::move(output_handler);
+  ctx.m_cancellation_map.resize(number_of_parties, false);
 
   return ctx;
 }

src/scl/simulation/event.cc

@@ -176,6 +176,14 @@ void SleepEvent::write(std::ostream& stream) {
   JSON_OBJ_END;
 }
 
+void OutputEvent::write(std::ostream& stream) {
+  JSON_OBJ_START;
+  writeString(stream, "type", "OUTPUT");
+  JSON_COMMA;
+  writeTimestamp(stream, time());
+  JSON_OBJ_END;
+}
+
 #undef JSON_OBJ_START
 #undef JSON_OBJ_END
 #undef JSON_COMMA

src/scl/simulation/simulator.cc

@@ -111,7 +111,7 @@ Task<void> runProtocol(std::unique_ptr<Protocol> protocol,
       ctx.addEvent<EndEvent>(et, protocol->name());
 
       if (next.output.has_value()) {
-        // TODO: handle output
+        ctx.output(next.output);
       }
 
       // This will suspend this party, allowing someone else to run. It's not
@@ -126,6 +126,10 @@ Task<void> runProtocol(std::unique_ptr<Protocol> protocol,
 
     ctx.addEvent<StopEvent>(ctx.lastEvent()->time());
 
+  } catch (CancelledEvent&) {
+    // this party was stopped by a user supplied hook.
+    ctx.addEvent<CancelledEvent>(ctx.lastEvent()->time());
+
   } catch (std::exception& e) {
     // all exceptions are caught and discarded, but we make sure to record an
     // event.
@@ -209,9 +213,11 @@ Simulator::Result Simulator::run(
     std::vector<std::unique_ptr<Protocol>>&& protocols,
     NetworkParams network_params) {
   if (!protocols.empty()) {
-    auto sim_ctx = details::SimulatorContext::create(protocols.size(),
-                                                     network_params,
-                                                     std::move(m_hooks));
+    auto sim_ctx =
+        details::SimulatorContext::create(protocols.size(),
+                                          network_params,
+                                          std::move(m_hooks),
+                                          std::move(m_output_handler));
     auto runtime = std::make_unique<details::SimulatorRuntime>(sim_ctx);
 
     runtime->run(simulate(std::move(protocols), sim_ctx));

test/scl/simulation/test_channel.cc

@@ -31,7 +31,7 @@ using namespace std::chrono_literals;
 
 TEST_CASE("SimulatedChannel send", "[sim]") {
   auto nd = NetworkParams::create(2);
-  auto ctx = details::SimulatorContext::create(2, nd, {});
+  auto ctx = details::SimulatorContext::create(2, nd, {}, {});
 
   auto transport = std::make_shared<details::Transport>(ctx);
   ChannelId id{0, 1};
@@ -70,7 +70,7 @@ TEST_CASE("SimulatedChannel send", "[sim]") {
 
 TEST_CASE("SimulatedChannel recv", "[sim]") {
   auto nd = NetworkParams::create(2);
-  auto ctx = details::SimulatorContext::create(2, nd, {});
+  auto ctx = details::SimulatorContext::create(2, nd, {}, {});
   auto tp = std::make_shared<details::Transport>(ctx);
   ChannelId id{0, 1};
   auto channel = details::SimulatedChannel::create(id, ctx.getContext(0), tp);
@@ -106,7 +106,7 @@ TEST_CASE("SimulatedChannel recv timeout") {
   using namespace std::chrono_literals;
 
   auto nd = NetworkParams::create(2);
-  auto ctx = details::SimulatorContext::create(2, nd, {});
+  auto ctx = details::SimulatorContext::create(2, nd, {}, {});
   auto tp = std::make_shared<details::Transport>(ctx);
   ChannelId id{0, 1};
 

test/scl/simulation/test_simulator.cc

@@ -15,8 +15,10 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+#include <any>
 #include <catch2/catch_test_macros.hpp>
 #include <initializer_list>
+#include <memory>
 
 #include "scl/coro.h"
 #include "scl/protocol.h"
@@ -98,3 +100,35 @@ TEST_CASE("Simulator test", "[sim]") {
                 EventType::END,
                 EventType::STOP});
 }
+
+namespace {
+
+struct OutputProtocol final : public Protocol {
+  Task<Result> run(Env& /* ignored */) const override {
+    co_return Result::done(123);
+  }
+};
+
+}  // namespace
+
+TEST_CASE("Simulator handle output", "[sim]") {
+  auto nd = NetworkParams::create(1);
+  Simulator sim;
+
+  bool called = false;
+
+  sim.addOutputHandler([&called](std::size_t pid, std::any output) {
+    called = (pid == 0) && (output.has_value()) &&
+             (std::any_cast<int>(output) == 123);
+  });
+
+  auto res = sim.run(
+      []() {
+        std::vector<std::unique_ptr<Protocol>> p;
+        p.emplace_back(std::make_unique<OutputProtocol>());
+        return p;
+      },
+      nd);
+
+  REQUIRE(called);
+}

test/scl/simulation/test_transport.cc

@@ -29,7 +29,7 @@ using namespace std::chrono_literals;
 
 TEST_CASE("Transport send", "[sim]") {
   auto nd = NetworkParams::create(2);
-  auto ctx = details::SimulatorContext::create(2, nd, {});
+  auto ctx = details::SimulatorContext::create(2, nd, {}, {});
   ChannelId id{0, 1};
 
   details::Transport transport(ctx);
@@ -53,7 +53,7 @@ TEST_CASE("Transport send", "[sim]") {
 
 TEST_CASE("Transport ready w. limit", "[sim]") {
   auto nd = NetworkParams::create(2);
-  auto ctx = details::SimulatorContext::create(2, nd, {});
+  auto ctx = details::SimulatorContext::create(2, nd, {}, {});
   ChannelId id{0, 1};
   auto sid = id.flip();