C++ runtime (runtime/include/wireforge/)
Header-only C++17. No heap, no exceptions, no RTTI, no OS headers, no host-endianness or struct-layout assumptions.
Every fallible call returns wireforge::Status.
| Header | Content |
|---|---|
status.hpp |
Status, is_ok(), to_string() (see Status codes below) |
config.hpp |
build options: WIREFORGE_CONFIG_HEADER, WIREFORGE_NO_STD_MUTEX, WIREFORGE_DEFAULT_LOCK, WIREFORGE_CRC_TABLELESS |
version.hpp |
runtime version constants |
span.hpp |
Span<T> (dynamic extent, explicit constructors, subspan/first), make_span |
array_access.hpp |
array_at(): std::array element access without the exception path of at() |
static_vector.hpp |
StaticVector<T, N> (occurs storage: count + std::array), FixedString<N> (char arrays, always zero-terminated) |
lock.hpp |
lock policy contract is_lock_policy_v, NullLock, StdMutexLock, DefaultLock, ScopedLock, RelaxedCounter |
bit_utils.hpp |
BitOrder, masks, two's complement helpers, reflect, narrow_to, BitPacker / BitUnpacker |
byte_io.hpp |
Endian, store_unsigned/load_unsigned, ByteWriter, ByteReader (ints 1..8 bytes, f32/f64, bytes, bit groups, patching) |
ring_buffer.hpp |
SpscByteRing (lock-free), StaticSpscByteRing<N>, LockedByteRing<L> |
frame_layout.hpp |
FieldLocation shared by decoder and dispatcher |
payload_trim.hpp |
trimmed_size, ZeroExtended<N>: payloads sent without their trailing zero bytes |
frame_decoder.hpp |
FrameFormat, FrameDecoder<Checksum> (fixed, sync+length, length-prefixed; checksum verify; resync; counters) |
delegate.hpp |
Delegate<R(Args...)>: non-owning free/member/callable reference, no heap |
dispatcher.hpp |
RawMessage (payload and frame), Dispatcher<N, L> (header ids, fallback, frozen table), RawDispatcher<L> |
transport.hpp |
transport requirements is_transport_v, ITransport base, LoopbackTransport<N> |
link.hpp |
Link<Transport, Decoder, Dispatch, MaxFrame, RxCapacity, L>, Unframed, PollResult |
checksum.hpp |
checksum contract is_checksum_v, compute_checksum, Crc<...> (Rocksoft), Crc32, Crc16CcittFalse |
codec_support.hpp |
Encoding, Encoder/Decoder with a sticky first error (used by generated codecs) |
validation.hpp |
range, bit-width and count checks used by generated validate(); status_if(), size_if_ok() and first_error() keep generated code free of branches |
expr_support.hpp |
integer helpers used by generated size and count expressions |
Status codes
enum class Status : std::uint8_t; every fallible call returns one, nothing throws.
| Code | Meaning |
|---|---|
Ok |
Success |
BufferTooSmall |
The output buffer cannot hold the encoded data |
Truncated |
The input ended before the data was complete |
OutOfRange |
A value violates its min/max, enum or bit-width range |
CountExceedsMax |
An element count is above the capacity (or below the minimum) |
ConstMismatch |
A constant field differs from its declared value |
ChecksumMismatch |
A received checksum does not match the recomputed one |
UnknownMessageId |
A message id is not known on this interface |
InvalidLength |
A length field is inconsistent with the frame or buffer |
TrailingBytes |
The payload was not fully consumed |
InvalidState |
The API was misused (invalid argument or call sequence) |
NotForThisNode |
A valid frame that this unit does not receive; not an error (not counted in PollResult.errors) |
Byte and bit IO
- Integers are written byte by byte with shifts; widths 1..8 bytes; signed values as two's complement, decoded with explicit sign extension (no implementation-defined conversions). Floats go through their IEEE-754 bit pattern (D11).
- A failing call changes neither the position nor the output.
write_unsigned_atpatches an already written range (length fields, checksums);peek_unsigned_atinspects a header without consuming it. - Bit groups (D19):
BitPacker(total_bits, order)collects fields into one container integer,write_bitswrites it with the message endianness;read_bits+BitUnpackerreverse it. Endianness is a function argument, so a constant argument in generated code is resolved at compile time (all IO except floats isconstexpr). Encoder::write_bytes(Span<const std::uint8_t>)/Decoder::read_bytes(Span<std::uint8_t>)copy bytes onto/from the wire unchanged, no endian or bit-order transform: the only IO a user type's ownencode/decodeneeds.Encoder::write_width(value, width)/Decoder::read_width(value, width)write and read an unsigned value in a number of bytes smaller than its type (a 24-bit header field); a value that does not fit isOutOfRange.payload_trim.hpp:trimmed_size(payload)is the size of a payload without its trailing zero bytes (the first byte stays) andZeroExtended<N>gives a shorter payload back asNbytes padded with zeros, for interfaces withtrim_trailing_zeros. The C runtime haswf_trimmed_size()andwf_zero_extend()(wireforge/c/trim.h).
C runtime
runtime/include/wireforge/c/ is the runtime for C99 code (#include <wireforge/c/wireforge.h>, or the single headers):
header-only, static inline, no heap, no global state, no operating system. Its names are the ones of the C++ runtime
with a wf_ prefix, and the rules are the same: wf_status has the values and the order of wireforge::Status
(WF_OK, WF_BUFFER_TOO_SMALL, ...); wf_writer/wf_reader and wf_bit_packer/wf_bit_unpacker do the byte and
bit IO of byte_io.hpp and bit_utils.hpp; wf_encoder/wf_decoder keep the first error like Encoder/Decoder;
wf_check_* are the checks of validation.hpp, with the value passed as int64_t, uint64_t or double;
wf_crc() is the parametric CRC (bitwise, without a table); wf_expr_* are the helpers of generated expressions. A
checksum of a field is a function uint64_t f(const uint8_t *data, size_t length) over the covered bytes.
For interfaces there is wf_ring (a byte ring over caller storage), wf_frame_decoder (sync and length, length
prefixed and fixed framing, a checksum, resynchronisation, counters: frame_decoder.hpp) and wf_link (reads a
wf_transport into the ring, dispatches every frame, sends frames, counts bytes and frames: link.hpp). They have no
locks and no atomics (C99 has none): a link belongs to one thread at a time, and an interrupt handler that fills a
ring guards it with a critical section of the application. The C runtime
is tested by tests/c/runtime_test.c and tests/c/link_test.c (plain C99, no framework) and is compiled with the warning set of C code
(-Wall -Wextra -Wconversion -Wsign-conversion -Wshadow ... as errors; /W4 /WX for MSVC).
Thread safety
SpscByteRing: exactly one producer (write) and one consumer (peek,read,consume); indices run in[0, 2*capacity)so the whole storage is usable; release/acquire atomics publish data.reset()needs both sides idle.LockedByteRing<L>runs every operation under lock policyL;write_allkeeps records from concurrent producers whole.- Lock policies are template parameters. An RTOS port provides a default-constructible type with
lock() noexceptandunlock() noexceptand setsWIREFORGE_DEFAULT_LOCK(andWIREFORGE_NO_STD_MUTEXto drop<mutex>), D17.
Checksums (D4, D16)
Crc<Width, Poly, Init, RefIn, RefOut, XorOut, UseTable> covers widths 1..64 with a left-aligned 64-bit register; the
table mode shares one 2 KiB constexpr table per polynomial, the table-less mode loops over bits. Custom algorithms follow
the contract in checksum.hpp; generated code asserts is_checksum_v<Impl>.
Frame decoding
FrameDecoder<Checksum> reads from any ring with size/capacity/peek/consume. Incomplete frames stay in the ring, so
results do not depend on chunking. next() returns Ok (frame copied out), Truncated (need more bytes) or a rejection
(InvalidLength, ChecksumMismatch, BufferTooSmall) after which decoding continues. With resync a rejection skips one
byte and rescans; without it every buffered byte is dropped. Bytes that cannot start a frame (wrong sync) are skipped
silently and counted in discarded_bytes. Framing none needs no decoder (each transport read is one frame).
Dispatching
Handlers are registered (add, set_fallback, set_handler) before start(), under the lock policy. start() sorts and
freezes the table; afterwards dispatch()/dispatch_frame() take no lock and can run on several threads, and
registration returns InvalidState. Unknown ids go to the fallback handler or return UnknownMessageId.
Handlers receive a RawMessage with the payload and the whole frame. dispatch(id, payload) passes the payload as
both spans; dispatch_frame() slices the payload out of the frame. Both spans are valid only during the call.
Transport and link
A transport has send(Span<const uint8_t>) -> size_t and receive(Span<uint8_t>) -> size_t, both non-blocking. An
existing driver interface is connected by a small adapter class, either a plain type or derived from
ITransport. Link::poll() (one receiving thread) moves transport bytes into its ring, decodes and dispatches every
complete frame and returns counts plus the last error. Link::send(encode) runs the encoder on the preallocated tx
buffer under the tx lock and hands the frame to the transport; a transport that stops accepting bytes mid-frame gives
BufferTooSmall (the receiver resynchronises). With Unframed each transport read is one frame; a read longer than MaxFrame is rejected as InvalidLength and
whatever the transport still holds is dropped. The link reads into MaxFrame + 1 bytes, so a read of up to MaxFrame
bytes is always one frame: this holds for byte streams and for message transports (a message queue, a datagram socket,
a shared-memory channel), where each read returns one message. On a message transport an oversized message also drops
the messages queued behind it. In C, wf_link_init_rx() takes the receive frame buffer size separately (one byte more
than a frame for an unframed link, as the generated code does); wf_link_init() keeps both buffers the same size and
suits byte streams only.
Link::record sorts every received frame into one counter of LinkCounters by its status: rx_frames (Ok),
rx_rejected (the frame decoder refused it), rx_unknown_id, rx_not_for_node (NotForThisNode: a valid frame this
unit does not receive; it is neither a frame nor an error of the poll result) and rx_decode_errors (any other
status). reset_counters() (C: wf_link_reset_counters) sets every counter to zero.
Unhandled frames
A valid frame that reaches no received callback is handed to the generated handler's onUnhandled(const
UnhandledFrame&) (C: on_unhandled, wf_unhandled_frame) with its reason: UnknownMessageId, NotForThisNode or
DecodeError (the default raw callback could not decode it). The default only lets the link count the frame. Frames
the frame decoder rejects do not reach the hook, because no whole frame is at hand. count_if_ok (C:
wf_count_if_ok) is the branch-free helper generated code counts messages with.
Tests
tests/io_test.cpp, containers_test.cpp, ring_buffer_test.cpp (model fuzz, SPSC and MPMC stress under TSan),
frame_decoder_test.cpp (chunking equivalence, garbage, bad checksum/length, all framings), dispatcher_test.cpp (delegates, lookup, life cycle, concurrent dispatch and registration), link_test.cpp (loopback, garbage, full transport, ITransport adapter, unframed, sender/poller threads), checksum_test.cpp (CRC catalogue check values in both modes, custom Fletcher-16), lock_config_test.cpp
(built with WIREFORGE_NO_STD_MUTEX). Each suite checks for zero heap use with the allocation trap.
Portability
The runtime and the generated code are verified on every combination of word size and byte order, with an x86 and an
ARM target for little endian: quality/run_portability.sh cross compiles every test suite with the full warning set
and runs it under qemu user emulation (docs/DECISIONS.md D34). The wire bytes of the golden frames are compared on every
target.
| Little endian | Big endian | |
|---|---|---|
| 64-bit | x86-64 (host), aarch64 | s390x |
| 32-bit | i686, armhf (ARMv7) | powerpc |
The host is also built with plain char unsigned (cmake --preset unsigned-char, the ARM default) and with
AddressSanitizer and UBSan (which includes the alignment check). The tests run under qemu-user, not on hardware.
Conversions whose source width depends on the platform use narrow_to<T>(value) (bit_utils.hpp); counters accept any
unsigned amount. The runtime uses atomics of at most the size of a pointer, so targets without 64-bit atomics (32-bit
PowerPC, Cortex-M) need no libatomic.
Environments
The runtime and the generated code use only the C++17 standard library (an allow list of headers, checked by
quality/check_os_neutral.py) and test for no operating system. The CI checks it in these environments:
| Environment | Compiler | What is proved |
|---|---|---|
| Linux | GCC 13, Clang 18 | build, all tests, sanitizers |
| Windows | MSVC x64, MSVC x86, clang-cl | build with /W4 /WX, all tests |
| macOS (Apple silicon) | AppleClang | build, all tests |
| Android | NDK Clang, Bionic, libc++ (arm64-v8a, armeabi-v7a, x86_64) | the runtime tests and the tests of the generated code build and link with the full warning set; they are not run, because a Bionic binary does not run on a glibc host |
| FreeRTOS | arm-none-eabi-gcc, newlib-nano, Cortex-M4F | the generated self-tests of three examples and the runtime with several tasks run on QEMU mps2-an386 |
The generator, the command line and the server (Python) are tested on Linux, Windows and macOS.
On an RTOS the locking of the runtime is the lock of the kernel. tests/rtos/freertos_lock.hpp is a complete lock
policy on a FreeRTOS mutex; the harness makes it the default lock of the library with
-DWIREFORGE_NO_STD_MUTEX -DWIREFORGE_DEFAULT_LOCK=FreeRtosLock (see the table of config.hpp) and uses it for a ring
and a link between tasks. The library allocates nothing, so a kernel that only allocates for its own objects is enough.
quality/run_freertos.sh builds and runs the harness; quality/run_android.sh builds for the NDK.
Requirements
runtime/requirements.yaml holds the requirements of the runtime (RTR-<header>-NNN): the text, the header and the
symbols that implement it (checked against the header), the kinds of generated low-level requirements it realizes
and how it is verified (test, analysis or review). The file is written and reviewed by people; the first
version was drafted from the Doxygen comments and the tests, so it describes the code and does not yet stand apart from
it. Every unit test records the requirements it verifies as the first statement of its body
(::testing::Test::RecordProperty("requirements", "RTR-...")); only the tests of the allocation trap, which check the
test tooling, record none. Ids are never reused: a dropped requirement stays with retired: true.
Claims about several threads (the standard mutex lock, the single-producer ring, the locked ring, concurrent dispatch)
have verification: analysis: the evidence is for single-threaded use with the null lock, and the rest is the
integrator's to verify on the target. LoopbackTransport is a test helper and not part of that claim.
array_access.hpp, expr_support.hpp, frame_layout.hpp and config.hpp have no requirement yet.
wireforge docs --runtime -o <dir> [--results <build>] [--strict] writes the dossier (requirements, design, tests,
report, traceability, environment) of the runtime; quality/run_coverage.sh writes it to build/evidence-runtime
and CI publishes it. A project's documents name the runtime requirements that realize their low-level requirements
and the runtime version, and do not copy the dossier (docs/LIFECYCLE.md).
The coverage job of CI measures the runtime headers with the runtime tests and the tests of the generated code of the
examples (the differential harness, the fuzz targets replayed with golden inputs mutated at every byte and cut at
every length, and all read lengths of a link) and fails below the line coverage it states in ci.yml. Template
instances are counted one by one, as gcovr reports them, so a Link or FrameDecoder instance that is only compiled
lowers the figure. Gaps are closed with tests; there are no exclusions.