6e89cf99
docs: C acceleration architecture note (pf6 deliverable)
Records the architecture chosen for the C-accelerated encode/decode
path, based on the bench/c_accel/ spike results (commit d4dbd2f).
Closes the umbrella decision task pf6; the breakdown of follow-on
implementation work lives in Beads under bd-ra6 and its twelve
sub-issues (3a–3l).
Key decisions captured:
- Ship S3 (generic C runtime, descriptor-walking, one C call per
message) as bd-ra6. Within ±15% of hand-written codegen in the
spike, and beats it at scale on encode.
- Defer S4 (codegen-emitted C, bd-c0i) with explicit revival
criteria — ≤15% headroom doesn't earn codegen + maintenance +
distribution complexity.
- Drop S2 (per-primitive FFI) — structurally worse than pure Lua;
the FFI boundary cost (~60-75 ns/call) is the same order of
magnitude as the pure-Lua varint helpers it would replace.
User-facing contract:
- PB_ENABLE_C=1 env var is the only activation switch, default
off. require('pb') returns the same Lua surface in both modes;
zero behavior change for existing installs.
- No Lua-level toggle. Single knob, evaluated once at module load.
Parity verification:
- No separate Lua-vs-C diff harness. Existing test suites
(luatest, conformance, interop fixtures) run twice in CI — once
with PB_ENABLE_C unset and once with PB_ENABLE_C=1. Parity is
guaranteed by transitivity through the reference outputs.
beads-tarantool-protobuf-pf6
Eugene Blikh <bigbes@gmail.com> — 2026-05-18 20:22:56 UTC
Commit 6e89cf9978343e9c7ead0bad1afcda886b18a3b6 —
view raw patch
Parent(s):
a51ae324
| File | Status | + | − |
|---|---|---|---|
docs/c-accel.md
|
A | +241 |