more documentation

Author: anderspkd

include/scl/protocol.h

@@ -26,38 +26,108 @@
 
 namespace scl {
 
+/**
+ * @brief Protocol environment.
+ *
+ * Env is the interface with which a Protocol can interact with the outside
+ * world, as it were. It contains (1) a way to send and receive data to the
+ * other parties, and (2) a way to see how long the protocol has been running
+ * for.
+ */
 struct Env {
+  /**
+   * @brief The network.
+   */
   Network network;
+
+  /**
+   * @brief A clock.
+   */
   std::unique_ptr<Clock> clock;
 };
 
 struct Result;
 
+/**
+ * @brief Protocol interface.
+ *
+ * Protocol defines the "smallest possible" protocol. Namely a protocol which
+ * can be run once, and which might produce (1) some output, and (2) another
+ * protocol which can then be run next. This allows us to string multiple
+ * Protocols together in order to get a much larger protocol. For example,
+ * instead of implementing a full evaluation of a circuit, it might be easier to
+ * implement something which only evaluates a single layer of the circuit. To
+ * evaluate the full circuit, we just need stich enough of these single-layer
+ * protocols together.
+ *
+ * The following simple example illustrates this idea.
+ * @code
+ * class CountdownProtocol final : public Protocol {
+ *  public:
+ *   CountdownProtocol(int current) : m_current(current) {}
+ *   Task<Result> run(Env& ignored) const override {
+ *     std::cout << "countdown: " << m_current << "\n";
+ *     if (m_current == 0) {
+ *       co_return Result::done();
+ *     } else {
+ *       co_return Result::next(
+ *           std::make_unique<CountdownProtocol>(m_current - 1));
+ *     }
+ *   }
+ *  private:
+ *   int m_current;
+ * };
+ * @endcode
+ */
 struct Protocol {
   virtual ~Protocol() {}
 
+  /**
+   * @brief Default name of a protocol.
+   */
   constexpr static const char* DEFAULT_NAME = "N/A";
 
+  /**
+   * @brief Runs the protocol.
+   */
   virtual Task<Result> run(Env& env) const = 0;
 
+  /**
+   * @brief Returns the name of the protocol.
+   */
   virtual std::string name() const {
     return DEFAULT_NAME;
   }
 };
 
+/**
+ * @brief The result of calling Protocol::run.
+ */
 struct Result {
+  /**
+   * @brief Creates a Result with no next step, and no output.
+   */
   static Result done() {
     return Result{.next = nullptr, .output = {}};
   }
 
+  /**
+   * @brief Creates a Result with no next step, and some output.
+   */
   static Result done(std::any output) {
     return Result{.next = nullptr, .output = output};
   }
 
+  /**
+   * @brief Creates a Result with a next step, and no output.
+   */
   static Result nextStep(std::unique_ptr<Protocol> next) {
     return Result{.next = std::move(next), .output = {}};
   }
 
+  /**
+   * @brief Creates a Result with a next step, and some output.
+   */
   static Result nextStep(std::unique_ptr<Protocol> next, std::any output) {
     return Result{.next = std::move(next), .output = output};
   }

include/scl/serialization.h

@@ -25,17 +25,54 @@
 
 namespace scl {
 
+/**
+ * @brief Serializer type.
+ *
+ * A type \p T is serializable if it <code>Serializer<T></code> contains three
+ * static functions.
+ *
+ * @code
+ * struct Thing {
+ *   static std::size_t sizeOf(Thing t) {
+ *      // return the size in bytes of the object t of type Thing
+ *   }
+ *
+ *   static std::size_t write(Thing t, unsigned char* out) {
+ *      // write t to out.
+ *      // out will be guaranteed to point to at least sizeOf(t) available bytes
+ *      // return the amount of bytes written to out
+ *   }
+ *
+ *   static std::size_t read(Thing& t, const unsigned char* in) {
+ *      // read a Thing from in, store the result in t
+ *      // return the amount of bytes read from in
+ *   }
+ * }
+ * @endcode
+ *
+ * Note that no guarantees are made about the buffer passed to
+ * <code>read</code>.
+ *
+ * Serializer's mostly play a role in reading and writing to Packets for the
+ * purpose of communicating with other parties.
+ */
 template <typename T>
 struct Serializer;
 
+/**
+ * @brief Serializable concept.
+ */
 template <typename T>
 concept Serializable =
-    requires(T v, const unsigned char* in, unsigned char* out) {
+    requires(T v, T& r, const unsigned char* in, unsigned char* out) {
       { Serializer<T>::sizeOf(v) } -> std::same_as<std::size_t>;
       { Serializer<T>::write(v, out) } -> std::same_as<std::size_t>;
-      { Serializer<T>::read(v, in) } -> std::same_as<std::size_t>;
+      { Serializer<T>::read(r, in) } -> std::same_as<std::size_t>;
     };
 
+/**
+ * @brief Serializer for trivially copyable types.
+ */
 template <typename T>
   requires(std::is_trivially_copyable_v<T>)
 struct Serializer<T> {
@@ -54,7 +91,10 @@ struct Serializer<T> {
   }
 };
 
-template <typename T>
+/**
+ * @brief Serializer for STL vectors of something serializable.
+ */
+template <Serializable T>
 struct Serializer<std::vector<T>> {
   using VecSizeType = std::uint32_t;
 

include/scl/simulation/channel_id.h

@@ -24,7 +24,7 @@
 namespace scl {
 
 /**
- * @brief x
+ * @brief Identifier used for Channels.
  */
 struct ChannelId final {
   std::size_t local;

include/scl/simulation/event.h

@@ -102,12 +102,14 @@ enum class EventType {
 
 /**
  * @brief Base class for all events.
+ *
+ * All events in SCL's simulator inheret from Event. The most basic Event is
+ * effectively just a timestamp telling us when the event was generated.
  */
 class Event {
  public:
   /**
    * @brief Constructor.
-   * @param timestamp the time that the event was issued.
    */
   Event(Time::Duration timestamp) : m_timestamp(timestamp) {}
 
@@ -136,6 +138,7 @@ class Event {
 
 /**
  * @brief Event issued when a party starts executing a Protocol.
+ * @see EndEvent
  */
 class BeginEvent final : public Event {
  public:
@@ -148,6 +151,10 @@ class BeginEvent final : public Event {
     return EventType::BEGIN;
   }
 
+  /**
+   * @brief The name of protocol.
+   * @see Protocol::name
+   */
   std::string_view name() const {
     return m_name;
   }
@@ -158,6 +165,7 @@ class BeginEvent final : public Event {
 
 /**
  * @brief Event issued when a party finishes executing a Protocol.
+ * @see BeginEvent
  */
 class EndEvent final : public Event {
  public:
@@ -170,6 +178,10 @@ class EndEvent final : public Event {
     return EventType::END;
   }
 
+  /**
+   * @brief The name of protocol.
+   * @see Protocol::name
+   */
   std::string_view name() const {
     return m_name;
   }
@@ -180,6 +192,7 @@ class EndEvent final : public Event {
 
 /**
  * @brief Event issued when a party starts running.
+ * @see StopEvent
  */
 class StartEvent final : public Event {
  public:
@@ -192,6 +205,7 @@ class StartEvent final : public Event {
 
 /**
  * @brief Event issued when a party stops running.
+ * @see StartEvent
  */
 class StopEvent final : public Event {
  public:
@@ -209,6 +223,10 @@ class KilledEvent final : public Event {
  public:
   KilledEvent(Time::Duration timestamp, const std::string& reason)
       : Event(timestamp), m_reason(reason) {}
+
+  /**
+   * @brief The exception's what message.
+   */
   std::string reason() const {
     return m_reason;
   }
@@ -241,6 +259,9 @@ class ChannelEvent : public Event {
   ChannelEvent(Time::Duration timestamp, ChannelId id)
       : Event(timestamp), m_id(id) {}
 
+  /**
+   * @brief The identifier of the channel this event pertains to.
+   */
   ChannelId id() const {
     return m_id;
   }
@@ -255,9 +276,7 @@ class ChannelEvent : public Event {
 class CloseEvent final : public ChannelEvent {
  public:
   using ChannelEvent::ChannelEvent;
-
   void write(std::ostream& stream) override;
-
   EventType type() const override {
     return EventType::CHANNEL_CLOSE;
   }
@@ -271,6 +290,9 @@ class ChannelDataEvent : public ChannelEvent {
   ChannelDataEvent(Time::Duration timestamp, ChannelId id, std::size_t amount)
       : ChannelEvent(timestamp, id), m_amount(amount) {}
 
+  /**
+   * @brief The amount of data sent or received.
+   */
   std::size_t amount() const {
     return m_amount;
   }
@@ -303,6 +325,9 @@ class RecvEvent final : public ChannelDataEvent {
   }
 };
 
+/**
+ * @brief Event issued when a party times out during a recv call.
+ */
 class RecvTimeoutEvent final : public ChannelEvent {
  public:
   using ChannelEvent::ChannelEvent;
@@ -325,6 +350,9 @@ class PollEvent final : public ChannelEvent {
     return EventType::CHANNEL_POLL;
   }
 
+  /**
+   * @brief The result of the Channel::poll call.
+   */
   bool result() const {
     return m_result;
   }
@@ -333,6 +361,9 @@ class PollEvent final : public ChannelEvent {
   bool m_result;
 };
 
+/**
+ * @brief Event issued when a party sleeps.
+ */
 class SleepEvent final : public Event {
  public:
   SleepEvent(Time::Duration timestamp, Time::Duration duration)
@@ -344,6 +375,9 @@ class SleepEvent final : public Event {
     return EventType::SLEEP;
   }
 
+  /**
+   * @brief The amount of time a party slept.
+   */
   Time::Duration duration() const {
     return m_duration;
   }
@@ -352,9 +386,22 @@ class SleepEvent final : public Event {
   Time::Duration m_duration;
 };
 
+namespace details {
+
+/**
+ * @brief Tracks events added by a party during simulation.
+ *
+ * EventList is mostly just a wrapper around an STL vector of Event
+ * pointers. Minor book keeping is done to ensure that all events of type
+ * EventType::TRANSIENT only appear of the head of the list.
+ */
 class EventList final {
  public:
   EventList();
+
+  /**
+   * @brief Add a new event by in-place construction.
+   */
   template <typename EVENT, typename... ARGS>
     requires(std::is_base_of_v<Event, EVENT>)
   void add(ARGS... args) {
@@ -403,6 +450,7 @@ class EventList final {
   std::vector<std::unique_ptr<Event>> m_events;
 };
 
+}  // namespace details
 }  // namespace scl
 
 #endif  // SCL_SIMULATION_EVENT_H