wireforge 0.1.0__py3-none-any.whl

wireforge/_data/runtime/include/wireforge/codec_support.hpp

@@ -0,0 +1,412 @@
+/**
+ * @file codec_support.hpp
+ * @brief Encoder and Decoder used by generated serialize/deserialize functions.
+ *
+ * Both keep the first error ("sticky" status): after a failure every further operation does
+ * nothing, so generated code is a straight sequence of calls followed by `status()`.
+ */
+#ifndef WIREFORGE_CODEC_SUPPORT_HPP
+#define WIREFORGE_CODEC_SUPPORT_HPP
+
+#include "wireforge/bit_utils.hpp"
+#include "wireforge/byte_io.hpp"
+#include "wireforge/checksum.hpp"
+#include "wireforge/span.hpp"
+#include "wireforge/static_vector.hpp"
+#include "wireforge/status.hpp"
+
+#include <cstddef>
+#include <cstdint>
+#include <limits>
+#include <type_traits>
+
+namespace wireforge {
+
+/// @brief Encoding settings of one message on one interface.
+struct Encoding {
+    Endian endian = Endian::Big;             ///< Byte order of multi-byte values.
+    BitOrder bit_order = BitOrder::MsbFirst; ///< Placement of fields in bit groups.
+    bool check_encode = true;                ///< Check min/max and enum values when encoding.
+    bool check_decode = true;                ///< Check min/max and enum values when decoding.
+    bool allow_trailing_bytes = false;       ///< Accept payload bytes after the last field.
+};
+
+/// @cond INTERNAL
+namespace detail {
+
+template <typename T> struct WireInt {
+    using type = T;
+};
+template <> struct WireInt<bool> {
+    using type = std::uint8_t;
+};
+template <> struct WireInt<char> {
+    using type = std::uint8_t;
+};
+
+// Integer type that carries the wire value of T (enums: their underlying type).
+template <typename T>
+using wire_int_t =
+    typename WireInt<typename std::conditional_t<std::is_enum_v<T>, std::underlying_type<T>,
+                                                 std::enable_if<true, T>>::type>::type;
+
+// Converts without a cast when the types already match (keeps -Wuseless-cast quiet).
+template <typename To, typename From> [[nodiscard]] constexpr To convert(From value) noexcept {
+    if constexpr (std::is_same_v<To, From>) {
+        return value;
+    } else {
+        return static_cast<To>(value);
+    }
+}
+
+} // namespace detail
+/// @endcond
+
+/**
+ * @brief Sequential encoder with a sticky status.
+ */
+class Encoder {
+public:
+    /// @brief Encodes into @p buffer with @p encoding.
+    Encoder(Span<std::uint8_t> buffer, const Encoding& encoding) noexcept
+        : writer_(buffer), encoding_(encoding) {}
+
+    /// @brief Settings in use.
+    [[nodiscard]] const Encoding& encoding() const noexcept { return encoding_; }
+    /// @brief The first error, or Status::Ok.
+    [[nodiscard]] Status status() const noexcept { return status_; }
+    /// @brief Bytes written so far.
+    [[nodiscard]] std::size_t position() const noexcept { return writer_.position(); }
+
+    /// @brief Records @p status unless an earlier error is already recorded.
+    void check(Status status) noexcept {
+        if (status_ == Status::Ok) {
+            status_ = status;
+        }
+    }
+
+    /// @brief Records @p status when encode-side value checks are enabled.
+    void check_value(Status status) noexcept {
+        if (encoding_.check_encode) {
+            check(status);
+        }
+    }
+
+    /**
+     * @brief Writes @p value as wire type T (integers, bool, char, enums, float, double).
+     */
+    template <typename T> void write(T value) noexcept {
+        if (status_ != Status::Ok) {
+            return;
+        }
+        if constexpr (std::is_same_v<T, float>) {
+            check(writer_.write_f32(value, encoding_.endian));
+        } else if constexpr (std::is_same_v<T, double>) {
+            check(writer_.write_f64(value, encoding_.endian));
+        } else {
+            using Wire = detail::wire_int_t<T>;
+            const auto wire = detail::convert<Wire>(value);
+            if constexpr (std::is_signed_v<Wire>) {
+                check(writer_.write_signed(wire, sizeof(Wire), encoding_.endian));
+            } else {
+                check(writer_.write_unsigned(wire, sizeof(Wire), encoding_.endian));
+            }
+        }
+    }
+
+    /**
+     * @brief Writes an element count as wire type W (bool counts must be 0 or 1).
+     */
+    template <typename W> void write_count(std::size_t count) noexcept {
+        const std::uint64_t limit = std::is_same_v<W, bool>
+                                        ? 1U
+                                        : static_cast<std::uint64_t>(std::numeric_limits<W>::max());
+        if (count > limit) {
+            check(Status::OutOfRange);
+            return;
+        }
+        if constexpr (std::is_same_v<W, bool>) {
+            write(count == 1U);
+        } else {
+            write(detail::convert<W>(count));
+        }
+    }
+
+    /// @brief Writes the first @p count characters of @p text and pads with zeros to @p width.
+    template <std::size_t N>
+    void write_text(const FixedString<N>& text, std::size_t width) noexcept {
+        for (std::size_t index = 0U; index < width; ++index) {
+            write(index < text.size() ? text[index] : '\0');
+        }
+    }
+
+    /**
+     * @brief Adds a field to a bit group (bool, enum, signed or unsigned integer).
+     */
+    template <typename T> void put(BitPacker& group, T value, unsigned bits) noexcept {
+        using Wire = detail::wire_int_t<T>;
+        const auto wire = detail::convert<Wire>(value);
+        if constexpr (std::is_signed_v<Wire>) {
+            check(group.put_signed(wire, bits));
+        } else {
+            check(group.put(wire, bits));
+        }
+    }
+
+    /// @brief Writes a complete bit group.
+    void write_bits(const BitPacker& group) noexcept {
+        if (status_ == Status::Ok) {
+            check(writer_.write_bits(group, encoding_.endian));
+        }
+    }
+
+    /**
+     * @brief Copies @p bytes onto the wire unchanged (no endian or bit-order transform).
+     *
+     * For a user type's own encode(): the type owns its wire representation entirely. Sets
+     * Status::BufferTooSmall (checked by status()) when they do not fit.
+     */
+    void write_bytes(Span<const std::uint8_t> bytes) noexcept {
+        if (status_ == Status::Ok) {
+            check(writer_.write_bytes(bytes));
+        }
+    }
+
+    /**
+     * @brief Writes the checksum C of the bytes written in [@p begin, @p end).
+     */
+    template <typename C> void write_checksum(std::size_t begin, std::size_t end) noexcept {
+        if (status_ != Status::Ok) {
+            return;
+        }
+        const Span<const std::uint8_t> covered = writer_.written().subspan(begin, end - begin);
+        check(writer_.write_unsigned(compute_checksum<C>(covered), C::kSize, encoding_.endian));
+    }
+
+private:
+    ByteWriter writer_;
+    Encoding encoding_;
+    Status status_ = Status::Ok;
+};
+
+/**
+ * @brief Sequential decoder with a sticky status.
+ */
+class Decoder {
+public:
+    /// @brief Decodes @p input with @p encoding.
+    Decoder(Span<const std::uint8_t> input, const Encoding& encoding) noexcept
+        : input_(input), reader_(input), encoding_(encoding) {}
+
+    /// @brief Settings in use.
+    [[nodiscard]] const Encoding& encoding() const noexcept { return encoding_; }
+    /// @brief The first error, or Status::Ok.
+    [[nodiscard]] Status status() const noexcept { return status_; }
+    /// @brief Bytes consumed so far.
+    [[nodiscard]] std::size_t position() const noexcept { return reader_.position(); }
+    /// @brief Bytes not consumed yet.
+    [[nodiscard]] std::size_t remaining() const noexcept { return reader_.remaining(); }
+
+    /// @brief Records @p status unless an earlier error is already recorded.
+    void check(Status status) noexcept {
+        if (status_ == Status::Ok) {
+            status_ = status;
+        }
+    }
+
+    /// @brief Records @p status when decode-side value checks are enabled.
+    void check_value(Status status) noexcept {
+        if (encoding_.check_decode) {
+            check(status);
+        }
+    }
+
+    /**
+     * @brief Reads a value of wire type T into @p out (a bool must be 0 or 1).
+     */
+    template <typename T> void read(T& out) noexcept {
+        if (status_ != Status::Ok) {
+            return;
+        }
+        if constexpr (std::is_same_v<T, float>) {
+            check(reader_.read_f32(out, encoding_.endian));
+        } else if constexpr (std::is_same_v<T, double>) {
+            check(reader_.read_f64(out, encoding_.endian));
+        } else {
+            using Wire = detail::wire_int_t<T>;
+            Wire wire{};
+            read_int(wire);
+            assign(out, wire);
+        }
+    }
+
+    /// @brief Reads an element count stored as wire type W.
+    template <typename W> [[nodiscard]] std::size_t read_count() noexcept {
+        W value{};
+        read(value);
+        return detail::convert<std::size_t>(value);
+    }
+
+    /// @brief Reads a value of wire type T and fails with ConstMismatch unless it is @p expected.
+    template <typename T> void expect(T expected) noexcept {
+        T value{};
+        read(value);
+        if (status_ == Status::Ok && !(value == expected)) {
+            check(Status::ConstMismatch);
+        }
+    }
+
+    /// @brief Skips @p count bytes.
+    void skip(std::size_t count) noexcept {
+        if (status_ == Status::Ok) {
+            check(reader_.skip(count));
+        }
+    }
+
+    /**
+     * @brief Reads @p out.size() bytes unchanged (no endian or bit-order transform).
+     *
+     * For a user type's own decode(): the type owns its wire representation entirely. Sets
+     * Status::Truncated (checked by status()) when fewer bytes remain.
+     */
+    void read_bytes(Span<std::uint8_t> out) noexcept {
+        if (status_ == Status::Ok) {
+            check(reader_.read_bytes(out));
+        }
+    }
+
+    /**
+     * @brief Reads @p width characters; a fixed-width text drops trailing zeros.
+     */
+    template <std::size_t N>
+    void read_text(FixedString<N>& text, std::size_t width, bool fixed) noexcept {
+        if (width > N) {
+            check(Status::CountExceedsMax);
+        }
+        if (status_ != Status::Ok) {
+            return;
+        }
+        static_cast<void>(text.resize(width));
+        std::size_t length = 0U;
+        for (std::size_t index = 0U; index < width; ++index) {
+            read(text[index]);
+            length = text[index] != '\0' || !fixed ? index + 1U : length;
+        }
+        static_cast<void>(text.resize(length));
+    }
+
+    /// @brief Sets the size of @p container to @p count (CountExceedsMax outside [low, capacity]).
+    template <typename Container>
+    void resize(Container& container, std::size_t count, std::size_t low) noexcept {
+        if (count < low || count > Container::capacity()) {
+            check(Status::CountExceedsMax);
+        }
+        if (status_ == Status::Ok) {
+            static_cast<void>(container.resize(count));
+        }
+    }
+
+    /**
+     * @brief Number of elements of @p element_size bytes in the rest of the input.
+     * @return 0 with InvalidLength when the rest is not a multiple of the element size.
+     */
+    [[nodiscard]] std::size_t fill_count(std::size_t element_size) noexcept {
+        if (element_size == 0U || remaining() % element_size != 0U) {
+            check(Status::InvalidLength);
+            return 0U;
+        }
+        return remaining() / element_size;
+    }
+
+    /// @brief Reads a bit group of @p total_bits bits.
+    [[nodiscard]] BitUnpacker read_bits(unsigned total_bits) noexcept {
+        BitUnpacker group(0U, total_bits, encoding_.bit_order);
+        if (status_ == Status::Ok) {
+            check(reader_.read_bits(group, total_bits, encoding_.bit_order, encoding_.endian));
+        }
+        return group;
+    }
+
+    /// @brief Extracts the next field of a bit group into @p out.
+    template <typename T> void get(BitUnpacker& group, T& out, unsigned bits) noexcept {
+        using Wire = detail::wire_int_t<T>;
+        if constexpr (std::is_signed_v<Wire>) {
+            std::int64_t value = 0;
+            check(group.get_signed(value, bits));
+            assign(out, detail::convert<Wire>(value));
+        } else {
+            std::uint64_t value = 0U;
+            check(group.get(value, bits));
+            assign(out, detail::convert<Wire>(value));
+        }
+    }
+
+    /// @brief Extracts a constant field of a bit group (ConstMismatch when it differs).
+    template <typename T> void expect_bits(BitUnpacker& group, T expected, unsigned bits) noexcept {
+        T value{};
+        get(group, value, bits);
+        if (status_ == Status::Ok && !(value == expected)) {
+            check(Status::ConstMismatch);
+        }
+    }
+
+    /// @brief Skips a reserved field of a bit group.
+    void skip_bits(BitUnpacker& group, unsigned bits) noexcept {
+        std::uint64_t ignored = 0U;
+        check(group.get(ignored, bits));
+    }
+
+    /**
+     * @brief Reads a checksum C and compares it with the checksum of the input [@p begin, @p end).
+     */
+    template <typename C> void verify_checksum(std::size_t begin, std::size_t end) noexcept {
+        std::uint64_t received = 0U;
+        if (status_ == Status::Ok) {
+            check(reader_.read_unsigned(received, C::kSize, encoding_.endian));
+        }
+        if (status_ == Status::Ok &&
+            compute_checksum<C>(input_.subspan(begin, end - begin)) != received) {
+            check(Status::ChecksumMismatch);
+        }
+    }
+
+    /// @brief Fails with TrailingBytes when input is left and trailing bytes are not allowed.
+    void finish() noexcept {
+        if (remaining() > 0U && !encoding_.allow_trailing_bytes) {
+            check(Status::TrailingBytes);
+        }
+    }
+
+private:
+    template <typename Wire> void read_int(Wire& wire) noexcept {
+        if constexpr (std::is_signed_v<Wire>) {
+            std::int64_t value = 0;
+            check(reader_.read_signed(value, sizeof(Wire), encoding_.endian));
+            wire = detail::convert<Wire>(value);
+        } else {
+            std::uint64_t value = 0U;
+            check(reader_.read_unsigned(value, sizeof(Wire), encoding_.endian));
+            wire = detail::convert<Wire>(value);
+        }
+    }
+
+    template <typename T, typename Wire> void assign(T& out, Wire wire) noexcept {
+        if constexpr (std::is_same_v<T, bool>) {
+            if (wire > 1U) {
+                check(Status::OutOfRange);
+            }
+            out = wire == 1U;
+        } else {
+            out = detail::convert<T>(wire);
+        }
+    }
+
+    Span<const std::uint8_t> input_;
+    ByteReader reader_;
+    Encoding encoding_;
+    Status status_ = Status::Ok;
+};
+
+} // namespace wireforge
+
+#endif // WIREFORGE_CODEC_SUPPORT_HPP

wireforge/_data/runtime/include/wireforge/config.hpp

@@ -0,0 +1,41 @@
+/**
+ * @file config.hpp
+ * @brief Build-time configuration of the WireForge runtime.
+ *
+ * Every option is a macro that can be set on the compiler command line or in a user header named by
+ * `WIREFORGE_CONFIG_HEADER`, which is included first.
+ *
+ * | Macro                     | Effect                                                         |
+ * |---------------------------|----------------------------------------------------------------|
+ * | `WIREFORGE_CONFIG_HEADER` | Header (with quotes or angle brackets) included before anything |
+ * | `WIREFORGE_NO_STD_MUTEX`  | Do not include `<mutex>`; wireforge::StdMutexLock is unavailable |
+ * | `WIREFORGE_DEFAULT_LOCK`  | Lock policy type used as wireforge::DefaultLock                 |
+ * | `WIREFORGE_CRC_TABLELESS` | Predefined CRC aliases use the bitwise mode instead of a table  |
+ */
+#ifndef WIREFORGE_CONFIG_HPP
+#define WIREFORGE_CONFIG_HPP
+
+#if defined(WIREFORGE_CONFIG_HEADER)
+#include WIREFORGE_CONFIG_HEADER
+#endif
+
+/// @brief Compile-time view of the configuration macros.
+namespace wireforge::config {
+
+#if defined(WIREFORGE_NO_STD_MUTEX)
+inline constexpr bool kHasStdMutex = false;
+#else
+/// @brief true unless `WIREFORGE_NO_STD_MUTEX` is defined.
+inline constexpr bool kHasStdMutex = true;
+#endif
+
+#if defined(WIREFORGE_CRC_TABLELESS)
+inline constexpr bool kCrcUseTable = false;
+#else
+/// @brief Default table mode of wireforge::Crc; false when `WIREFORGE_CRC_TABLELESS` is defined.
+inline constexpr bool kCrcUseTable = true;
+#endif
+
+} // namespace wireforge::config
+
+#endif // WIREFORGE_CONFIG_HPP

wireforge/_data/runtime/include/wireforge/delegate.hpp

@@ -0,0 +1,101 @@
+/**
+ * @file delegate.hpp
+ * @brief Small non-owning callable wrapper that never allocates.
+ */
+#ifndef WIREFORGE_DELEGATE_HPP
+#define WIREFORGE_DELEGATE_HPP
+
+#include <type_traits>
+#include <utility>
+
+namespace wireforge {
+
+/// @brief Declared only; see the specialization for function types.
+template <typename Signature> class Delegate;
+
+/**
+ * @brief Non-owning reference to a free function, a member function bound to an object, or a
+ *        callable object.
+ *
+ * The delegate stores two pointers and never allocates. Objects bound with bind() or
+ * from_callable() are referenced, not copied: they must outlive the delegate.
+ * @code
+ * Delegate<int(int)> d1 = Delegate<int(int)>::from_function(&twice);
+ * Delegate<int(int)> d2 = Delegate<int(int)>::bind<&Counter::add>(counter);
+ * auto lambda = [](int value) { return value + 1; };
+ * Delegate<int(int)> d3 = Delegate<int(int)>::from_callable(lambda);
+ * @endcode
+ * @tparam R Return type.
+ * @tparam Args Parameter types.
+ */
+template <typename R, typename... Args> class Delegate<R(Args...)> {
+public:
+    /// @brief Free function type accepted by from_function().
+    using Function = R (*)(Args...);
+
+    /// @brief Creates an empty delegate; calling it is not allowed.
+    constexpr Delegate() noexcept = default;
+
+    /// @brief Refers to the free function @p function.
+    [[nodiscard]] static constexpr Delegate from_function(Function function) noexcept {
+        Delegate delegate;
+        delegate.function_ = function;
+        delegate.stub_ = function == nullptr ? nullptr : &call_function;
+        return delegate;
+    }
+
+    /**
+     * @brief Refers to member function @p Method called on @p object.
+     * @tparam Method Pointer to a member function of T with this delegate's signature.
+     */
+    template <auto Method, typename T>
+    [[nodiscard]] static constexpr Delegate bind(T& object) noexcept {
+        Delegate delegate;
+        delegate.object_ = &object;
+        delegate.stub_ = &call_member<T, Method>;
+        return delegate;
+    }
+
+    /// @brief Refers to the callable object @p callable (for example a lambda); it must be an
+    /// lvalue.
+    template <typename F>
+    [[nodiscard]] static constexpr Delegate from_callable(F& callable) noexcept {
+        static_assert(!std::is_const_v<F>, "bind a non-const callable object");
+        Delegate delegate;
+        delegate.object_ = &callable;
+        delegate.stub_ = &call_callable<F>;
+        return delegate;
+    }
+
+    /// @brief true when the delegate refers to something callable.
+    [[nodiscard]] constexpr explicit operator bool() const noexcept { return stub_ != nullptr; }
+
+    /**
+     * @brief Calls the referenced function.
+     * @pre The delegate is not empty.
+     */
+    R operator()(Args... args) const { return stub_(*this, std::forward<Args>(args)...); }
+
+private:
+    using Stub = R (*)(const Delegate&, Args...);
+
+    static R call_function(const Delegate& self, Args... args) {
+        return self.function_(std::forward<Args>(args)...);
+    }
+
+    template <typename T, auto Method> static R call_member(const Delegate& self, Args... args) {
+        return (static_cast<T*>(self.object_)->*Method)(std::forward<Args>(args)...);
+    }
+
+    template <typename F> static R call_callable(const Delegate& self, Args... args) {
+        return (*static_cast<F*>(self.object_))(std::forward<Args>(args)...);
+    }
+
+    void* object_ = nullptr;
+    Function function_ = nullptr;
+    Stub stub_ = nullptr;
+};
+
+} // namespace wireforge
+
+#endif // WIREFORGE_DELEGATE_HPP