move stuff into details namespace

Author: anderspkd

include/scl/primitives/digest.h

@@ -28,17 +28,12 @@ namespace scl {
 
 /**
  * @brief A digest of some bitsize.
- * @tparam Bits the bitsize of the digest
- *
- * This type is effectively <code>std::array<unsigned char, N / 8</code>.
  */
 template <std::size_t BITS>
 using Digest = std::array<unsigned char, BITS / 8>;
 
 /**
- * @brief Convert a digest to a string.
- * @param digest the digest
- * @return a hex representation of the digest.
+ * @brief Convert a digest to a hex string.
  */
 template <typename DIGEST>
 std::string digestToString(const DIGEST& digest) {

include/scl/simulation/channel.h

@@ -24,7 +24,7 @@
 #include "scl/simulation/context.h"
 #include "scl/simulation/transport.h"
 
-namespace scl {
+namespace scl::details {
 
 class SimulatedChannel final : public Channel {
  public:
@@ -52,6 +52,6 @@ class SimulatedChannel final : public Channel {
   std::shared_ptr<Transport> m_transport;
 };
 
-}  // namespace scl
+}  // namespace scl::details
 
 #endif  // SCL_SIMULATION_CHANNEL_H

include/scl/simulation/channel_id.h

@@ -39,14 +39,15 @@ struct ChannelId final {
 
 }  // namespace scl
 
-/**
- * @brief x
- */
+/// @cond
+
 template <>
 struct std::hash<scl::ChannelId> {
   std::size_t operator()(const scl::ChannelId& channel_id) const {
     return channel_id.local ^ (channel_id.remote << 32);
   }
 };
 
+/// @endcond
+
 #endif  // SCL_SIMULATION_CHANNEL_ID_H

include/scl/simulation/context.h

@@ -25,7 +25,7 @@
 #include "scl/simulation/network_description.h"
 #include "scl/simulation/simulator.h"
 
-namespace scl {
+namespace scl::details {
 
 class Context;
 
@@ -34,6 +34,9 @@ class Context;
  */
 class SimulatorContext final {
  public:
+  /**
+   * @brief Create a new simulation context object.
+   */
   static SimulatorContext create(
       NetworkDescription network_desc,
       std::vector<Simulator::SimulationHook>&& hooks);
@@ -43,6 +46,9 @@ class SimulatorContext final {
    */
   Context getContext(std::size_t id);
 
+  /**
+   * @brief Add an event to
+   */
   template <typename EVENT, typename... ARGS>
     requires(std::is_base_of_v<Event, EVENT>)
   void addEvent(std::size_t pid, ARGS... args) {
@@ -125,6 +131,6 @@ inline Context SimulatorContext::getContext(std::size_t id) {
   return Context{*this, id};
 }
 
-}  // namespace scl
+}  // namespace scl::details
 
 #endif  // SCL_SIMULATION_CONTEXT_H

include/scl/simulation/network_description.h

@@ -26,28 +26,76 @@
 
 namespace scl {
 
+/**
+ * @brief Describes the characterists of a channel.
+ */
 struct ChannelDescription final {
+  /**
+   * @brief The channel bandwidth, in bits/s.
+   */
   std::size_t bandwith;
+
+  /**
+   * @brief The channel latency, in microseconds.
+   */
   std::size_t latency;
+
+  /**
+   * @brief The latency variance, in microseconds.
+   */
   std::size_t latency_jitter;
+
+  /**
+   * @brief The channel package loss, a value in [0, 1).
+   */
   float loss;
 };
 
+/**
+ * @brief Describes a network in terms of its channels.
+ */
 class NetworkDescription final {
  public:
+  /**
+   * @brief The parameters of a channel at a given point in time.
+   */
   struct ChannelParameters {
+    /**
+     * @brief The current channel bandwidth.
+     */
     std::size_t bandwidth;
+
+    /**
+     * @brief The current channel latency.
+     */
     std::size_t latency;
+
+    /**
+     * @brief The current channel packege loss.
+     */
     float loss;
   };
 
+  /**
+   * @brief Create a default LAN network.
+   */
   static NetworkDescription createDefaultLAN(std::size_t size);
+
+  /**
+   * @brief Create a default WAN network.
+   */
   static NetworkDescription createDefaultWAN(std::size_t size);
 
+  /**
+   * @brief The size of the network.
+   */
   std::size_t size() const {
     return m_size;
   }
 
+  /**
+   * @brief Get the parameters of a particular channel.
+   */
   ChannelParameters getChannel(ChannelId id);
 
  private:

include/scl/simulation/runtime.h

@@ -23,7 +23,7 @@
 #include "scl/coro/runtime.h"
 #include "scl/simulation/context.h"
 
-namespace scl {
+namespace scl::details {
 
 class SimulatorRuntime final : public Runtime {
  private:
@@ -60,6 +60,6 @@ class SimulatorRuntime final : public Runtime {
   std::list<Coro> m_tq;
 };
 
-}  // namespace scl
+}  // namespace scl::details
 
 #endif  // SCL_SIMULATION_RUNTIME_H

include/scl/simulation/transport.h

@@ -26,7 +26,7 @@
 #include "scl/simulation/context.h"
 #include "scl/time.h"
 
-namespace scl {
+namespace scl::details {
 
 class Transport {
  public:
@@ -49,6 +49,6 @@ class Transport {
       m_pqs;
 };
 
-}  // namespace scl
+}  // namespace scl::details
 
 #endif  // SCL_SIMULATION_TRANSPORT_H

include/scl/time.h

@@ -53,8 +53,20 @@ inline long double timeToMillis(Time::Duration time) {
   return duration<long double, std::milli>(time).count();
 }
 
+/**
+ * @brief Clock interface.
+ *
+ * Clock is used within protocols to get the time elapsed since the protocol was
+ * first started. The reason for requiring an interface to get this information
+ * is because protocols might be run in a simulation, in which case wall-clock
+ * time wouldn't be accurate.
+ */
 struct Clock {
   virtual ~Clock();
+
+  /**
+   * @brief Read the value of the clock.
+   */
   virtual Time::Duration read() const = 0;
 };
 

src/scl/simulation/channel.cc

@@ -22,18 +22,18 @@
 #include "scl/simulation/transport.h"
 #include "scl/time.h"
 
-void scl::SimulatedChannel::close() {
+void scl::details::SimulatedChannel::close() {
   m_ctx.addEvent<scl::CloseEvent>(m_ctx.elapsedTime(), m_id);
 }
 
-scl::Task<void> scl::SimulatedChannel::send(Packet&& packet) {
+scl::Task<void> scl::details::SimulatedChannel::send(Packet&& packet) {
   const auto et = m_ctx.elapsedTime();
   m_ctx.addEvent<SendEvent>(et, m_id, packet.size());
   m_transport->send(et, m_id, std::move(packet));
   co_return;
 }
 
-scl::Task<void> scl::SimulatedChannel::send(const Packet& packet) {
+scl::Task<void> scl::details::SimulatedChannel::send(const Packet& packet) {
   const auto et = m_ctx.elapsedTime();
   m_ctx.addEvent<SendEvent>(et, m_id, packet.size());
   m_transport->send(et, m_id, packet);
@@ -71,10 +71,10 @@ class RecvPendingEvent final : public scl::ChannelEvent {
 
 // Awaitable that checks if the transport is ready.
 struct ReadyChecker {
-  scl::Transport* transport;
+  scl::details::Transport* transport;
   scl::ChannelId id;
   RecvPendingEvent* event;
-  scl::Context& ctx;
+  scl::details::Context& ctx;
 
   bool operator()() {
     const auto is_ready = transport->ready(id);
@@ -91,7 +91,7 @@ struct ReadyChecker {
 
 }  // namespace
 
-scl::Task<scl::Packet> scl::SimulatedChannel::recv() {
+scl::Task<scl::Packet> scl::details::SimulatedChannel::recv() {
   const auto et = m_ctx.elapsedTime();
 
   m_ctx.addEvent<RecvPendingEvent>(et, m_id);
@@ -111,10 +111,10 @@ namespace {
 
 // Ready checker which capable of timing out
 struct TimeoutReadyChecker {
-  scl::Transport* transport;
+  scl::details::Transport* transport;
   scl::ChannelId id;
   RecvPendingEvent* event;
-  scl::Context& ctx;
+  scl::details::Context& ctx;
   scl::Time::Duration timeout_rem;
 
   bool operator()() {
@@ -135,7 +135,7 @@ struct TimeoutReadyChecker {
 
 }  // namespace
 
-scl::Task<std::optional<scl::Packet>> scl::SimulatedChannel::recv(
+scl::Task<std::optional<scl::Packet>> scl::details::SimulatedChannel::recv(
     Time::Duration timeout) {
   // const auto et = m_ctx.elapsedTime();
 
@@ -149,7 +149,7 @@ scl::Task<std::optional<scl::Packet>> scl::SimulatedChannel::recv(
   co_return {};
 }
 
-scl::Task<bool> scl::SimulatedChannel::poll() {
+scl::Task<bool> scl::details::SimulatedChannel::poll() {
   const auto et = m_ctx.elapsedTime();
   Transport::PollResult pr;
 

src/scl/simulation/context.cc

@@ -19,9 +19,7 @@
 
 #include "scl/simulation/event.h"
 
-using namespace scl;
-
-SimulatorContext SimulatorContext::create(
+scl::details::SimulatorContext scl::details::SimulatorContext::create(
     NetworkDescription network_desc,
     std::vector<Simulator::SimulationHook>&& hooks) {
   SimulatorContext ctx{network_desc};
@@ -33,7 +31,7 @@ SimulatorContext SimulatorContext::create(
   return ctx;
 }
 
-void SimulatorContext::runHooks(std::size_t pid, Event* event) {
+void scl::details::SimulatorContext::runHooks(std::size_t pid, Event* event) {
   for (auto& [trigger, hook] : m_hooks) {
     // if the trigger was specified, then the hook is only run if the current
     // event matches the trigger type.