wireforge 0.1.0__py3-none-any.whl

wireforge/_data/runtime/include/wireforge/link.hpp

@@ -0,0 +1,223 @@
+/**
+ * @file link.hpp
+ * @brief Connects a transport, a frame decoder and a dispatcher with preallocated buffers.
+ */
+#ifndef WIREFORGE_LINK_HPP
+#define WIREFORGE_LINK_HPP
+
+#include "wireforge/lock.hpp"
+#include "wireforge/ring_buffer.hpp"
+#include "wireforge/span.hpp"
+#include "wireforge/status.hpp"
+#include "wireforge/transport.hpp"
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <type_traits>
+#include <utility>
+
+namespace wireforge {
+
+/// @brief Decoder type for interfaces without framing: every transport read is one frame.
+struct Unframed {};
+
+/// @brief Outcome of one Link::poll() call.
+struct PollResult {
+    std::size_t frames = 0U;        ///< Frames dispatched successfully.
+    std::size_t errors = 0U;        ///< Frames rejected by the decoder or the dispatcher.
+    Status last_error = Status::Ok; ///< The most recent error, Status::Ok when none.
+};
+
+/// @brief Statistics of a link; readable from any thread.
+struct LinkCounters {
+    RelaxedCounter rx_bytes;  ///< Bytes received from the transport.
+    RelaxedCounter tx_bytes;  ///< Bytes accepted by the transport.
+    RelaxedCounter tx_frames; ///< Frames sent completely.
+    RelaxedCounter tx_errors; ///< Frames not sent (encoder error or transport full).
+};
+
+/**
+ * @brief One communication link: receive path transport -> ring -> decoder -> dispatcher, and a
+ *        transmit path that encodes into a preallocated buffer and hands it to the transport.
+ *
+ * Thread safety: poll() runs on a single receiving thread. send() and send_frame() may be called
+ * from several threads; they are serialized by lock policy @p L. The transport, decoder and
+ * dispatcher are referenced and must outlive the link.
+ * @tparam Transport Type satisfying the transport requirements (or ITransport).
+ * @tparam Decoder FrameDecoder<...> or Unframed.
+ * @tparam Dispatch Dispatcher<...> or RawDispatcher<...> (anything with dispatch_frame()).
+ * @tparam MaxFrame Largest frame in bytes (size of the rx and tx frame buffers).
+ * @tparam RxCapacity Capacity of the receive ring in bytes (at least MaxFrame).
+ * @tparam L Lock policy of the transmit path.
+ */
+template <typename Transport, typename Decoder, typename Dispatch, std::size_t MaxFrame,
+          std::size_t RxCapacity = 2U * MaxFrame, typename L = DefaultLock>
+class Link {
+    static_assert(is_transport_v<Transport>, "Transport must satisfy the transport requirements");
+    static_assert(RxCapacity >= MaxFrame, "the receive ring must hold a whole frame");
+    static_assert(is_lock_policy_v<L>, "L must satisfy the lock policy contract");
+    static constexpr bool kUnframed = std::is_same_v<Decoder, Unframed>;
+
+public:
+    /**
+     * @param transport Byte transport.
+     * @param decoder Frame decoder (ignored for Unframed).
+     * @param dispatcher Receives every complete frame.
+     */
+    Link(Transport& transport, Decoder& decoder, const Dispatch& dispatcher) noexcept
+        : transport_(&transport), decoder_(&decoder), dispatcher_(&dispatcher) {}
+
+    /**
+     * @brief Reads everything the transport has and dispatches every complete frame.
+     *
+     * Call regularly from the receiving thread. For Unframed links each non-empty transport read
+     * is dispatched as one frame; a read with more than MaxFrame bytes is rejected as
+     * Status::InvalidLength and its bytes are dropped.
+     */
+    PollResult poll() noexcept {
+        PollResult result;
+        if constexpr (kUnframed) {
+            const std::size_t received = transport_->receive(Span<std::uint8_t>(rx_frame_));
+            counters_.rx_bytes.add(received);
+            if (received == MaxFrame && discard_excess() > 0U) {
+                record(result, Status::InvalidLength);
+            } else if (received > 0U) {
+                record(result, dispatcher_->dispatch_frame(
+                                   Span<const std::uint8_t>(rx_frame_.data(), received)));
+            }
+        } else {
+            for (;;) {
+                const std::size_t received = fill_ring();
+                drain_ring(result);
+                if (received == 0U) {
+                    break;
+                }
+            }
+        }
+        return result;
+    }
+
+    /**
+     * @brief Encodes a frame into the transmit buffer and sends it.
+     * @param encode Callable `Status(Span<std::uint8_t> buffer, std::size_t& size)` that writes
+     *               one frame into @p buffer and sets @p size; called under the transmit lock.
+     * @return The encoder's error, Status::BufferTooSmall when the transport did not accept the
+     *         whole frame, otherwise Status::Ok.
+     */
+    template <typename Encode> Status send(Encode&& encode) noexcept {
+        const ScopedLock<L> guard(tx_lock_);
+        std::size_t size = 0U;
+        const Status status = std::forward<Encode>(encode)(Span<std::uint8_t>(tx_frame_), size);
+        if (status != Status::Ok || size > MaxFrame) {
+            counters_.tx_errors.increment();
+            return status != Status::Ok ? status : Status::BufferTooSmall;
+        }
+        return transmit(Span<const std::uint8_t>(tx_frame_.data(), size));
+    }
+
+    /**
+     * @brief Sends an already encoded frame.
+     * @return Status::BufferTooSmall when the transport did not accept the whole frame.
+     */
+    Status send_frame(Span<const std::uint8_t> frame) noexcept {
+        const ScopedLock<L> guard(tx_lock_);
+        return transmit(frame);
+    }
+
+    /// @brief Statistics since construction.
+    [[nodiscard]] const LinkCounters& counters() const noexcept { return counters_; }
+
+private:
+    static void record(PollResult& result, Status status) noexcept {
+        if (status == Status::Ok) {
+            ++result.frames;
+        } else {
+            ++result.errors;
+            result.last_error = status;
+        }
+    }
+
+    // Drops what the transport still holds after a read that filled the frame buffer: an
+    // unframed read longer than MaxFrame is one oversized frame. Returns the dropped count.
+    std::size_t discard_excess() noexcept {
+        std::array<std::uint8_t, kChunk> chunk{};
+        std::size_t total = 0U;
+        for (;;) {
+            const std::size_t received = transport_->receive(Span<std::uint8_t>(chunk));
+            if (received == 0U) {
+                return total;
+            }
+            counters_.rx_bytes.add(received);
+            total += received;
+        }
+    }
+
+    // Moves bytes from the transport into the ring until either is exhausted; returns the count.
+    std::size_t fill_ring() noexcept {
+        std::array<std::uint8_t, kChunk> chunk{};
+        std::size_t total = 0U;
+        while (rx_ring_.free_space() > 0U) {
+            const std::size_t wanted =
+                rx_ring_.free_space() < chunk.size() ? rx_ring_.free_space() : chunk.size();
+            const std::size_t received =
+                transport_->receive(Span<std::uint8_t>(chunk).first(wanted));
+            if (received == 0U) {
+                break;
+            }
+            counters_.rx_bytes.add(received);
+            static_cast<void>(rx_ring_.write(Span<const std::uint8_t>(chunk.data(), received)));
+            total += received;
+        }
+        return total;
+    }
+
+    void drain_ring(PollResult& result) noexcept {
+        for (;;) {
+            std::size_t size = 0U;
+            const Status status = decoder_->next(rx_ring_, Span<std::uint8_t>(rx_frame_), size);
+            if (status == Status::Truncated) {
+                return;
+            }
+            if (status != Status::Ok) {
+                record(result, status);
+                continue;
+            }
+            record(result,
+                   dispatcher_->dispatch_frame(Span<const std::uint8_t>(rx_frame_.data(), size)));
+        }
+    }
+
+    Status transmit(Span<const std::uint8_t> frame) noexcept {
+        std::size_t sent = 0U;
+        while (sent < frame.size()) {
+            const std::size_t accepted = transport_->send(frame.subspan(sent));
+            if (accepted == 0U) {
+                break;
+            }
+            sent += accepted;
+        }
+        counters_.tx_bytes.add(sent);
+        if (sent != frame.size()) {
+            counters_.tx_errors.increment();
+            return Status::BufferTooSmall;
+        }
+        counters_.tx_frames.increment();
+        return Status::Ok;
+    }
+
+    static constexpr std::size_t kChunk = 64U;
+
+    Transport* transport_;
+    Decoder* decoder_;
+    const Dispatch* dispatcher_;
+    StaticSpscByteRing<RxCapacity> rx_ring_;
+    std::array<std::uint8_t, MaxFrame> rx_frame_{};
+    std::array<std::uint8_t, MaxFrame> tx_frame_{};
+    L tx_lock_;
+    LinkCounters counters_;
+};
+
+} // namespace wireforge
+
+#endif // WIREFORGE_LINK_HPP

wireforge/_data/runtime/include/wireforge/lock.hpp

@@ -0,0 +1,146 @@
+/**
+ * @file lock.hpp
+ * @brief Lock policies, a scoped guard and a statistics counter.
+ *
+ * A lock policy is a default-constructible type with `void lock() noexcept` and
+ * `void unlock() noexcept`. Runtime classes take the policy as a template parameter, so a port to
+ * an RTOS supplies its own type and never needs `<mutex>`:
+ * @code
+ * struct RtosLock {
+ *     void lock() noexcept { take(semaphore); }
+ *     void unlock() noexcept { give(semaphore); }
+ *     Semaphore semaphore;
+ * };
+ * @endcode
+ */
+#ifndef WIREFORGE_LOCK_HPP
+#define WIREFORGE_LOCK_HPP
+
+#include "wireforge/config.hpp"
+
+#include <atomic>
+#include <cstdint>
+#include <type_traits>
+#include <utility>
+
+#if !defined(WIREFORGE_NO_STD_MUTEX)
+#include <mutex>
+#endif
+
+namespace wireforge {
+
+/// @brief Detects whether @p L satisfies the lock policy requirements.
+template <typename L, typename = void> struct is_lock_policy : std::false_type {};
+
+/// @cond INTERNAL
+template <typename L>
+struct is_lock_policy<
+    L, std::void_t<decltype(std::declval<L&>().lock()), decltype(std::declval<L&>().unlock())>>
+    : std::bool_constant<std::is_default_constructible_v<L> &&
+                         noexcept(std::declval<L&>().lock()) &&
+                         noexcept(std::declval<L&>().unlock())> {};
+/// @endcond
+
+/// @brief true when @p L is a lock policy.
+template <typename L> inline constexpr bool is_lock_policy_v = is_lock_policy<L>::value;
+
+/// @brief Lock policy that does nothing: for single-threaded use or externally serialized access.
+class NullLock {
+public:
+    /// @brief Does nothing.
+    static constexpr void lock() noexcept {}
+    /// @brief Does nothing.
+    static constexpr void unlock() noexcept {}
+};
+
+#if !defined(WIREFORGE_NO_STD_MUTEX)
+/**
+ * @brief Lock policy backed by `std::mutex`.
+ * @note A failing `std::mutex::lock` calls `std::terminate` because lock() is noexcept.
+ */
+class StdMutexLock {
+public:
+    /// @brief Creates an unlocked mutex.
+    StdMutexLock() noexcept = default;
+    ~StdMutexLock() = default;
+    StdMutexLock(const StdMutexLock&) = delete;
+    StdMutexLock& operator=(const StdMutexLock&) = delete;
+    StdMutexLock(StdMutexLock&&) = delete;
+    StdMutexLock& operator=(StdMutexLock&&) = delete;
+
+    /// @brief Blocks until the mutex is acquired.
+    void lock() noexcept { mutex_.lock(); }
+    /// @brief Releases the mutex.
+    void unlock() noexcept { mutex_.unlock(); }
+
+private:
+    std::mutex mutex_;
+};
+#endif
+
+#if defined(WIREFORGE_DEFAULT_LOCK)
+using DefaultLock = WIREFORGE_DEFAULT_LOCK;
+#elif !defined(WIREFORGE_NO_STD_MUTEX)
+/**
+ * @brief Lock policy used when none is given.
+ *
+ * `WIREFORGE_DEFAULT_LOCK` when defined, otherwise StdMutexLock, or NullLock when
+ * `WIREFORGE_NO_STD_MUTEX` is defined.
+ */
+using DefaultLock = StdMutexLock;
+#else
+using DefaultLock = NullLock;
+#endif
+
+static_assert(is_lock_policy_v<NullLock>, "NullLock must satisfy the lock policy contract");
+static_assert(is_lock_policy_v<DefaultLock>, "DefaultLock must satisfy the lock policy contract");
+
+/**
+ * @brief Acquires a lock on construction and releases it on destruction.
+ * @tparam L Lock policy.
+ */
+template <typename L> class ScopedLock {
+    static_assert(is_lock_policy_v<L>, "L must satisfy the lock policy contract");
+
+public:
+    /// @brief Locks @p lock until this guard is destroyed.
+    explicit ScopedLock(L& lock) noexcept : lock_(lock) { lock_.lock(); }
+    ~ScopedLock() { lock_.unlock(); }
+    ScopedLock(const ScopedLock&) = delete;
+    ScopedLock& operator=(const ScopedLock&) = delete;
+    ScopedLock(ScopedLock&&) = delete;
+    ScopedLock& operator=(ScopedLock&&) = delete;
+
+private:
+    L& lock_;
+};
+
+/**
+ * @brief 32-bit counter that one thread updates and any thread reads.
+ *
+ * Uses relaxed atomics: the value is informational (statistics) and does not order other memory
+ * accesses.
+ */
+class RelaxedCounter {
+public:
+    /// @brief Adds one.
+    void increment() noexcept { value_.fetch_add(1U, std::memory_order_relaxed); }
+    /// @brief Adds @p amount, an unsigned integer (wraps around modulo 2^32).
+    template <typename U> void add(U amount) noexcept {
+        static_assert(std::is_unsigned_v<U>, "counters add unsigned amounts");
+        value_.fetch_add(static_cast<std::uint32_t>(amount), std::memory_order_relaxed);
+    }
+    /// @brief Sets the counter to zero.
+    void reset() noexcept { value_.store(0U, std::memory_order_relaxed); }
+    /// @brief Current value.
+    [[nodiscard]] std::uint32_t load() const noexcept {
+        return value_.load(std::memory_order_relaxed);
+    }
+
+private:
+    std::atomic<std::uint32_t> value_{0U};
+};
+
+} // namespace wireforge
+
+#endif // WIREFORGE_LOCK_HPP

wireforge/_data/runtime/include/wireforge/ring_buffer.hpp

@@ -0,0 +1,226 @@
+/**
+ * @file ring_buffer.hpp
+ * @brief Byte ring buffers: lock-free single-producer/single-consumer and lock-protected variants.
+ */
+#ifndef WIREFORGE_RING_BUFFER_HPP
+#define WIREFORGE_RING_BUFFER_HPP
+
+#include "wireforge/lock.hpp"
+#include "wireforge/span.hpp"
+
+#include <array>
+#include <atomic>
+#include <cstddef>
+#include <cstdint>
+
+namespace wireforge {
+
+/**
+ * @brief Lock-free single-producer/single-consumer byte ring over caller-provided storage.
+ *
+ * Thread safety: write() from exactly one producer thread; peek(), read() and consume() from
+ * exactly one consumer thread; size queries from either. reset() requires both sides to be idle.
+ * The whole storage is usable (no sentinel byte). Data written by the producer is visible to the
+ * consumer once write() returns.
+ */
+class SpscByteRing {
+public:
+    /// @brief Uses @p storage as the ring memory; it must outlive the ring.
+    explicit SpscByteRing(Span<std::uint8_t> storage) noexcept : storage_(storage) {}
+    ~SpscByteRing() = default;
+    SpscByteRing(const SpscByteRing&) = delete;
+    SpscByteRing& operator=(const SpscByteRing&) = delete;
+    SpscByteRing(SpscByteRing&&) = delete;
+    SpscByteRing& operator=(SpscByteRing&&) = delete;
+
+    /// @brief Size of the storage in bytes.
+    [[nodiscard]] std::size_t capacity() const noexcept { return storage_.size(); }
+
+    /// @brief Bytes available to the consumer.
+    [[nodiscard]] std::size_t size() const noexcept {
+        return distance(head_.load(std::memory_order_acquire),
+                        tail_.load(std::memory_order_acquire));
+    }
+    /// @brief Bytes the producer can still write.
+    [[nodiscard]] std::size_t free_space() const noexcept { return capacity() - size(); }
+    /// @brief true when no bytes are available.
+    [[nodiscard]] bool empty() const noexcept { return size() == 0U; }
+
+    /**
+     * @brief Producer: appends as many bytes of @p bytes as fit.
+     * @return Number of bytes stored (less than bytes.size() when the ring is full).
+     */
+    std::size_t write(Span<const std::uint8_t> bytes) noexcept {
+        const std::size_t tail = tail_.load(std::memory_order_relaxed);
+        const std::size_t head = head_.load(std::memory_order_acquire);
+        const std::size_t space = capacity() - distance(head, tail);
+        const std::size_t count = bytes.size() < space ? bytes.size() : space;
+        std::size_t slot = wrap(tail);
+        for (std::size_t index = 0U; index < count; ++index) {
+            storage_[slot] = bytes[index];
+            slot = slot + 1U == capacity() ? 0U : slot + 1U;
+        }
+        tail_.store(advance(tail, count), std::memory_order_release);
+        return count;
+    }
+
+    /**
+     * @brief Consumer: copies bytes without consuming them.
+     * @param out Destination; up to out.size() bytes are copied.
+     * @param offset Number of available bytes to skip before copying.
+     * @return Number of bytes copied.
+     */
+    std::size_t peek(Span<std::uint8_t> out, std::size_t offset = 0U) const noexcept {
+        const std::size_t head = head_.load(std::memory_order_relaxed);
+        const std::size_t tail = tail_.load(std::memory_order_acquire);
+        const std::size_t used = distance(head, tail);
+        if (offset >= used) {
+            return 0U;
+        }
+        const std::size_t available = used - offset;
+        const std::size_t count = out.size() < available ? out.size() : available;
+        std::size_t slot = wrap(advance(head, offset));
+        for (std::size_t index = 0U; index < count; ++index) {
+            out[index] = storage_[slot];
+            slot = slot + 1U == capacity() ? 0U : slot + 1U;
+        }
+        return count;
+    }
+
+    /**
+     * @brief Consumer: discards up to @p count bytes.
+     * @return Number of bytes discarded.
+     */
+    std::size_t consume(std::size_t count) noexcept {
+        const std::size_t head = head_.load(std::memory_order_relaxed);
+        const std::size_t tail = tail_.load(std::memory_order_acquire);
+        const std::size_t used = distance(head, tail);
+        const std::size_t discarded = count < used ? count : used;
+        head_.store(advance(head, discarded), std::memory_order_release);
+        return discarded;
+    }
+
+    /**
+     * @brief Consumer: copies and consumes up to out.size() bytes.
+     * @return Number of bytes read.
+     */
+    std::size_t read(Span<std::uint8_t> out) noexcept { return consume(peek(out)); }
+
+    /// @brief Drops all content. Neither producer nor consumer may run concurrently.
+    void reset() noexcept {
+        head_.store(0U, std::memory_order_relaxed);
+        tail_.store(0U, std::memory_order_release);
+    }
+
+private:
+    // Indices run in [0, 2 * capacity) so that "full" and "empty" are distinguishable.
+    [[nodiscard]] std::size_t distance(std::size_t head, std::size_t tail) const noexcept {
+        return tail >= head ? tail - head : (2U * capacity()) - head + tail;
+    }
+    [[nodiscard]] std::size_t advance(std::size_t index, std::size_t count) const noexcept {
+        const std::size_t limit = 2U * capacity();
+        const std::size_t next = index + count;
+        return next >= limit ? next - limit : next;
+    }
+    [[nodiscard]] std::size_t wrap(std::size_t index) const noexcept {
+        return index >= capacity() ? index - capacity() : index;
+    }
+
+    Span<std::uint8_t> storage_;
+    std::atomic<std::size_t> head_{0U};
+    std::atomic<std::size_t> tail_{0U};
+};
+
+/**
+ * @brief Byte ring for any number of producers and consumers.
+ *
+ * Every operation of an SpscByteRing runs under lock policy @p L.
+ * @tparam L Lock policy (see lock.hpp).
+ */
+template <typename L = DefaultLock> class LockedByteRing {
+    static_assert(is_lock_policy_v<L>, "L must satisfy the lock policy contract");
+
+public:
+    /// @brief Uses @p storage as the ring memory; it must outlive the ring.
+    explicit LockedByteRing(Span<std::uint8_t> storage) noexcept : ring_(storage) {}
+
+    /// @copydoc SpscByteRing::capacity
+    [[nodiscard]] std::size_t capacity() const noexcept { return ring_.capacity(); }
+    /// @copydoc SpscByteRing::size
+    [[nodiscard]] std::size_t size() const noexcept {
+        const ScopedLock<L> guard(lock_);
+        return ring_.size();
+    }
+    /// @copydoc SpscByteRing::free_space
+    [[nodiscard]] std::size_t free_space() const noexcept {
+        const ScopedLock<L> guard(lock_);
+        return ring_.free_space();
+    }
+    /// @copydoc SpscByteRing::empty
+    [[nodiscard]] bool empty() const noexcept { return size() == 0U; }
+
+    /// @copydoc SpscByteRing::write
+    std::size_t write(Span<const std::uint8_t> bytes) noexcept {
+        const ScopedLock<L> guard(lock_);
+        return ring_.write(bytes);
+    }
+    /**
+     * @brief Stores all of @p bytes or nothing, so records of concurrent producers stay whole.
+     * @return true when the bytes were stored.
+     */
+    bool write_all(Span<const std::uint8_t> bytes) noexcept {
+        const ScopedLock<L> guard(lock_);
+        if (ring_.free_space() < bytes.size()) {
+            return false;
+        }
+        return ring_.write(bytes) == bytes.size();
+    }
+    /// @copydoc SpscByteRing::peek
+    std::size_t peek(Span<std::uint8_t> out, std::size_t offset = 0U) const noexcept {
+        const ScopedLock<L> guard(lock_);
+        return ring_.peek(out, offset);
+    }
+    /// @copydoc SpscByteRing::consume
+    std::size_t consume(std::size_t count) noexcept {
+        const ScopedLock<L> guard(lock_);
+        return ring_.consume(count);
+    }
+    /// @copydoc SpscByteRing::read
+    std::size_t read(Span<std::uint8_t> out) noexcept {
+        const ScopedLock<L> guard(lock_);
+        return ring_.read(out);
+    }
+    /// @brief Drops all content.
+    void reset() noexcept {
+        const ScopedLock<L> guard(lock_);
+        ring_.reset();
+    }
+
+private:
+    mutable L lock_;
+    SpscByteRing ring_;
+};
+
+/// @cond INTERNAL
+namespace detail {
+template <std::size_t N> struct RingStorage {
+    std::array<std::uint8_t, N> bytes{};
+};
+} // namespace detail
+/// @endcond
+
+/**
+ * @brief SpscByteRing with built-in storage of @p N bytes.
+ * @tparam N Capacity in bytes.
+ */
+template <std::size_t N>
+class StaticSpscByteRing : private detail::RingStorage<N>, public SpscByteRing {
+public:
+    /// @brief Creates an empty ring.
+    StaticSpscByteRing() noexcept
+        : detail::RingStorage<N>(), SpscByteRing(Span<std::uint8_t>(this->bytes)) {}
+};
+
+} // namespace wireforge
+
+#endif // WIREFORGE_RING_BUFFER_HPP