Wire codec deep-dive & throughput (L2/L3)

Where wire codec round-trip proves byte-identity, this example is the anatomy and cost companion. It builds a POINT TLV carrying two VALUE children with a CRC trailer, prints the encoded size and the raw header bytes, then times encode (model → bytes), tlv_node_t::over (bytes → a validated, borrowed node), and the full round-trip over 50,000 iterations (kIters, core/examples/wire_codec.cpp:constexpr int kIters = 50000;). See the frame codec module and the bit-level walkthrough for the byte layout.

Anatomy and timing

  • The header is small and fixed in shape — the example prints the leading bytes (type, opt, the fixed-width length). It also prints the encoded size, read from the buffer at run time (wire.size(), core/examples/wire_codec.cpp:std::printf("encoded POINT{VALUE,VALUE}+CRC:); that size is reported, not checked against a constant, so it is a property of the run and not a documented figure.

  • The read borrows rather than copies — each child’s payload is a std::span over the encoded buffer, and the example checks that the first child’s payload address lies inside wire.

  • Encode and decode are timed apart — encode materializes the byte vector and computes the CRC; the read validates the frame and builds nothing. The RESULT line reports the two separately plus the round-trip rate, so neither half is hidden inside the other.

  • The correctness properties are gated, the timings are not — the example returns non-zero on any failed check and runs under ctest as example_wire_codec (core/examples/CMakeLists.txt:add_test(NAME example_wire_codec COMMAND wire_codec)), unconditionally of the net plane.

Note

The absolute nanoseconds come from whatever build ran (CI builds the examples in a debug configuration); treat them as a shape, not a spec number. The canonical, release-build, CI-published codec figures — including the cross-core cpp/ts/rust comparison — live on the performance page.

Source

  1/*
  2 * SPDX-License-Identifier: Apache-2.0
  3 * SPDX-FileCopyrightText: Copyright 2026 avatarsd LLC
  4 */
  5
  6/**
  7 * @file
  8 * @brief Wire codec deep-dive — build a structured frame, inspect its bytes, and
  9 *        measure encode / decode / round-trip throughput.
 10 *
 11 * Where `wire_roundtrip` proves byte-identity, this example is the performance and
 12 * anatomy companion (`docs/modules/frame-codec.md`, `docs/modules/wire-format-bits.md`).
 13 * It builds a POINT TLV carrying two VALUE children with a CRC trailer, prints the
 14 * encoded size and the raw header bytes, then times three things over many
 15 * iterations: `encode` (model → bytes), `tlv_node_t::over` (bytes → a validated, borrowed
 16 * node whose children are walked in place), and the full round-trip. It also confirms the
 17 * read is zero-copy (payload spans borrow the encoded buffer) and that the node spans the
 18 * whole frame byte for byte.
 19 *
 20 * RESULT perf lines are informational (CI never flakes on timing); the self-checks
 21 * guard correctness. Runs under ctest as `example_wire_codec`.
 22 */
 23
 24#include <algorithm>
 25#include <chrono>
 26#include <cstddef>
 27#include <cstdint>
 28#include <cstdio>
 29#include <iterator>
 30#include <span>
 31#include <vector>
 32
 33#include "libtracer/tracer.hpp"
 34
 35namespace {
 36
 37using clock_t_ = std::chrono::steady_clock;
 38using tr::wire::opt_t;
 39using tr::wire::tlv_t;
 40using tr::wire::type_t;
 41
 42/** @brief A VALUE TLV borrowing @p bytes (little-endian payload; must outlive the TLV). */
 43tlv_t value_tlv(std::span<const std::byte> bytes) {
 44    tlv_t t;
 45    t.type = type_t::VALUE;
 46    t.payload = bytes;
 47    return t;
 48}
 49
 50/** @brief Record a failed expectation on @p ok and report it. */
 51void check(bool& ok, bool cond, const char* what) {
 52    if (!cond) {
 53        std::printf("  [FAIL] %s\n", what);
 54        ok = false;
 55    }
 56}
 57
 58}  // namespace
 59
 60int main() {
 61    // Two 4-byte little-endian VALUE payloads; their bytes outlive every TLV below.
 62    const std::vector<std::byte> a = {std::byte{0x17}, std::byte{0x00}, std::byte{0x00},
 63                                      std::byte{0x00}};
 64    const std::vector<std::byte> b = {std::byte{0x2A}, std::byte{0x00}, std::byte{0x00},
 65                                      std::byte{0x00}};
 66
 67    // A structured POINT (opt.pl = payload-is-children) with a CRC-32C trailer.
 68    tlv_t point;
 69    point.type = type_t::POINT;
 70    point.opt = opt_t{.pl = true, .cr = true};
 71    point.children = {value_tlv(a), value_tlv(b)};
 72
 73    const std::vector<std::byte> wire = tr::wire::encode(point);
 74    std::printf("encoded POINT{VALUE,VALUE}+CRC: %zu bytes\n", wire.size());
 75    std::printf("  header bytes:");
 76    for (std::size_t i = 0; i < wire.size() && i < 6; ++i)
 77        std::printf(" %02X", static_cast<unsigned>(std::to_integer<std::uint8_t>(wire[i])));
 78    std::printf("  (type, opt, length, …)\n");
 79
 80    bool ok = true;
 81    auto decoded = tr::wire::tlv_node_t::over(std::span<const std::byte>(wire));
 82    check(ok, decoded.has_value(), "decode succeeds (CRC verifies)");
 83    if (decoded) {
 84        const tr::wire::tlv_children_t kids = decoded->children();
 85        check(ok, decoded->type() == type_t::POINT, "root is a POINT");
 86        check(ok, std::ranges::distance(kids) == 2, "POINT has two VALUE children");
 87        const auto trailer = decoded->trailer();
 88        check(ok, trailer && trailer->crc.has_value(), "CRC trailer present and verified");
 89        if (!kids.empty()) {
 90            const auto c0 = (*kids.begin()).payload();
 91            check(ok, c0.data() >= wire.data() && c0.data() < wire.data() + wire.size(),
 92                  "decoded payload borrows the encoded buffer (zero copy)");
 93        }
 94        check(ok, std::ranges::equal(decoded->bytes(), wire), "the node spans the whole frame");
 95    }
 96
 97    // --- perf: encode / decode / round-trip over the same frame ---
 98    constexpr int kIters = 50000;
 99    std::size_t sink = 0;
100
101    auto t0 = clock_t_::now();
102    for (int i = 0; i < kIters; ++i) sink += tr::wire::encode(point).size();
103    auto t1 = clock_t_::now();
104    for (int i = 0; i < kIters; ++i) {
105        auto d = tr::wire::tlv_node_t::over(std::span<const std::byte>(wire));
106        sink += d ? static_cast<std::size_t>(std::ranges::distance(d->children())) : 0;
107    }
108    auto t2 = clock_t_::now();
109
110    const double enc_ns = std::chrono::duration<double, std::nano>(t1 - t0).count() / kIters;
111    const double dec_ns = std::chrono::duration<double, std::nano>(t2 - t1).count() / kIters;
112    const double rt_Mps = 1.0 / ((enc_ns + dec_ns) * 1e-9) / 1e6;
113    std::printf(
114        "RESULT wire_codec bytes=%zu encode_ns=%.0f decode_ns=%.0f "
115        "roundtrip_Mps=%.2f (sink=%zu)\n",
116        wire.size(), enc_ns, dec_ns, rt_Mps, sink);
117
118    std::printf("%s\n", ok ? "wire codec OK" : "wire codec FAILED");
119    return ok ? 0 : 1;
120}

See also: frame-codec module · wire codec round-trip · bit-level wire walkthrough.