Skip to main content
Search Documentation & Spec
Type to search all 11 pages

OmniBuf
for C++20.

Single header-only C++20 runtime with zero external library dependencies. Map plain C++ structs at compile time, transcode dynamic payloads from Protobuf descriptor sets, or generate codecs and zero-copy views with Buf.

Header-Only Runtime
#include "omnibuf/omnibuf.hpp"

Three ways to use OmniBuf in C++20.

All three produce identical wire bytes with zero external library dependencies.

Compile-time StructTraits on plain C++ structs

omnibuf::StructTraits<T> binds member pointers to field IDs via constexpr tuples. Standard containers (std::optional, std::vector, std::map, std::unique_ptr) fold into direct template code with zero virtual dispatch.

StructTraits<T>
#include "omnibuf/omnibuf.hpp"

struct PeerEvent {
  uint32_t asn = 0;
  std::string router_id;
  bool active = false;
  int32_t rssi_dbm = 0;
};

template <>
struct omnibuf::StructTraits<PeerEvent> {
  static constexpr std::string_view type_name = "PeerEvent";
  static constexpr auto fields() {
    return std::make_tuple(
        omnibuf::field<1, &PeerEvent::asn>("asn"),
        omnibuf::field<2, &PeerEvent::router_id>("router_id"),
        omnibuf::field<3, &PeerEvent::active>("active"),
        omnibuf::field<4, &PeerEvent::rssi_dbm, omnibuf::WireOverride::Sint>("rssi_dbm"));
  }
};

auto pkt = omnibuf::marshal(PeerEvent{.asn = 64512, .router_id = "rtr-01", .active = true});

Buf descriptor sets and Protobuf wire transcoding

omnibuf::DescriptorPool reads binary FileDescriptorSet images emitted by buf build -o schemas.fds.pb. Gateways can ingest standard Protobuf payloads and re-emit OmniBuf packets dynamically with no linked libprotobuf runtime.

DescriptorPool & DynamicMessage
omnibuf::DescriptorPool pool;
pool.load_file_descriptor_set(fds_bytes);

const omnibuf::MessageDesc* desc = pool.find_message("omnibuf.bench.PeerUpdate");
auto msg = omnibuf::proto::from_binary(*desc, protobuf_wire_bytes);
auto pkt = omnibuf::marshal_dynamic(*desc, msg.value());

Generated headers with protoc-gen-omnibuf-cpp

Running buf generate with protoc-gen-omnibuf-cpp outputs.omnibuf.pb.hpp headers containing value structs, register-cursor encoders, and Opaque views. Nested string reads return std::string_view directly into std::span<const uint8_t> in ~122 ns.

buf.gen.yaml
version: v2
plugins:
  - local: ./build/protoc-gen-omnibuf-cpp
    out: build/gen
Build Plugin & Generate
$ cmake --build build --target protoc-gen-omnibuf-cpp
$ buf generate
Generated Header & Opaque View
#include "omnibuf/bench/peer.omnibuf.pb.hpp"

std::vector<uint8_t> pkt = update.marshal_omnibuf();

omnibuf::bench::OpaquePeerUpdate view(pkt);
std::string_view city = view.get_location().get_city_view();

view.set_sequence(9876543211ULL);
std::vector<uint8_t> updated = view.marshal();

C++20 benchmarks.

11-field PeerUpdate struct on Apple Clang 21 (-O3 -DNDEBUG, C++20). Shorter bars = Faster.

Full Message Encode Speed

Serializing PeerUpdate into a fresh std::vector<uint8_t> against in-tree LEB128 Protobuf and JSON codecs.

OmniBuf (Generated)
1.0x (base) (281 ns)
Protobuf (LEB128 Wire)
1.0x slower (284 ns)
OmniBuf (C++ Struct)
1.2x slower (340 ns)
JSON
2.4x slower (671 ns)
Full Message Decode Speed

Decoding into a fresh C++20 PeerUpdate struct and reading all 11 fields.

OmniBuf (Generated)
1.0x (base) (657 ns)
OmniBuf (C++ Struct)
1.1x slower (743 ns)
Protobuf (LEB128 Wire)
1.2x slower (789 ns)
JSON
2.6x slower (1,686 ns)
Read a Single Nested Field

Returning std::string_view into the packet via OpaquePeerUpdate vs full message decode.

OmniBuf (Generated)
1.0x (base) (121 ns)
Protobuf (LEB128 Wire)
4.9x slower (591 ns)
JSON
12.3x slower (1,485 ns)
Selective Single-Field Mutation

Checking a nested city string and splicing an updated sequence counter via OpaquePeerUpdate vs full decode and re-encode.

OmniBuf (Generated)
1.0x (base) (427 ns)
Protobuf (LEB128 Wire)
2.1x slower (885 ns)
JSON
5.1x slower (2,194 ns)
Large Embedded Message Encode

Serializing a 39 KiB packet whose >16 KiB nested sub-messages trigger 2B-to-4B header expansion vs Protobuf two-pass sizing.

Protobuf (LEB128 Wire)
1.3x faster (4,140 ns)
OmniBuf (Generated)
1.0x (base) (5,242 ns)
OmniBuf (C++ Struct)
1.0x slower (5,298 ns)
JSON
10.2x slower (53,706 ns)
Embedded Message Growth

Growing a nested string field past 16 KiB ahead of 32 trailing Neighbor entries via Opaque splicing vs full decode and re-encode.

OmniBuf (Generated)
1.0x (base) (3,581 ns)
Protobuf (LEB128 Wire)
1.6x slower (5,907 ns)
JSON
10.3x slower (37,049 ns)

Benchmark Environment

Hardware & Runtime
CPU: Apple M1 Pro (darwin/arm64)
Compiler: Apple Clang 21.0.0 (-O3, C++20)
Command: just bench

Compiled with Apple Clang 21.0.0 (-O3 -DNDEBUG -std=c++20) on an Apple M1 Pro Mac. Zero-dependency omnibuf-cpp headers are benchmarked against in-tree LEB128 Protobuf wire and JSON codecs operating on the exact same PeerUpdate struct, UTF-8 validation rules, and 11-field checksum sink.

Benchmark source lives in benchmarks/peer_bench.cpp, with recorded output in testdata/benchmarks.json.

C++20 questions.

Does the C++20 runtime depend on libprotobuf or Abseil?

include/omnibuf/ is a standalone C++20 header library built strictly on standard headers (<bit>, <span>, <string_view>, <charconv>). Even DescriptorPool parses buf build descriptor sets directly, so binaries link zero third-party C++ archives.

How are malformed packets reported?

Decoders return omnibuf::Status and omnibuf::Result<T> values, so wire errors never throw C++ exceptions. Truncated slices, reserved Prefix-Varint markers, invalid UTF-8, and nesting past MaxNestingDepth fail deterministically.

How does decode_blind_json handle unknown schemas?

Compact packets decode into deterministic JSON with field_1, field_2, ... keys inferred from each tag's 4-bit wire type. Enabling .self_describing = true writes Field #0 so decode_blind_json restores exact field names.

Example
auto pkt = omnibuf::marshal(event, {.self_describing = true});
auto json = omnibuf::decode_blind_json(pkt.value());

Language implementations.

v0.1 Draft Wire Format · GitHub Feedback →
Architecture, Tooling & Wire Specification