Introduction

What to use

One line per module: what it is for, and the call you make.

Kubernetes, if you deploy there. Tuning a node and pod for HFT: Kubernetes HFT tuning — start there.

Start with ergo-sbe. Add another crate only for a need you have: ergon-io for exchange I/O, ergon-tune to check a latency host’s settings. Which clock to read for timestamps and durations: Clocks.

ergo-sbe generates Rust codecs with no heap allocation on the encode and decode hot paths (allocation_count_test) from Simple Binary Encoding schemas. Wire layout matches official SBE for the published profile. Tail order is a type error, not a runtime surprise.

Quick start

[build-dependencies]
ergo-sbe = "0.1"

[dependencies]
ergo-sbe = "0.1"   # only for sbe_mod! / include_sbe!

#![allow(unused)]
fn main() {
let mut buf = [0u8; HeartbeatEncoder::compute_length_with_header()];
// Buffer is exact size from const compute_length_with_header — no bounds check needed.
let len = HeartbeatEncoder::try_wrap_and_apply_header(&mut buf, 0)?
    .fixed(&HeartbeatFixedFields { sequence: 7, timestamp: 0 })
    .encoded_length_with_header();
let dec = HeartbeatDecoder::try_from(&buf[..len])?;
assert_eq!(dec.sequence(), 7);
}

(From book/examples/heartbeat-encode.rs — compiled against the feature-tour codec.)

Set up → · Feature tour → · Coming from sbe-tool →

0.x experimental. Pin versions. Exit criteria: Road to 1.0.

It is not a line-for-line port of sbe-tool. The generated API is meant to be easier under Rust’s borrow checker, safer at untrusted boundaries, and still official-SBE on the wire. Nested groups use scoped closures so you do not hand encoder ownership back with .parent():

#![allow(unused)]
fn main() {
pub fn encode_sample_car(buf: &mut [u8]) -> Result<usize, sbe_rt::EncodeError> {
    let mut extras = OptionalExtras::default();
    extras.cruise_control(true).sports_pack(true);

    // Buffer pre-sized from EncodedLength; try_* still validates extent.
    let len = CarEncoder::try_wrap_and_apply_header(buf, 0)
        .unwrap()
        .fixed(&CarFixedFields {
            serial_number: 1234,
            model_year: 2013,
            available: true.into(),
            code: Model::A,
            some_numbers: [10, 20, 30, 40],
            vehicle_code: [b'A', b'B', b'C', b'D', b'E', b'F'],
            extras,
            engine: Engine::new(
                2000,
                4,
                [b'1', b'2', b'3'],
                0i8,
                false.into(),
                Booster::new(BoostType::TURBO, 210),
            ),
        })
        .fuel_figures(2, |g| {
            g.add(|mut e| {
                e.speed(30).mpg(35.9);
                e.usage_description_as_str("Urban")
            })?;
            g.add(|mut e| {
                e.speed(60).mpg(25.0);
                e.usage_description_as_str("Highway")
            })?;
            Ok(())
        })?
        .performance_figures(1, |g| {
            g.add(|mut e| {
                e.octane_rating(95);
                e.acceleration(2, |a| {
                    a.add(|x| {
                        x.mph(30).seconds(4.0);
                        Ok(())
                    })?;
                    a.add(|x| {
                        x.mph(60).seconds(7.5);
                        Ok(())
                    })
                })
            })?;
            Ok(())
        })?
        .manufacturer_as_str("Honda")?
        .model_as_str("Civic VTi")?
        .activation_code_as_str("abcdef")?
        .encoded_length_with_header();

    Ok(len)
}
}

(Compiled and run in CI.)

Wire parity is tested by the dual-encode suite (sbe_tool_wire_parity_test, sbe_tool_multi_schema_wire_parity_test). The benchmarks also assert byte parity before timing: Benchmarks.

Deployment

How to set up hosts and Kubernetes for these crates on AWS and Azure, x86 and Graviton: Deployment.

Rust 1.99+. Clone setup and checks: repository README.

Getting Started

Add ergo-sbe as a build dependency, generate a module, include it, encode and decode.

• Depend on the Generator
• Generate in build.rs
• Include Generated Code
• Encode and Decode
• Method Chaining
• Multi-Schema Patterns
• Coming from sbe-tool
• Error Diagnostics

Depend on the Generator

Minimal product path — codegen only; generated codecs embed their own sbe_rt and do not link ergo-sbe into the application. Schema parse errors render a source snippet (line + span) by default:

[build-dependencies]
ergo-sbe = "0.1"
# no [dependencies] ergo-sbe

Convenience path — also pull ergo-sbe as a normal dependency when you use sbe_mod! / include_sbe! (macros expand in the app crate):

[build-dependencies]
ergo-sbe = "0.1"

[dependencies]
ergo-sbe = "0.1"   # only needed for sbe_mod! / include_sbe!

See Samples for monorepo crates that use each pattern.

Generate in build.rs

Two APIs — pick whichever fits your project:

generate_to_dir writes generated codecs to a directory you control (prefer src/generated/ for IDE go-to-definition). The feature-tour sample uses this pattern:

#![allow(unused)]
fn main() {
    let generated_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src/generated");
    let config = ergo_sbe::GenerationConfig::new("feature_tour")
        .with_domain_objects(ergo_sbe::DomainVarData::Strings)
        .with_domain_type(
            ergo_sbe::ConversionSelector::named_type("BooleanType"),
            "bool",
        )
        .with_domain_type(
            ergo_sbe::ConversionSelector::semantic_type("UTCTimestamp"),
            "chrono::DateTime<chrono::Utc>",
        )
        .with_conversion(ergo_sbe::ConversionSelector::named_type("Decimal"))
        // Same shape as Decimal, but the app supplies the impl itself — see
        // demo_domain_type_manual_impl in src/lib.rs.
        .with_manual_domain_type(
            ergo_sbe::ConversionSelector::named_type("ManualDecimal"),
            "rust_decimal::Decimal",
        );

    ergo_sbe::generate_to_dir("schemas/feature-tour.xml", config, &generated_dir)?;
}

generate_to_out_dir writes to Cargo’s $OUT_DIR and emits cargo::rerun-if-changed automatically. Use with include!(concat!(env!("OUT_DIR"), …)) — simpler, but rust-analyzer usually cannot jump into generated code.

Schema from a string / include_str!: generate_str_to_out_dir.

Need multi-schema or custom output paths? Use the lower-level parse_file + Generator API (same steps the helper runs). For shared types across schemas, see Multi-Schema Patterns below.

Include Generated Code

Prefer build-dep only for product crates (no runtime ergo-sbe link). Generated codecs embed sbe_rt; plain include! is enough:

#[path = "generated/feature_tour.rs"]
pub mod feature_tour;
pub use feature_tour::*;

(From sbe-feature-tour/src/lib.rs — the #[path] pattern used by every sample crate. The feature-tour’s cargo build verifies this compiles.)

or via include!:

mod messages {
    include!(concat!(env!("OUT_DIR"), "/messages.rs"));
}
use messages::*;

Optional convenience — sbe_mod! needs ergo-sbe as a normal dependency (macro expansion only; not required for encode/decode):

// Cargo.toml: [dependencies] ergo-sbe = "0.1"
ergo_sbe::sbe_mod!(messages);
use messages::*;
// Or only the include: ergo_sbe::include_sbe!("messages");

See Samples for which crates use which pattern.

Encode and Decode

Two styles — pick whichever fits:

fixed() struct (fill every field at once — compile error if a field is missing):

#![allow(unused)]
fn main() {
pub fn demo_fixed_heartbeat() -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    // Const length → stack array (no heap).
    let mut buf = [0u8; HeartbeatEncoder::compute_length_with_header()];
    let nanos: i64 = 1_720_000_000_000_000_000;
    // Buffer pre-sized via const compute_length_with_header; try_* still validates extent.
    let written = HeartbeatEncoder::try_wrap_and_apply_header(&mut buf, 0)
        .unwrap()
        .fixed(&HeartbeatFixedFields {
            sequence: 7,
            timestamp: nanos as u64,
        })
        .encoded_length_with_header();

    let dec = HeartbeatDecoder::try_decode(&buf[..written], 0)?;
    assert_eq!(dec.sequence(), 7);
    let decoded_ts: DateTime<Utc> = dec.timestamp()?;
    assert_eq!(decoded_ts.timestamp_nanos_opt(), Some(nanos));
    Ok(buf[..written].to_vec())
}
}

(This code comes from the sbe-feature-tour sample crate.)

{Msg}FixedFields has no Default. Every required scalar must appear in the struct literal (optional fields use Option only when schema presence="optional"). That is intentional: zero-filling required IDs hides bugs. For large messages, build the literal next to the encode call in wire order.

On a fixed-only message (no groups or var-data), as_bytes_with_header, as_body_bytes, encoded_length*, and into_remaining_mut exist only after fixed(&FixedFields). Calling them on the value returned by wrap* is a type error — that is what stops a reused buffer from publishing leftover body bytes or packing the next message over a stale body.

Individual setters stay on the unfixed encoder after wrap* and also on raw_fixed() (body-relative offsets). Prefer fixed(&FixedFields) when you have every field; use raw_fixed() when you want a dedicated writer:

#![allow(unused)]
fn main() {
// Dedicated raw writer (setters also exist on the unfixed encoder).
// `as_bytes_with_header` is only on FieldsFixed after `fixed(&FixedFields)`.
let mut buf = [0u8; HeartbeatEncoder::compute_length_with_header()];
let mut w = HeartbeatEncoder::try_wrap_and_apply_header(&mut buf, 0)?
    .raw_fixed();
w.sequence(7);
w.timestamp_wire(0);
let dec = HeartbeatDecoder::try_from(&buf[..HeartbeatEncoder::ENCODED_LENGTH])?;
assert_eq!(dec.sequence(), 7);
}

(From book/examples/heartbeat-encode.rs — compiled against the feature-tour codec.)

raw_fixed() writes into the buffer you already sized. It does not mark the message complete: omitted required setters leave stale bytes, and as_bytes_with_header / encoded_length* / into_remaining_mut stay locked. Set every required field, then call fixed(&FixedFields) for the complete-message views. Slicing &buf[..ENCODED_LENGTH] yourself is possible but is not the completeness-checked path.

Optional fields and apply_nulls

try_wrap_and_apply_header / wrap_and_apply_header write the message header only — they do not fill optional fixed fields with schema null sentinels (sbe-tool parity). Unwritten optional bytes retain whatever was already in the buffer (often zero, sometimes stale).

fixed() closes that gap for you. Optional fields are Option<T> in the generated FixedFields struct, and fixed() writes the schema null wire image for every None — including fixed arrays and nested optional composite members. Since fixed() is the only route to a message’s tails and to fixed-only complete byte views, the ordinary path never leaves a stale optional behind:

// `price` is optional; None writes the schema null image, not stale bytes.
// (Illustrative — use your schema's message name and optional field.)
let len = OrderEncoder::wrap_and_apply_header(&mut buf, 0)
    .fixed(&OrderFixedFields { symbol: *b"IBM     ", price: None })
    .encoded_length_with_header();

apply_nulls() remains on the unfixed encoder after wrap*, for the case where you set individual optional fields yourself and no FixedFields value describes which optionals are unset. It is generated only for messages that declare at least one optional field, and it is the counterpart to sbe-tool’s nullify_optional_fields().

Group entries need no call at all. Every add() writes the null image for the entry’s optional fields before your setters run, so a reused buffer cannot leak a previous entry’s value. The cover is narrower than the message-level path, though: it applies to optional fields with a declared nullValue and a width of 1-8 bytes. An optional array or composite inside a group entry is not nulled — set it explicitly if your schema has one.

See Why NullVal Instead of Option and, when porting, Coming from sbe-tool.

Character arrays: fixed-width char fields become [u8; N]. Pass a shorter &str via the _str setter — auto-padded with NULs. On decode, copy_* copies the raw bytes into your buffer, or read the slice with vehicle_code():

#![allow(unused)]
fn main() {
let complete_len = CarEncoder::compute_length()
    .fuel_figures_ragged(0, |_| Ok(()))?
    .performance_figures_ragged(0, |_| Ok(()))?
    .manufacturer(5)?
    .model(5)?
    .activation_code(3)?
    .encoded_length_with_header();
const PAD: usize = 256;
assert!(complete_len <= PAD, "car length {complete_len} exceeds pad {PAD}");
let mut storage = [0u8; PAD];
let buf = &mut storage[..complete_len];
let fields = CarFixedFields {
    serial_number: 1234,
    model_year: 2013,
    available: true.into(),
    code: Model::A,
    some_numbers: [10, 20, 30, 40],
    vehicle_code: *b"ABCDEF",
    extras: OptionalExtras::default(),
    engine: Engine::new(2000, 4, *b"123", 0i8, false.into(), Booster::new(BoostType::TURBO, 210)),
};
let n = CarEncoder::try_wrap_and_apply_header(buf, 0)?
    .fixed(&fields)
    .fuel_figures(0, |_| Ok(()))?
    .performance_figures(0, |_| Ok(()))?
    .manufacturer_as_str("Honda")?
    .model_as_str("Civic")?
    .activation_code_as_str("abc")?
    .encoded_length_with_header();
assert_eq!(n, complete_len);

let car = CarDecoder::try_from(&buf[..n])?;
let mut dst = [0u8; 6];
assert_eq!(car.copy_vehicle_code(&mut dst), 6);
assert_eq!(&dst, b"ABCDEF");
assert_eq!(car.vehicle_code(), *b"ABCDEF");
}

(From book/examples/fixed-char-arrays.rs — compiled against the feature-tour codec.)

The Car encoder’s fixed fields include vehicle_code: [u8; 6] (schema char array) and some_numbers: [u32; 4]. See the feature tour for the complete Car example with groups and var-data.

Start here for a full runnable map of features: sbe-feature-tour (cargo run --manifest-path samples/sbe-feature-tour/Cargo.toml).
More recipes: Recipes.

Method Chaining

ergo-sbe encoders are designed so the entire encode reads as one expression, from wrap_and_apply_header through .fixed(...) and every dynamic tail, ending in .encoded_length_with_header(). Bind only the resulting length; do not retain intermediate encoder variables.

Prefer (one chain, one let):

#![allow(unused)]
fn main() {
let mut buf = [0u8; HeartbeatEncoder::compute_length_with_header()];
// Buffer is exact size from const compute_length_with_header — no bounds check needed.
let len = HeartbeatEncoder::try_wrap_and_apply_header(&mut buf, 0)?
    .fixed(&HeartbeatFixedFields { sequence: 7, timestamp: 0 })
    .encoded_length_with_header();
let dec = HeartbeatDecoder::try_from(&buf[..len])?;
assert_eq!(dec.sequence(), 7);
}

(From book/examples/heartbeat-encode.rs — compiled against the feature-tour codec.)

Staged chaining vs fixed-only

For a fixed-only message like Heartbeat, wrap* returns HeartbeatEncoder<'_, H, FieldsUnfixed>. .fixed(&HeartbeatFixedFields { … }) consumes that value and returns FieldsFixed, which is the only phase that exposes as_bytes_with_header / as_body_bytes / encoded_length* / into_remaining_mut. Individual field setters stay on the unfixed phase and on raw_fixed(); they are not on that complete view.

Avoid (interrupted chain, rebinding):

// Each `let` breaks the chain and splays the pipeline across the screen.
// The `.unwrap()` calls are a code smell — the fallible chain should use `?`.
let enc = CarEncoder::wrap_and_apply_header(&mut buf, 0).fixed(&fields);
let enc = enc.fuel_figures(2, |g| { ... }).unwrap();
let enc = enc.manufacturer_as_str("Honda").unwrap();
let len = enc.encoded_length_with_header();

Every encoder stage is chainable — fixed() and each tail method return the next stage (or Result<NextStage, _>) and compose with ? in the same expression. Intermediate encoder rebinding and manual .unwrap() defeat this design.

For the full Car example with groups and var-data, see the feature tour page.

Decoding

Sequential decode consumes each tail in wire order. For callbacks throughout the chain, start with decoder.ordered():

#![allow(unused)]
fn main() {
pub fn demo_car_ordered_lane(wire: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
    let mut speeds = Vec::new();
    let mut octanes = Vec::new();
    let mut text = Vec::new();

    let len = CarDecoder::try_decode(wire, 0)?
        .ordered()
        .fixed(|car| {
            assert_eq!(car.serial_number(), 1234);
            Ok(())
        })?
        .fuel_figures(|entry, info| {
            // `info` carries the position the wire declares.
            assert_eq!(info.count, 2);
            assert_eq!(info.is_last(), info.index == 1);
            speeds.push(entry.speed());
            Ok(entry.ordered().usage_description(|_| Ok(()))?)
        })?
        .performance_figures(|entry, _info| {
            octanes.push(entry.octane_rating());
            Ok(entry.ordered().acceleration(|a, _| {
                let _ = (a.mph(), a.seconds());
                Ok(())
            })?)
        })?
        .manufacturer_as_str(|s| {
            text.push(s.to_owned());
            Ok(())
        })?
        .model_as_str(|s| {
            text.push(s.to_owned());
            Ok(())
        })?
        .activation_code_as_str(|s| {
            text.push(s.to_owned());
            Ok(())
        })?
        .encoded_length_with_header();

    assert_eq!(speeds, vec![30, 60]);
    assert_eq!(octanes, vec![95]);
    assert_eq!(text, vec!["Honda", "Civic VTi", "abcdef"]);
    assert_eq!(len, wire.len());
    Ok(())
}
}

The fixed callback comes before tails and receives a fixed-fields-only view; each group callback receives the entry and its EntryInfo, and var-data callbacks receive bytes or strictly validated text. Every callback returns Result<_, DecodeError>, so the closures infer. These callbacks borrow the original wire buffer, so bytes and text may be retained as the chain advances. The message chain ends on encoded_length_with_header() / as_bytes_with_header(), like encode — .done() is only to unwrap the staged complete. A nested ordered() walk returns that completion to the parent callback directly. The L3 sample shows this recursive form.

The underlying staged API also supports explicit iteration and skipping. Its group and var-data spellings can require iterator and tuple bindings:

Var-data into_<name>() returns (payload, next). Text fields also offer into_<name>_as_str(), with strict validation and the same tuple shape. These borrowed payloads can be retained while advancing later stages.

Prefer:

#![allow(unused)]
fn main() {
pub fn demo_car_decode_stages(wire: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
    let car = CarDecoder::try_decode(wire, 0)?;
    assert_eq!(car.serial_number(), 1234);
    assert_eq!(car.model_year(), 2013);
    // Domain conversion: BooleanType → bool when configured.
    let available: bool = car.available()?;
    assert!(available);
    assert_eq!(car.code(), Model::A);
    assert_eq!(car.discounted_model(), Model::C); // constant field
    assert_eq!(car.engine().capacity(), 2000);

    // Schema order: groups then var-data, one chain. Both of Car's groups have
    // entries that carry their own tails, so both take a visit closure: the
    // completion the closure returns is where the next entry starts, so the
    // group is walked exactly once.
    let mut speeds = Vec::new();
    let mut octanes = Vec::new();
    let (mfr, decoder) = car
        .into_fuel_figures(|entry| -> Result<_, sbe_rt::DecodeError> {
            speeds.push(entry.speed());
            // usageDescription is this entry's only tail, so reading it
            // completes the entry.
            entry.into_usage_description().map(|(_usage, done)| done)
        })?
        .into_performance_figures(|entry| -> Result<_, sbe_rt::DecodeError> {
            octanes.push(entry.octane_rating());
            // acceleration has fixed-stride entries, so it is a real iterator.
            let mut accel = entry.into_acceleration()?;
            assert_eq!((&mut accel).len(), 2);
            accel.finish()
        })?
        .into_manufacturer_as_str()?;
    assert_eq!(speeds, vec![30, 60]);
    assert_eq!(octanes, vec![95]);
    let (model, decoder) = decoder.into_model_as_str()?;
    let (code, _decoder) = decoder.into_activation_code_as_str()?;
    // All three &str coexist — each borrows 'a from the original wire buffer.
    assert_eq!((mfr, model, code), ("Honda", "Civic VTi", "abcdef"));
    Ok(())
}
}

(Real code from the sbe-feature-tour sample. fuelFigures and performanceFigures entries carry tails, so they take closures; acceleration is fixed-stride, so it is an iterator.)

Consecutive var-data fields chain through the next stage each tuple returns; the borrowed slices stay valid while later stages advance:

#![allow(unused)]
fn main() {
fn count_car_text_bytes(wire: &[u8]) -> Result<usize, sbe_rt::DecodeError> {
    let (manufacturer, next) = CarDecoder::try_from(wire)?
        .skip_fuel_figures()?
        .skip_performance_figures()?
        .into_manufacturer()?;
    let (model, next) = next.into_model()?;
    let (activation_code, _complete) = next.into_activation_code()?;
    Ok(manufacturer.len() + model.len() + activation_code.len())
}
}

For callbacks instead of tuples, use the ordered lane’s <name>(|bytes| ..) and <name>_as_str(|text| ..), which return DecodeError.

The generated staged walk advances once through dynamic tails. Random-access getters used before that walk, including counts or lengths for later tails, can add scans. See Asking before walking.

Multi-Schema Patterns

SBE schemas often share types (messageHeader, groupSizeEncoding, composites, enums, sets). ergo-sbe supports two approaches:

The <include> path is what the SBE spec expects. The shared-Ir path is a convenience for tooling, build scripts, and any workflow where you already have the shared schema parsed in memory.

Shared Ir — parse, then share

// 1. Parse the shared schema once (composites, enums, sets).
let common = ergo_sbe::parse_file("schemas/common-types.xml")?;

// 2. Parse a consumer schema — no <include> needed.
let orders = ergo_sbe::parse_file_with_shared("schemas/orders.xml", &common)?;

// 3. Each schema gets its own module.
let generator = ergo_sbe::Generator::new(
    ergo_sbe::GenerationConfig::new("common_types").with_shared_module("common_types"),
);
let modules = generator.generate_multi(&[
    (&ergo_sbe::Schema::from_ir(common), "common_types"),
    (&ergo_sbe::Schema::from_ir(orders), "orders"),
])?;

With with_shared_module("common_types"), the first entry owns the shared enums/sets/composites; later entries pub use super::common_types::* and skip duplicate type generation.

Module names must be unique, non-empty Rust identifiers (no path separators or keywords). Before any file is written, shared types with the same name are compared by a canonical wire fingerprint (token order, primitive encodings, offsets, presence, null/min/max, discriminants/choices, sinceVersion, and schema byte order). A name collision with a different fingerprint fails generation with GenerateError::IncompatibleSharedType rather than silently reusing the first schema’s layout.

parse_with_shared from in-memory strings

let common = ergo_sbe::parse(
    r#"<?xml version="1.0"?>
<messageSchema package="common" id="0" version="1" byteOrder="littleEndian">
  <types>
    <composite name="messageHeader">
      <type name="blockLength" primitiveType="uint16"/>
      <type name="templateId" primitiveType="uint16"/>
      <type name="schemaId" primitiveType="uint16"/>
      <type name="version" primitiveType="uint16"/>
    </composite>
    <composite name="Price">
      <type name="mantissa" primitiveType="int64"/>
      <type name="exponent" primitiveType="int8"/>
    </composite>
  </types>
</messageSchema>"#,
)?;

// No <types> / <include> — Price resolves from `common`.
let orders = ergo_sbe::parse_with_shared(
    r#"<?xml version="1.0"?>
<messageSchema package="orders" id="1" version="1" byteOrder="littleEndian"
               headerType="messageHeader">
  <message name="NewOrder" id="1">
    <field name="price" id="1" type="Price"/>
  </message>
</messageSchema>"#,
    &common,
)?;

The shared Ir path does not recover bare top-level <type> typedefs (those are inlined during parsing and dropped from the token stream). Reference them through a <composite> / <enum> / <set> in the shared schema instead.

Full build.rs — one helper call

Module names are supplied, not derived from file stems, so a hyphenated common-types.xml can emit common_types.rs. The helper parses the shared schema first, resolves consumers against it, validates the whole set, then writes. A late consumer failure leaves no partial files. Cargo watches every root and every resolved include.

// build.rs
use std::path::Path;
use ergo_sbe::{GenerationConfig, SchemaFile, generate_multi_to_out_dir};

fn main() -> ergo_sbe::miette::Result<()> {
    generate_multi_to_out_dir(
        SchemaFile::new(Path::new("schemas/common-types.xml"), "common_types"),
        &[
            SchemaFile::new(Path::new("schemas/orders.xml"), "orders"),
            SchemaFile::new(Path::new("schemas/fills.xml"), "fills"),
        ],
        GenerationConfig::new("common_types"),
    )?;
    Ok(())
}

Consumer modules import the shared module for cross-schema type resolution:

mod common_types { include!(concat!(env!("OUT_DIR"), "/common_types.rs")); }
mod orders {
    use super::common_types::*;       // shared types + header composite
    include!(concat!(env!("OUT_DIR"), "/orders.rs"));
}
mod fills {
    use super::common_types::*;
    include!(concat!(env!("OUT_DIR"), "/fills.rs"));
}

AnyMessage is generated once per schema module. Template ids are not unique across schemas. Generate an opt-in AnySchemaMessage over every configured schema with Generator::generate_schema_dispatch:

#![allow(unused)]
fn main() {
use ergo_sbe::{GenerateError, GeneratedModule, GenerationConfig, Generator, Schema};

fn dispatcher(market: &Schema, trading: &Schema) -> Result<GeneratedModule, GenerateError> {
    Generator::new(GenerationConfig::new("market")).generate_schema_dispatch(
        &[(market, "market"), (trading, "trading")],
        "any_schema",
    )
}
}

Write the returned source to its path beside the codec modules, then include any_schema.rs in a sibling module. This also works when the codecs were generated separately with different conversion settings. Each codec must have AnyMessage dispatch enabled. The combined enum wraps it in a variant named from the module, such as Market and Trading, and reads schemaId before templateId. Decode errors retain the originating schema’s error type.

Schema ids and module names must be unique. Headers must declare the same wire layout and byte order, with a required, encoded schemaId. Custom layouts and big-endian headers work; mixed layouts or byte orders are rejected as ambiguous. Single-schema generation and the ordinary codec hot paths are unchanged.

Pass a slice bounded to one transport frame to AnySchemaMessage::decode. An unknown schema id returns Other { schema_id, template_id, frame }. An unknown template in a known schema remains that module’s AnyMessage::Unknown. Both retain the supplied header and body. as_bytes() borrows the complete frame without allocating, including future-version fields and unknown frames, for persistence or forwarding.

See also: sbe-codegen-examples (reusable generator setup), multi_schema_versioning_test (versioned schemas with shared types), exchange-example (multi-schema exchange feed with IPC).

Coming from sbe-tool

Side-by-side mapping for teams migrating from the official Simple Binary Encoding Rust generator (sbe-tool). Within the [published SBE profile] (../design-notes/feature-matrix.md) and docs/SBE_COMPATIBILITY.md, ergo-sbe aims for official-SBE wire fidelity with sbe-tool; the API shape is intentionally different. Do not read this as unqualified “binary compatible with every SBE feature.”

The #1 trap: wrap offset

// Frame at buf[0..]:
// sbe-tool:  enc.wrap(buf, 8)              // body starts at 8
// ergo-sbe:  Enc::wrap(buf, 0)             // message starts at 0
//            Enc::wrap_and_apply_header(buf, 0)

Passing sbe-tool’s 8 into ergo-sbe for a frame at zero mis-aligns every field. Generated rustdoc on wrap / wrap_and_apply_header / decode repeats this callout.

Header modes (fair comparison table)

Use the same logical work on both sides when comparing or porting:

• ergon wrap = message start; sbe-tool wrap = body offset.
• sbe-tool encoded_length() is body only. ergon encoded_length_with_header() includes the header. Never invent 8 + encoded_length() to “prove” a header was written if .header(0) was not called on the sbe-tool arm.

Full fairness rules for benchmarks: Benchmarks methodology.

Groups: .parent() hopscotch vs closures

#![allow(unused)]
fn main() {
pub fn encode_sample_car(buf: &mut [u8]) -> Result<usize, sbe_rt::EncodeError> {
    let mut extras = OptionalExtras::default();
    extras.cruise_control(true).sports_pack(true);

    // Buffer pre-sized from EncodedLength; try_* still validates extent.
    let len = CarEncoder::try_wrap_and_apply_header(buf, 0)
        .unwrap()
        .fixed(&CarFixedFields {
            serial_number: 1234,
            model_year: 2013,
            available: true.into(),
            code: Model::A,
            some_numbers: [10, 20, 30, 40],
            vehicle_code: [b'A', b'B', b'C', b'D', b'E', b'F'],
            extras,
            engine: Engine::new(
                2000,
                4,
                [b'1', b'2', b'3'],
                0i8,
                false.into(),
                Booster::new(BoostType::TURBO, 210),
            ),
        })
        .fuel_figures(2, |g| {
            g.add(|mut e| {
                e.speed(30).mpg(35.9);
                e.usage_description_as_str("Urban")
            })?;
            g.add(|mut e| {
                e.speed(60).mpg(25.0);
                e.usage_description_as_str("Highway")
            })?;
            Ok(())
        })?
        .performance_figures(1, |g| {
            g.add(|mut e| {
                e.octane_rating(95);
                e.acceleration(2, |a| {
                    a.add(|x| {
                        x.mph(30).seconds(4.0);
                        Ok(())
                    })?;
                    a.add(|x| {
                        x.mph(60).seconds(7.5);
                        Ok(())
                    })
                })
            })?;
            Ok(())
        })?
        .manufacturer_as_str("Honda")?
        .model_as_str("Civic VTi")?
        .activation_code_as_str("abcdef")?
        .encoded_length_with_header();

    Ok(len)
}
}

Compile-time order: you cannot call asks before bids — the stage type has no asks method. See Wire order via named stages.

Length APIs

Do not default to vec![0u8; 4096] or Vec::with_capacity(MAX) then truncate. See Buffer sizing and Exact sizing.

Optional fields: nullify_optional_fields() → apply_nulls()

Neither generator nullifies on wrap, so in sbe-tool an optional field you never set keeps whatever was already in the buffer unless you remember to call nullify_optional_fields(). The ergon equivalent is apply_nulls(), but the port is usually to delete the call rather than rename it:

Optional fields are Option<T> in the generated *FixedFields struct, and fixed() writes the schema null wire image for every None — including fixed arrays and nested optional composite members.

apply_nulls() is still generated (message encoders with at least one optional field, on the unfixed stage after wrap*) for the case where you write individual optionals through raw_fixed() and have no FixedFields value describing which ones are unset.

One asymmetry to carry across: group-entry auto-nulling covers optional fields that have a declared nullValue and a width of 1-8 bytes. An optional array or composite inside a group entry is not nulled, where the message-level path does handle those shapes. If your schema has one, set it explicitly.

See Optional fields and apply_nulls and Why NullVal instead of Option.

Decode entry

ergo-sbe decoder wrap and try_wrap take the message start, including the header, while sbe-tool’s wrap takes the body offset. Use try_decode when the header metadata is not already available:

See Trust Boundary.

Decoding: lanes, not one cursor

sbe-tool gives you a single &mut decoder carrying a limit cursor. Every group and var-data accessor reads at limit and advances it, so the order you call methods in is the wire walk. ergon splits that:

• Sequential: into_* / skip_* (or decoder.ordered() for one callback per tail)
• Random-access: try_decode — any order, Sync

A group whose entries carry their own tails takes a visit closure; a fixed-stride group hands back an iterator.

Start here when porting:

// sbe-tool: one cursor, order is a convention
let car = CarDecoder::default()
    .wrap(ReadBuf::new(buf), 8, block_len, version);   // body offset, not 0
let mut ff = car.fuel_figures_decoder();               // consumes `car`
while ff.advance()?.is_some() { /* … */ }
let mut car = ff.parent()?;                            // hand it back
let coords = car.manufacturer_decoder();               // (offset, len)
let manufacturer = car.manufacturer_slice(coords);

// ergo-sbe: consuming stages carry the next tail offset.
// fuelFigures entries carry var-data, so the step is a visit closure and the
// completion it returns is where the next entry starts — one pass, no rescan.
let (manufacturer, car) = CarDecoder::try_decode(buf, 0)?
    .into_fuel_figures(|e| e.into_usage_description().map(|(_usage, done)| done))?
    .skip_performance_figures()?
    .into_manufacturer()?;

Note what disappears in the port: no .parent() hop, no (offset, length) coordinate pair threaded to a second _slice() call, and no &mut on a decoder you only wanted to read.

Fixed-block messages — no groups, no var-data — get no memoized() or ordered(), and AnyMessage offers only into_<name>() for them. Every field is already random-access off the block.

Full per-lane pros, cons, and cost table: Decoder lanes.

Version handling

Decoders are version-aware: tail offsets use the wire acting block length, not only the compiled block length. Optional / sinceVersion fields follow schema presence rules. Prefer explicit try_* entry points when reading mixed-version streams.

What has no direct ergon equivalent (and why)

Trust boundary

try_* returns Result on short buffers (and identity mismatches). Bare wrap panics if short. Bare decode is a hybrid: panics if short, but still returns Err on wrong template/schema. decode_unchecked is unchecked extent + checked identity. After a safe constructor succeeds, fixed-field accessors are branch-free. Full detail: Trust Boundary.

Further reading

• Type-state and runtime cost
• API freeze decisions
• Feature matrix
• Sample: sbe-feature-tour

Error Diagnostics

Schema errors use miette for pinpointed diagnostics. The generator shows what went wrong, where in the XML, and a unique error code you can match on programmatically.

Invalid type reference

Referencing a type that doesn’t exist:

<field name="badField" id="10" type="NonExistentType"/>

ergo_sbe::schema_parse::invalid

  × invalid type for field 'badField': NonExistentType
    ╭─[schema.xml:15:9]
 14 │         <!-- NonExistentType not defined -->
 15 │         <field name="badField" id="10" type="NonExistentType"/>
    ·         ───────────────────────────┬───────────────────────────
    ·                                    ╰── invalid here
 16 │     </message>
    ╰────

The error code ergo_sbe::schema_parse::invalid identifies the variant. The span points to the exact attribute. The source line and surrounding context are rendered automatically.

Missing required attribute

Omitting name on a <field>:

ergo_sbe::schema_parse::missing

  × missing field @name
    ╭─[schema.xml:15:9]
 14 │     <message name="TestMessage" id="1">
 15 │         <field id="10" type="uint8"/>
    ·         ──────────────┬──────────────
    ·                       ╰── missing here
 16 │     </message>
    ╰────

Duplicate template ID

Two messages sharing the same id:

ergo_sbe::schema_parse::resolve

  × resolution error: duplicate template id 1 for message
  │ AnotherMessageWithId1
  ╰─▶ duplicate template id 1 for message AnotherMessageWithId1

Invalid enum encoding type

ergo_sbe::schema_parse::invalid

  × invalid enum encodingType: NonExistentEncodingType
    ╭─[schema.xml:13:9]
 12 │             <!-- encodingType references non-existent type -->
 13 │ ╭─▶         <enum name="BadEnum" encodingType="NonExistentEncodingType">
 14 │ │               <validValue name="Value1">1</validValue>
 15 │ ├─▶         </enum>
    · ╰──── invalid here
 16 │         </types>
    ╰────

Multi-line spans show the full element, with the label pointing to the offending attribute.

Use in build scripts

ParseError implements miette::Diagnostic. Wrap it in miette::Report to render the full diagnostic with source context:

use ergo_sbe::parse_file;

match parse_file("my-schema.xml") {
    Ok(_) => { /* regenerate codec */ }
    Err(e) => {
        let report = miette::Report::new(e);
        eprintln!("{report:?}");
        std::process::exit(1);
    }
}

For programmatic handling, match on the variant directly — ParseError is a plain enum, no downcast needed. Keep a wildcard so new variants are not a compile break:

#![allow(unused)]
fn main() {
use ergo_sbe::{parse_file, ParseError};

match parse_file("my-schema.xml") {
    Ok(_) => {}
    Err(ParseError::MalformedXml { message, .. }) => {
        eprintln!("malformed XML: {message}");
    }
    Err(ParseError::Missing { what, .. }) => {
        eprintln!("missing {what}");
    }
    Err(ParseError::Invalid { what, value, .. }) => {
        eprintln!("invalid {what}: {value}");
    }
    Err(ParseError::Resolve { error, .. }) => {
        eprintln!("resolve: {error}");
    }
    Err(ParseError::Io { path, source, .. }) => {
        eprintln!("cannot read {}: {source}", path.display());
    }
    Err(ParseError::Include { href, cause, .. }) => {
        eprintln!("include {href}: {cause}");
    }
    // Forward-compatible: ParseError is #[non_exhaustive].
    Err(other) => {
        eprintln!("{other}");
    }
}
}

Out-of-range null / min / max

A present nullValue, minValue, or maxValue is parsed fail-closed against the declared primitive width. nullValue="256" on uint8 is rejected (it is not a valid one-byte sentinel). Signed types accept the type’s full range (int8 -1 is fine; int8 128 is not).

ergo_sbe::schema_parse::invalid

  × invalid nullValue: '256' is out of range for UInt8

Without that check the generator used to emit 256_u64 as u8, so Some(0) and None collided on the wire.

Error variants

ParseError is #[non_exhaustive]. Match with a wildcard. Current variants:

Every diagnostic variant except Io carries source_code and an optional span. Include highlights the <include> element when the include was parsed from a document.

Migration from 0.1.x: IncludeError { message } is now Include { href, attempted, cause, .. }. Root read_to_string failures are Io, not MalformedXml.

Feature Tour

Runnable examples pull live source from sbe-feature-tour (compiled by docs_validation_test). Schematics that cannot run in the harness stay rust,ignore.

• Exact Sizing — compute_length_with_header before you encode
• Bulk Arrays — bulk_add(&[Entry]) for fixed-stride leaf groups
• Decoder Lanes — random access, staged into_*, ordered callbacks, .memoized()
• What Generated Code Looks Like — stages, metadata, reserved names
• Trust Boundaries — try_* → Result; wrap panics if short; decode is hybrid
• Domain Objects (DTOs) — owned snapshots (never on the hot path)
• Multi-Template Dispatch — AnyMessage routes by template ID

Exact Sizing

Dynamic messages expose schema-aware size APIs. Flat shapes get a direct checked helper; nested or ragged shapes get a staged *EncodedLength builder. Allocate or claim exactly that many bytes, then write groups and var-data in wire order:

#![allow(unused)]
fn main() {
pub fn demo_car_size_and_encode() -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    // Fuel: 2 entries with usage ASCII lengths 5 and 7.
    // Performance: 1 entry with 2 nested acceleration rows (fixed-only entries).
    // Message var-data: manufacturer / model / activationCode lengths.
    let complete_len = CarEncoder::compute_length()
        .fuel_figures_ragged(2, |ff| {
            ff.add()?.usage_description(5)?; // "Urban"
            ff.add()?.usage_description(7)?; // "Highway"
            Ok(())
        })?
        .performance_figures_ragged(1, |pf| {
            pf.add()?.acceleration(|acc| {
                acc.uniform(2)?;
                Ok(())
            })?;
            Ok(())
        })?
        .manufacturer(5)? // "Honda"
        .model(9)? // "Civic VTi"
        .activation_code(6)? // "abcdef"
        .encoded_length_with_header();

    // Exact size from compute_length → stack pad (this demo fits well under 512).
    const CAR_PAD: usize = 512;
    assert!(
        complete_len <= CAR_PAD,
        "sample car length {complete_len} exceeds stack pad {CAR_PAD}"
    );
    let mut storage = [0u8; CAR_PAD];
    let written = encode_sample_car(&mut storage[..complete_len])?;
    assert_eq!(
        written, complete_len,
        "CarEncodedLength must equal encoder-produced length"
    );
    Ok(storage[..written].to_vec())
}
/// Encode the canonical sample car into `buf` (must be pre-sized).
pub fn encode_sample_car(buf: &mut [u8]) -> Result<usize, sbe_rt::EncodeError> {
    let mut extras = OptionalExtras::default();
    extras.cruise_control(true).sports_pack(true);

    // Buffer pre-sized from EncodedLength; try_* still validates extent.
    let len = CarEncoder::try_wrap_and_apply_header(buf, 0)
        .unwrap()
        .fixed(&CarFixedFields {
            serial_number: 1234,
            model_year: 2013,
            available: true.into(),
            code: Model::A,
            some_numbers: [10, 20, 30, 40],
            vehicle_code: [b'A', b'B', b'C', b'D', b'E', b'F'],
            extras,
            engine: Engine::new(
                2000,
                4,
                [b'1', b'2', b'3'],
                0i8,
                false.into(),
                Booster::new(BoostType::TURBO, 210),
            ),
        })
        .fuel_figures(2, |g| {
            g.add(|mut e| {
                e.speed(30).mpg(35.9);
                e.usage_description_as_str("Urban")
            })?;
            g.add(|mut e| {
                e.speed(60).mpg(25.0);
                e.usage_description_as_str("Highway")
            })?;
            Ok(())
        })?
        .performance_figures(1, |g| {
            g.add(|mut e| {
                e.octane_rating(95);
                e.acceleration(2, |a| {
                    a.add(|x| {
                        x.mph(30).seconds(4.0);
                        Ok(())
                    })?;
                    a.add(|x| {
                        x.mph(60).seconds(7.5);
                        Ok(())
                    })
                })
            })?;
            Ok(())
        })?
        .manufacturer_as_str("Honda")?
        .model_as_str("Civic VTi")?
        .activation_code_as_str("abcdef")?
        .encoded_length_with_header();

    Ok(len)
}
}

(This code comes from the sbe-feature-tour sample crate.)

Bulk Arrays

For repeating groups with fixed-size entries (no var-data, no nested groups), generated encoders offer a bulk_add(&[Entry]) path that validates the destination region once and writes every entry.

Car fuelFigures has var-data (usageDescription), so it is not eligible. The nested acceleration group is — each row is mph + seconds only:

#![allow(unused)]
fn main() {
pub fn demo_bulk_add() -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let mut extras = OptionalExtras::default();
    extras.cruise_control(true);
    let rows = [
        CarPerformanceFiguresAccelerationEntry {
            mph: 30,
            seconds: 4.0,
        },
        CarPerformanceFiguresAccelerationEntry {
            mph: 60,
            seconds: 7.5,
        },
    ];
    let complete_len = CarEncoder::compute_length()
        .fuel_figures_ragged(0, |_| Ok(()))?
        .performance_figures_ragged(1, |pf| {
            pf.add()?.acceleration(|acc| {
                acc.uniform(2)?;
                Ok(())
            })?;
            Ok(())
        })?
        .manufacturer(5)?
        .model(5)?
        .activation_code(3)?
        .encoded_length_with_header();
    const PAD: usize = 256;
    assert!(
        complete_len <= PAD,
        "bulk-add car length {complete_len} exceeds pad {PAD}"
    );
    let mut storage = [0u8; PAD];
    let buf = &mut storage[..complete_len];
    let len = CarEncoder::try_wrap_and_apply_header(buf, 0)?
        .fixed(&CarFixedFields {
            serial_number: 1234,
            model_year: 2013,
            available: true.into(),
            code: Model::A,
            some_numbers: [10, 20, 30, 40],
            vehicle_code: *b"ABCDEF",
            extras,
            engine: Engine::new(
                2000,
                4,
                *b"123",
                0i8,
                false.into(),
                Booster::new(BoostType::TURBO, 210),
            ),
        })
        .fuel_figures(0, |_| Ok(()))?
        .performance_figures(1, |g| {
            g.add(|mut e| {
                e.octane_rating(95);
                e.acceleration(2, |a| {
                    a.bulk_add(&rows)?;
                    Ok(())
                })
            })?;
            Ok(())
        })?
        .manufacturer_as_str("Honda")?
        .model_as_str("Civic")?
        .activation_code_as_str("abc")?
        .encoded_length_with_header();
    assert_eq!(len, complete_len);
    Ok(buf[..len].to_vec())
}
}

(From samples/sbe-feature-tour — compiled and run in that crate’s tests.)

bids / asks on the l3-book schema have a nested orders group, so those outer groups are not eligible either. Only a leaf group whose entries are a pure fixed block gets bulk_add.

Constants and MetaAttribute expose schema metadata on every generated type (HeartbeatDecoder::sequence_meta_attribute(MetaAttribute::Presence) and friends). See the generated module after cargo build of the feature-tour sample.

Decoder Lanes

A decoder with groups or var-data has two jobs: read some fields in any order, or walk the whole message once in schema order. A group decoder from a random-access getter implements Iterator for partial traversal; it is not a third message-decoding lane.

Encoding is one state machine: each stage is the cursor, so the next legal field is the only method on that type. See Encode and Decode and Method Chaining. Decoding is the choice, because a decoder can be asked to read in an order the encoder never had.

Fixed fields stay random-access in all of them. Ordered also offers a fixed callback (fixed-fields-only view, not the full decoder). A message with no groups and no var-data has one lane: the base decoder. memoized() and ordered() are not generated; AnyMessage offers only into_<name>().

Worked nested example: L3 order book. AnyMessage can land in a lane directly (into_car(), into_car_memoized()).

sbe-tool has one &mut flyweight with a limit cursor. Wrong order reads the next group’s bytes as a length prefix; re-read means re-wrap; no useful &-sharing. Ergon splits those jobs. Full mapping: Coming from sbe-tool.

In every ergon lane, try_* construction makes a short buffer a DecodeError (not a panic), and a group’s numInGroup is checked against the bytes that are actually there before an entry reaches you.

Random access

Any-order getters. The decoder holds the buffer, offset, and acting header values — nothing else. Each dynamic-tail getter re-walks from the fixed block.

#![allow(unused)]
fn main() {
pub fn demo_car_random_access(wire: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
    let car = CarDecoder::try_decode(wire, 0)?;
    // Manufacturer is the first var-data field, after both groups — still legal
    // here because random access rescan preceding tails.
    assert_eq!(car.manufacturer_as_str()?, "Honda");
    assert_eq!(car.serial_number(), 1234);
    let mut speeds = Vec::new();
    for entry in car.fuel_figures()? {
        speeds.push(entry?.speed());
    }
    assert_eq!(speeds, vec![30, 60]);
    assert_eq!(car.model_as_str()?, "Civic VTi");
    Ok(())
}
}

Memoized (decoder.memoized())

Same getter names. First access to a tail walks forward from the cache frontier; later accesses reuse it. Construction is O(1) and allocates nothing. Decoded values match the base lane, including schema max-length rejection: warming the cache with encoded_length() does not accept a payload the base getter would refuse.

let decoder = CarDecoder::try_from(bytes)?;   // small, Sync, recalculates tails
let decoder = decoder.memoized();             // lazy cache, no allocation

read_header(&decoder)?;
read_groups(&decoder)?;
read_final_tail(&decoder)?;                   // reuses discovered boundaries

Build it once and pass &CarMemoizedDecoder. Calling .memoized() inside every function creates a separate empty cache. Cell interior mutability: Send but not Sync. into_inner() returns the base decoder.

The base lane’s tail_offset_k re-walks every preceding tail on every getter — quadratic even in schema order. Memoized makes that sweep linear. Staged already carries the cursor, so it needs no cache.

Use it when several helpers read the same decoder, or when you jump to a late tail and come back. Skip it for one tail and stop, a full wire-order walk (use staged), or if you need Sync.

The cache covers message-level tails only. Nested groups inside an entry use an ordinary entry decoder. just bench-diagnostics → versioned_l3_bench.

Staged (into_* / skip_*)

Sequential decode, the encoder dual. Each into_* consumes the stage. Wrong order is a missing method.

Iterator is implemented for &mut Iter only — for entry in iter does not compile, so a loop cannot drop the rest of the message. Also ExactSizeIterator and FusedIterator.

#![allow(unused)]
fn main() {
pub fn demo_car_decode_stages(wire: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
    let car = CarDecoder::try_decode(wire, 0)?;
    assert_eq!(car.serial_number(), 1234);
    assert_eq!(car.model_year(), 2013);
    // Domain conversion: BooleanType → bool when configured.
    let available: bool = car.available()?;
    assert!(available);
    assert_eq!(car.code(), Model::A);
    assert_eq!(car.discounted_model(), Model::C); // constant field
    assert_eq!(car.engine().capacity(), 2000);

    // Schema order: groups then var-data, one chain. Both of Car's groups have
    // entries that carry their own tails, so both take a visit closure: the
    // completion the closure returns is where the next entry starts, so the
    // group is walked exactly once.
    let mut speeds = Vec::new();
    let mut octanes = Vec::new();
    let (mfr, decoder) = car
        .into_fuel_figures(|entry| -> Result<_, sbe_rt::DecodeError> {
            speeds.push(entry.speed());
            // usageDescription is this entry's only tail, so reading it
            // completes the entry.
            entry.into_usage_description().map(|(_usage, done)| done)
        })?
        .into_performance_figures(|entry| -> Result<_, sbe_rt::DecodeError> {
            octanes.push(entry.octane_rating());
            // acceleration has fixed-stride entries, so it is a real iterator.
            let mut accel = entry.into_acceleration()?;
            assert_eq!((&mut accel).len(), 2);
            accel.finish()
        })?
        .into_manufacturer_as_str()?;
    assert_eq!(speeds, vec![30, 60]);
    assert_eq!(octanes, vec![95]);
    let (model, decoder) = decoder.into_model_as_str()?;
    let (code, _decoder) = decoder.into_activation_code_as_str()?;
    // All three &str coexist — each borrows 'a from the original wire buffer.
    assert_eq!((mfr, model, code), ("Honda", "Civic VTi", "abcdef"));
    Ok(())
}
}

Each into_*_as_str() returns (&'a str, NextStage<'a>) — the &str borrows the original buffer. See Method chaining.

Start with try_decode / try_from. Do not verify first then walk — that is two structural passes. Inside a dynamic-entry callback, consume nested tails with into_* / skip_* / ordered() and return that completion. Random-access getters or a root manufacturer_len() before visiting preceding groups rescan.

Consuming stages and group iterators are #[must_use]. Dropping a stage without into_* / skip_* / finish() abandons remaining tails.

A fixed-stride iterator need not be drained: finish(), or the next tail’s into_* / skip_* on the iterator, skips unread entries as count × block_length. Dynamic-stride skip_* still walks each unread entry.

Asking before walking

Absent versioned tails are 0. If a primary getter already uses that name, the convenience accessor is omitted on that owner. Non-consuming is not constant-time on random-access owners — lookahead may scan preceding tails. Group byte length is not available from the count when entries have tails.

#![allow(unused)]
fn main() {
pub fn demo_car_visit_entries(wire: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
    let car = CarDecoder::try_decode(wire, 0)?;

    // Non-advancing: `car` is untouched and still owns every tail.
    assert_eq!(car.fuel_figures_count()?, 2);
    assert_eq!(car.manufacturer_len()?, 5);

    // A fixed-stride group is a real iterator, and it does not have to be
    // drained. Read one acceleration entry, then let the walk move on — the
    // unread entries are skipped by the next step, not lost.
    let (mfr, _rest) = car
        .skip_fuel_figures()?
        .into_performance_figures(|entry| -> Result<_, sbe_rt::DecodeError> {
            let mut accel = entry.into_acceleration()?;
            assert_eq!((&mut accel).len(), 2);
            let first = (&mut accel).next().expect("acceleration is not empty");
            assert_eq!(first.mph(), 30);
            assert_eq!(accel.remaining_entries(), 1);
            // `finish()` skips the entry we did not read and completes.
            accel.finish()
        })?
        .into_manufacturer_as_str()?;
    assert_eq!(mfr, "Honda");
    Ok(())
}
}

Prefer staged when you skip tails, hold stages across functions, or want for entry in &mut iter. A closure error consumes the stage; there is no continuation to retry.

Ordered (decoder.ordered())

One callback per tail, same spelling at message and nested-entry level, plus EntryInfo per entry. Generated on message decoders with tails and on group entries that carry tails. An entry whose existing accessor is named ordered keeps that accessor and does not get this lane.

ordered() is sbe_rt::Ordered<S> over the staged stage — no second cursor. A nested ordered() walk is the completion the parent callback owes. .done() only unwraps the staged complete. The message chain ends on encoded_length_with_header() / as_bytes_with_header(), like encode.

#![allow(unused)]
fn main() {
pub fn demo_car_ordered_lane(wire: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
    let mut speeds = Vec::new();
    let mut octanes = Vec::new();
    let mut text = Vec::new();

    let len = CarDecoder::try_decode(wire, 0)?
        .ordered()
        .fixed(|car| {
            assert_eq!(car.serial_number(), 1234);
            Ok(())
        })?
        .fuel_figures(|entry, info| {
            // `info` carries the position the wire declares.
            assert_eq!(info.count, 2);
            assert_eq!(info.is_last(), info.index == 1);
            speeds.push(entry.speed());
            Ok(entry.ordered().usage_description(|_| Ok(()))?)
        })?
        .performance_figures(|entry, _info| {
            octanes.push(entry.octane_rating());
            Ok(entry.ordered().acceleration(|a, _| {
                let _ = (a.mph(), a.seconds());
                Ok(())
            })?)
        })?
        .manufacturer_as_str(|s| {
            text.push(s.to_owned());
            Ok(())
        })?
        .model_as_str(|s| {
            text.push(s.to_owned());
            Ok(())
        })?
        .activation_code_as_str(|s| {
            text.push(s.to_owned());
            Ok(())
        })?
        .encoded_length_with_header();

    assert_eq!(speeds, vec![30, 60]);
    assert_eq!(octanes, vec![95]);
    assert_eq!(text, vec!["Honda", "Civic VTi", "abcdef"]);
    assert_eq!(len, wire.len());
    Ok(())
}
}

EntryInfo is index, wire-declared count, acting block_length, plus is_first() / is_last() / remaining(). No entry scan. Group byte length is absent: entries with tails only settle it by traversing.

Message-level fixed is optional. Skip it, or call it and lose the view. The view has no group/var-data accessors. A first tail named fixed owns the fixed() name, so the fixed-block callback yields: read fixed fields before ordered(). Every callback returns Result<_, DecodeError>; a caller error type converts after the walk. Entry-level wrappers have no fixed: the parent already holds the entry.

Empty and version-absent groups invoke the callback zero times. <group>_count() on the ordered stage reports the wire-declared count for an empty group and 0 for a group the wire version predates, which has no count.

Bytes and text callbacks borrow 'a from the original buffer. A callback error consumes the stage. Prefer ordered when you always decode whole messages and want one shape. Prefer staged to skip, hold stages, or iterate.

Full-frame bytes mid-walk

See Generated code.

What Generated Code Looks Like

For a schema with one message (Car), ergo-sbe emits a single Rust module with:

Decoder (flyweight over &[u8])

// Each message gets a zero-allocation decoder.
pub struct CarDecoder<'a> {
    pub(crate) buf: &'a [u8],
    pub(crate) offset: usize,
    pub(crate) acting_version: u16,
    pub(crate) acting_block_length: usize,
}

impl<'a> CarDecoder<'a> {
    // Illustrative only — real values from your schema.
    pub const SCHEMA_ID: u16 = 1;
    pub const TEMPLATE_ID: u16 = 1;
    pub const BLOCK_LENGTH: usize = 45;
    pub const HEADER_LENGTH: usize = 8;

    // Checked framed entry (message start). Validates header + fixed extent.
    pub fn try_decode(buf: &'a [u8], pos: usize)
        -> Result<Self, sbe_rt::DecodeError> { ... }

    // Proves the header+fixed-body extent and panics if short.
    // Caller does not need `unsafe` — the proof is in the constructor.
    pub fn wrap(buf: &'a [u8], message_offset: usize,
               acting_block_length: usize, acting_version: u16)
        -> Self { ... }

    // Full dynamic-tail structural check (associated, not `car.verify()`).
    pub fn verify(buf: &[u8]) -> Result<(), sbe_rt::VerifyError> { ... }

    // Fixed fields are random-access — zero-copy reads after a checked wrap.
    #[inline]
    pub fn serial_number(&self) -> u64 {
        let offset = self.offset + 0;
        u64::from_le_bytes(/* private read after extent proof */)
    }
}

Encoder (type-state stages)

// Wire order is enforced by named stage types. The root encoder also carries a
// fields-state parameter: tails are reachable only after `fixed()`.
pub struct CarEncoder<
    'a,
    H: sbe_rt::HeaderState = sbe_rt::HeaderPresent,
    F: sbe_rt::FieldsState = sbe_rt::FieldsUnfixed,
> { ... }
pub struct CarAfterFuelFigures<'a, H: sbe_rt::HeaderState = sbe_rt::HeaderPresent> { ... }
pub struct CarAfterPerformanceFigures<'a, H: sbe_rt::HeaderState = sbe_rt::HeaderPresent> { ... }
pub struct CarComplete<'a, H: sbe_rt::HeaderState = sbe_rt::HeaderPresent> { ... }

// `fixed()` moves FieldsUnfixed -> FieldsFixed; the tail methods exist only on
// the fixed phase, so `wrap(...).fuel_figures(...)` is a compile error.
pub type CarUnfixedEncoder<'a, H = sbe_rt::HeaderPresent> =
    CarEncoder<'a, H, sbe_rt::FieldsUnfixed>;

impl<'a, H: sbe_rt::HeaderState> CarEncoder<'a, H, sbe_rt::FieldsUnfixed> {
    pub fn fixed(self, fields: &CarFixedFields) -> CarEncoder<'a, H, sbe_rt::FieldsFixed> { ... }
}

// Calling stages out of order is a type error — `CarEncoder` has no `asks()`.
impl<'a, H: sbe_rt::HeaderState> CarEncoder<'a, H, sbe_rt::FieldsFixed> {
    pub fn fuel_figures(self, count: u16, f: impl FnOnce(...) -> ...) -> Result<CarAfterFuelFigures> { ... }
}
impl<'a> CarAfterFuelFigures<'a> {
    pub fn performance_figures(self, ...) -> Result<CarAfterPerformanceFigures> { ... }
}
impl<'a> CarComplete<'a> {
    pub fn encoded_length_with_header(&self) -> usize { ... }
    pub fn as_bytes_with_header(&self) -> &[u8] { ... }
}

Metadata: no field-name collisions

Utility methods like remaining, buffer, as_bytes_with_header, and as_body_bytes live on a zero-copy metadata struct from get_metadata(). A schema field named remaining or buffer therefore generates dec.remaining() / dec.buffer() as field accessors — no _field suffix.

Reserved decoder names (ordered, memoized, acting_version, acting_block_length, …) still rename a colliding message-level field (ordered_field()). Group entries do not rename against that list: if an entry field is actingVersion, it keeps acting_version() and the metadata getter is omitted.

Convenience accessors (<group>_count, <field>_len, ordered fixed) yield to a same-named tail or field — the primary getter wins. A domain-typed field counts: its getter takes the plain field name (renamed against the same reserved list), so orders_count beside a group orders stays the field. reserved_name_clash_test, ordered_lane_test.

What does remaining() mean?

Session framing (header then app payload) must use get_metadata().remaining() for the payload bytes.

let dec = CarDecoder::try_decode(&buf, 0)?;
dec.serial_number();                              // field accessor — never collides
dec.get_metadata().remaining();                   // metadata — never collides
dec.get_metadata().buffer();                      // metadata — never collides
// Car has groups/var-data: metadata is fixed-block only (not a full frame).
dec.get_metadata().as_fixed_region_with_header()?;
// Complete frame after walking tails, or rescan without consuming:
// complete.as_bytes_with_header() / dec.as_bytes_with_header()?
dec.encoded_length_with_header()?;                // hot path stays on base struct

The metadata struct holds a reference to the parent (zero-copy):

pub struct CarDecoderMetadata<'m, 'a> {
    decoder: &'m CarDecoder<'a>,
}

Encoders have the same pattern. Fixed-only messages expose as_body_bytes / as_bytes_with_header only after fixed(&FixedFields) (on the encoder and on FieldsFixed metadata). Messages with tails use as_fixed_body_bytes / as_fixed_region_with_header until the complete stage.

let meta = enc.get_metadata();
meta.as_fixed_body_bytes();            // fixed block only when message has tails
meta.as_fixed_region_with_header();    // header + fixed block — not full frame
meta.message_offset();                 // message start in buffer

Metadata limits (tailed messages)

Do not use meta.limit() as the next-message offset in a multi-message buffer for Car-shaped schemas — that truncates at the fixed block.

acting_version / acting_block_length (dual surface)

These remain inherent on the message decoder for the hot path (dec.acting_version(), dec.acting_block_length()) and are also exposed on metadata (dec.get_metadata().acting_version()) for a uniform placement facet. Both paths return the same values. They are reserved method names: a schema field named actingVersion becomes acting_version_field on the decoder.

Exact buffer sizing

// Fixed-only messages: const length.
let mut buf = [0u8; HeartbeatEncoder::compute_length_with_header()];

// Variable-length: staged builder (zero allocation).
let len = CarEncoder::compute_length()
    .fuel_figures_ragged(2, |ff| {
        ff.add()?.usage_description(5)?;
        Ok(())
    })?
    .performance_figures_ragged(0, |_| Ok(()))?
    .manufacturer(5)?
    .model(9)?
    .activation_code(6)?
    .encoded_length_with_header();

Configuration controls output size

Every aspect of generated output is configurable:

GenerationConfig::new("msgs")
    .with_display_debug(false)   // omit Debug/Display impls
    .with_meta_attributes(false) // omit *_ENCODING_OFFSET etc.
    .with_dispatch(false)        // omit AnyMessage/FrameCursor
    .with_domain_objects(DomainVarData::Bytes) // owned DTOs

A default single-message schema with these knobs off produces minimal output.

GenerationConfig::new enables display/debug, metadata, and dispatch, and disables domain objects, deprecated attributes, blanket enum options, and automatic bool mapping. GenerationProfile::Lean turns off the three output-heavy conveniences (display/debug, metadata, dispatch). See the canonical option table.

Real example

The sbe-feature-tour sample builds and exercises a real Car schema. Run cargo test inside that directory to see the generated API in action, or open src/generated/feature_tour.rs after cargo build.

Trust Boundaries

Checked entry points validate the message header and fixed block. verify walks the complete dynamic tail before bulk access:

#![allow(unused)]
fn main() {
pub fn demo_try_vs_trusted(valid_car: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
    // `decode` validates template_id, schema_id, version, and the
    // version-aware fixed body extent at message start (offset 0).
    let _dec = CarDecoder::try_decode(valid_car, 0)?;

    // `verify` walks the complete dynamic tail (groups + var-data), not a
    // header-only peek — use it when you need full structural acceptance
    // without materialising a long-lived decoder stage chain.
    CarDecoder::verify(valid_car)?;

    // Truncated buffers fail checked entry points with Result errors.
    assert!(
        CarDecoder::try_decode(&valid_car[..8.min(valid_car.len())], 0).is_err(),
        "truncated buffer should fail try_decode"
    );
    if valid_car.len() > 16 {
        assert!(
            CarDecoder::verify(&valid_car[..16]).is_err(),
            "truncated buffer should fail verify (incomplete tail)"
        );
    }

    // `wrap` still returns Result and validates the body extent given acting
    // block_length + version (message start, not sbe-tool body offset).
    let mut hdr_bytes = [0u8; 8];
    hdr_bytes.copy_from_slice(&valid_car[..8]);
    let hdr = MessageHeader(hdr_bytes);
    let dec = CarDecoder::try_wrap(valid_car, 0, hdr.block_length() as usize, hdr.version())?;
    assert_eq!(dec.serial_number(), 1234);
    Ok(())
}
}

(This code comes from the sbe-feature-tour sample crate.)

Three-tier constructors

Bare decode looks like try_decode (Result) but short buffers still panic — prefer try_decode when every failure must be a Result. Full table and the ladder from untrusted bytes to typed fields: Trust Boundary (core concepts). sbe-tool offsets: Coming from sbe-tool.

Trust boundary

The constructor is the single trust checkpoint. After a safe constructor proves header + version-aware fixed extent, field accessors and setters are branch-free (unchecked loads/stores justified by that proof). Dynamic group/var-data tails still check on consume. Use *_unchecked only when you have proven the fixed extent independently (benchmarks, pre-validated buffers).

Domain Objects (DTOs)

Latency-sensitive paths: never use DTOs. Domain objects allocate (Vec, String) and copy every field out of the wire buffer. If latency matters, use the zero-copy flyweight decoder instead. DTOs are for tooling, logging, and offline processing — not the hot path.

DTO construction still owns and allocates its Vec/String fields. Re-encode does not add another allocation: wire-compatible flat groups automatically use the generated bulk_add_domain(&[EntryDomain]) path, which validates one complete output region and writes directly from the DTO slice. Groups with nested tails, var-data, optional/versioned fields, domain conversions, or bool domain remapping retain the general per-entry path.

Enable domain objects during generation when an owned application value is more convenient than a zero-copy flyweight. This fixture uses DomainVarData::Strings:

#![allow(unused)]
fn main() {
pub fn demo_car_domain_dto(wire: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
    let dec = CarDecoder::try_decode(wire, 0)?;
    // try_from_decoder (not TryFrom/From): two fallible sources — decoder vs
    // try_from_slice_with_header for framed bytes; materialisation can fail.
    let dto = CarDomain::try_from_decoder(dec)?;
    assert_eq!(dto.serial_number, 1234);
    assert!(dto.available); // bool domain field
    assert_eq!(dto.fuel_figures.len(), 2);
    assert_eq!(dto.fuel_figures[0].usage_description, "Urban");
    assert_eq!(dto.manufacturer, "Honda");

    const RE_PAD: usize = 512;
    assert!(wire.len() <= RE_PAD);
    let mut storage = [0u8; RE_PAD];
    let n = dto.encode(&mut storage[..wire.len()])?;
    assert_eq!(&storage[..n], wire, "DTO re-encode must be byte-identical");
    Ok(())
}
}

(This code comes from the sbe-feature-tour sample crate.)

Multi-Template Dispatch

AnyMessage reads the generated header layout and dispatches on the template ID. Prefer AnyMessage::try_decode at untrusted boundaries (returns Result). Bare AnyMessage::decode is the same implementation today; keep using try_* naming for consistency with the three-tier trust boundary.

#![allow(unused)]
fn main() {
pub fn demo_any_message() -> Result<(), Box<dyn std::error::Error>> {
    let mut hb = [0u8; HeartbeatEncoder::compute_length_with_header()];
    let hb_len = HeartbeatEncoder::compute_length_with_header();
    let nanos: u64 = 1_700_000_000_000_000_000;
    let _hb_len = HeartbeatEncoder::try_wrap_and_apply_header(&mut hb, 0)
        .unwrap()
        .fixed(&HeartbeatFixedFields {
            sequence: 1,
            timestamp: nanos,
        })
        .encoded_length_with_header();

    let note_body = "hello AnyMessage";
    let note_len = NoteEncoder::compute_length_with_header(note_body.len());
    const NOTE_PAD: usize = 64;
    assert!(note_len <= NOTE_PAD);
    let mut note_storage = [0u8; NOTE_PAD];
    let note = &mut note_storage[..note_len];
    let note_written = NoteEncoder::try_wrap_and_apply_header(note, 0)?
        .fixed(&NoteFixedFields { note_id: 99 })
        .body_as_str(note_body)?
        .encoded_length_with_header();
    assert_eq!(note_written, note_len);

    // Concatenate framed messages (each includes its own SBE header).
    let mut stream = Vec::new();
    stream.extend_from_slice(&hb[..hb_len]);
    stream.extend_from_slice(&note[..note_written]);

    let mut offset = 0usize;
    let mut saw_heartbeat = false;
    let mut saw_note = false;
    while offset < stream.len() {
        match AnyMessage::try_decode(&stream, offset)? {
            AnyMessage::Heartbeat(d) => {
                assert_eq!(d.sequence(), 1);
                offset += d.encoded_length_with_header()?;
                saw_heartbeat = true;
            }
            AnyMessage::Note(d) => {
                assert_eq!(d.note_id(), 99);
                let (body, complete) = d.into_body_as_str()?;
                assert_eq!(body, note_body);
                offset += complete.encoded_length() + NoteDecoder::HEADER_LENGTH;
                saw_note = true;
            }
            AnyMessage::Car(_) => return Err("unexpected Car in this demo stream".into()),
            AnyMessage::Quote(_) => return Err("unexpected Quote in this demo stream".into()),
            AnyMessage::Unknown { .. } => {
                return Err("unexpected Unknown template".into());
            }
        }
    }
    assert!(saw_heartbeat && saw_note);
    Ok(())
}
}

(This code comes from the sbe-feature-tour sample crate.)

Core Concepts

• Trust Boundary — try_* → Result; wrap panics if short; decode is hybrid
• Wire Order via Named Stages — asks before bids is a type error
• Buffer Sizing — exact byte count before writing
• Flyweight vs Whole-Struct — in-place decode or owned DTO
• Composite Layout & Endianness — wire images, not repr(C) overlays

Trust Boundary

Every SBE buffer crossing a process boundary must be validated. ergo-sbe provides a three-tier constructor API with different failure contracts:

The ladder, from untrusted bytes to typed fields:

flowchart LR
    B["untrusted bytes"] --> W["wrap / decode"]
    W --> Z["private zero-check core"]
    Z --> G["typed getters / setters"]
    U["*_unchecked: skip the proof"] -.->|"UB on OOB, not the default"| W

try_* returns Result::Err; bare names panic after the same extent proof; decode is the hybrid above. *_unchecked is not shipped as a default path — only after an independent extent proof.

Wire layout follows official SBE offsets and order for the shapes under test (compatibility profile); official SBE wire compatibility outranks API convenience.

The trusted tier is safe Rust. Bare constructors run the same header + fixed-body extent proof as try_*, then panic on failure. After that proof, field accessors/setters use unchecked loads/stores (justified by the constructor). Dynamic tails still check on consume.

try_decode does not first traverse all dynamic tails. A staged walk validates them as it advances, so checked construction is compatible with a single-pass decoder. A separate verify() before that walk adds another structural pass. Checks for text encoding happen when text accessors are used.

The unsafe fn *_unchecked variants skip the extent proof entirely — only for the case where panic machinery is measurable and the caller has proven the layout independently.

Encoder entry points

Decoder entry points

Why decode returns Result but still panics

Bare decode keeps a freeze-friendly hybrid so feed handlers can ? on WrongTemplate / WrongSchema after demux, while short buffers remain a trusted-tier panic (same extent proof as wrap). Prefer try_decode when every failure — including short buffers — must be a Result.

See Trust boundaries (feature tour) for worked examples.

Wire Order via Named Stages

SBE is positional: groups and var-data appear in a fixed schema order with no per-field tags. Two nearly identical groups back-to-back — bids then asks — are common. Swap them and the bytes still look valid; prices land on the wrong side of the book. That mistake is a type error here, not a production incident.

sbe-tool uses .parent() to hand encoder ownership back up the tree. In Rust that fights the borrow checker. ergo-sbe uses scoped closures so nested schemas stay readable:

#![allow(unused)]
fn main() {
pub fn encode_sample_car(buf: &mut [u8]) -> Result<usize, sbe_rt::EncodeError> {
    let mut extras = OptionalExtras::default();
    extras.cruise_control(true).sports_pack(true);

    // Buffer pre-sized from EncodedLength; try_* still validates extent.
    let len = CarEncoder::try_wrap_and_apply_header(buf, 0)
        .unwrap()
        .fixed(&CarFixedFields {
            serial_number: 1234,
            model_year: 2013,
            available: true.into(),
            code: Model::A,
            some_numbers: [10, 20, 30, 40],
            vehicle_code: [b'A', b'B', b'C', b'D', b'E', b'F'],
            extras,
            engine: Engine::new(
                2000,
                4,
                [b'1', b'2', b'3'],
                0i8,
                false.into(),
                Booster::new(BoostType::TURBO, 210),
            ),
        })
        .fuel_figures(2, |g| {
            g.add(|mut e| {
                e.speed(30).mpg(35.9);
                e.usage_description_as_str("Urban")
            })?;
            g.add(|mut e| {
                e.speed(60).mpg(25.0);
                e.usage_description_as_str("Highway")
            })?;
            Ok(())
        })?
        .performance_figures(1, |g| {
            g.add(|mut e| {
                e.octane_rating(95);
                e.acceleration(2, |a| {
                    a.add(|x| {
                        x.mph(30).seconds(4.0);
                        Ok(())
                    })?;
                    a.add(|x| {
                        x.mph(60).seconds(7.5);
                        Ok(())
                    })
                })
            })?;
            Ok(())
        })?
        .manufacturer_as_str("Honda")?
        .model_as_str("Civic VTi")?
        .activation_code_as_str("abcdef")?
        .encoded_length_with_header();

    Ok(len)
}
}

(From sbe-feature-tour — compiles and runs in CI.)

Order is the type-state pattern, implemented as named concrete stage structs (CarAfterFuelFigures), not Encoder<State>. The H: HeaderState generic on every stage is a zero-sized marker for header-present vs body-only — it does not track wire-order. Duplicating the stage graph for HeaderPresent / HeaderAbsent would provide no latency advantage.

pub struct BookEncoder<'a> { /* buf, pos, … */ }
pub struct BookAfterBids<'a> { /* same layout */ }
pub struct BookAfterAsks<'a> { /* same layout */ }

impl BookEncoder<'a> {
    pub fn bids(self, …) -> Result<BookAfterBids<'a>, …> { … }
    // no asks() — bids first on the wire
}
impl BookAfterBids<'a> {
    pub fn asks(self, …) -> Result<BookAfterAsks<'a>, …> { … }
}

After fixed fields you may only call the next group or var-data. BookEncoder has no asks method. Decoders use the same idea (BookDecoder → BookDecoderAfterBids → …).

Group bodies use |g| { g.add(|e| { … }) }: the closure ends, then chaining continues. See Type-state and Benchmarks for the cost claim and the 1.00× gate.

Buffer Sizing

Aeron try_claim (and similar slots) needs the encoded size before you write. Guessing with vec![0u8; 4096] and copying later defeats that model.

Describe the shape (group counts, nested groups, var-data lengths) and get an exact size from the generated API:

#![allow(unused)]
fn main() {
pub fn demo_car_size_and_encode() -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    // Fuel: 2 entries with usage ASCII lengths 5 and 7.
    // Performance: 1 entry with 2 nested acceleration rows (fixed-only entries).
    // Message var-data: manufacturer / model / activationCode lengths.
    let complete_len = CarEncoder::compute_length()
        .fuel_figures_ragged(2, |ff| {
            ff.add()?.usage_description(5)?; // "Urban"
            ff.add()?.usage_description(7)?; // "Highway"
            Ok(())
        })?
        .performance_figures_ragged(1, |pf| {
            pf.add()?.acceleration(|acc| {
                acc.uniform(2)?;
                Ok(())
            })?;
            Ok(())
        })?
        .manufacturer(5)? // "Honda"
        .model(9)? // "Civic VTi"
        .activation_code(6)? // "abcdef"
        .encoded_length_with_header();

    // Exact size from compute_length → stack pad (this demo fits well under 512).
    const CAR_PAD: usize = 512;
    assert!(
        complete_len <= CAR_PAD,
        "sample car length {complete_len} exceeds stack pad {CAR_PAD}"
    );
    let mut storage = [0u8; CAR_PAD];
    let written = encode_sample_car(&mut storage[..complete_len])?;
    assert_eq!(
        written, complete_len,
        "CarEncodedLength must equal encoder-produced length"
    );
    Ok(storage[..written].to_vec())
}
/// Encode the canonical sample car into `buf` (must be pre-sized).
pub fn encode_sample_car(buf: &mut [u8]) -> Result<usize, sbe_rt::EncodeError> {
    let mut extras = OptionalExtras::default();
    extras.cruise_control(true).sports_pack(true);

    // Buffer pre-sized from EncodedLength; try_* still validates extent.
    let len = CarEncoder::try_wrap_and_apply_header(buf, 0)
        .unwrap()
        .fixed(&CarFixedFields {
            serial_number: 1234,
            model_year: 2013,
            available: true.into(),
            code: Model::A,
            some_numbers: [10, 20, 30, 40],
            vehicle_code: [b'A', b'B', b'C', b'D', b'E', b'F'],
            extras,
            engine: Engine::new(
                2000,
                4,
                [b'1', b'2', b'3'],
                0i8,
                false.into(),
                Booster::new(BoostType::TURBO, 210),
            ),
        })
        .fuel_figures(2, |g| {
            g.add(|mut e| {
                e.speed(30).mpg(35.9);
                e.usage_description_as_str("Urban")
            })?;
            g.add(|mut e| {
                e.speed(60).mpg(25.0);
                e.usage_description_as_str("Highway")
            })?;
            Ok(())
        })?
        .performance_figures(1, |g| {
            g.add(|mut e| {
                e.octane_rating(95);
                e.acceleration(2, |a| {
                    a.add(|x| {
                        x.mph(30).seconds(4.0);
                        Ok(())
                    })?;
                    a.add(|x| {
                        x.mph(60).seconds(7.5);
                        Ok(())
                    })
                })
            })?;
            Ok(())
        })?
        .manufacturer_as_str("Honda")?
        .model_as_str("Civic VTi")?
        .activation_code_as_str("abcdef")?
        .encoded_length_with_header();

    Ok(len)
}
}

(From sbe-feature-tour — EncodedLength + exact buffer encode, tested in CI.)

Nested books: book_encoded_length. API matrix: encoded_length_api_test.

Flyweight vs Whole-Struct

Use the style that matches how much of the message you touch.

Encode — whole fixed block as a struct

When you always populate every fixed field, a struct is clearer and schema additions break at compile time:

#![allow(unused)]
fn main() {
let mut buf = [0u8; HeartbeatEncoder::compute_length_with_header()];
// Buffer is exact size from const compute_length_with_header — no bounds check needed.
let len = HeartbeatEncoder::try_wrap_and_apply_header(&mut buf, 0)?
    .fixed(&HeartbeatFixedFields { sequence: 7, timestamp: 0 })
    .encoded_length_with_header();
let dec = HeartbeatDecoder::try_from(&buf[..len])?;
assert_eq!(dec.sequence(), 7);
}

(From book/examples/heartbeat-encode.rs — compiled against the feature-tour codec.)

If the schema later adds a required field to the fixed block, this stops compiling until you add it to the struct literal — you cannot silently omit it.

Decode — individual fields (flyweight)

#![allow(unused)]
fn main() {
// Encode a sample car first (normally bytes come from the wire)
let complete_len = CarEncoder::compute_length()
    .fuel_figures_ragged(0, |_| Ok(()))?
    .performance_figures_ragged(0, |_| Ok(()))?
    .manufacturer(5)?
    .model(5)?
    .activation_code(3)?
    .encoded_length_with_header();
const PAD: usize = 256;
assert!(complete_len <= PAD, "car length {complete_len} exceeds pad {PAD}");
let mut storage = [0u8; PAD];
let buf = &mut storage[..complete_len];
let fields = CarFixedFields {
    serial_number: 1234,
    model_year: 2013,
    available: true.into(),
    code: Model::A,
    some_numbers: [10, 20, 30, 40],
    vehicle_code: *b"ABCDEF",
    extras: OptionalExtras::default(),
    engine: Engine::new(2000, 4, *b"123", 0i8, false.into(), Booster::new(BoostType::TURBO, 210)),
};
let n = CarEncoder::try_wrap_and_apply_header(buf, 0)?
    .fixed(&fields)
    .fuel_figures(0, |_| Ok(()))?
    .performance_figures(0, |_| Ok(()))?
    .manufacturer_as_str("Honda")?
    .model_as_str("Civic")?
    .activation_code_as_str("abc")?
    .encoded_length_with_header();
assert_eq!(n, complete_len);
// Now decode — read only the fields you need, no DTO allocation:
let car = CarDecoder::try_from(&buf[..n])?;
assert_eq!(car.serial_number(), 1234);
assert_eq!(car.model_year(), 2013);
assert_eq!(car.code(), Model::A);
assert_eq!(car.engine().capacity(), 2000);
}

(From book/examples/flyweight-access.rs — compiled against the feature-tour codec.)

Decode — whole message as a DTO

Do not use on the latency-sensitive path. DTO decode allocates Vec/String and copies every field. For the hot path, use the flyweight decoder instead.

When you always need (almost) everything, or want to pass a value across threads / into non-SBE code:

#![allow(unused)]
fn main() {
pub fn demo_car_domain_dto(wire: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
    let dec = CarDecoder::try_decode(wire, 0)?;
    // try_from_decoder (not TryFrom/From): two fallible sources — decoder vs
    // try_from_slice_with_header for framed bytes; materialisation can fail.
    let dto = CarDomain::try_from_decoder(dec)?;
    assert_eq!(dto.serial_number, 1234);
    assert!(dto.available); // bool domain field
    assert_eq!(dto.fuel_figures.len(), 2);
    assert_eq!(dto.fuel_figures[0].usage_description, "Urban");
    assert_eq!(dto.manufacturer, "Honda");

    const RE_PAD: usize = 512;
    assert!(wire.len() <= RE_PAD);
    let mut storage = [0u8; RE_PAD];
    let n = dto.encode(&mut storage[..wire.len()])?;
    assert_eq!(&storage[..n], wire, "DTO re-encode must be byte-identical");
    Ok(())
}
}

Encode — your own type through a Source trait

*FixedFields covers the fixed block only. With .with_source_traits(true) each message gets a {Message}Source trait — one getter per field in wire order, impl ExactSizeIterator<Item = impl …EntrySource> per repeating group, &[u8] per var-data — and the encoder gains encode_from(&src) and encoded_length_with_header_from(&src). Implement the trait on the type your application already has; encode_from writes it through the same setters and type-state stages a hand-written encode uses, and returns the terminal stage:

#![allow(unused)]
fn main() {
/// The application's own type: no generated struct is involved.
struct Reminder {
    id: u32,
    text: String,
}

impl NoteSource for Reminder {
    fn note_id(&self) -> u32 {
        self.id
    }
    fn body(&self) -> &[u8] {
        self.text.as_bytes()
    }
}

let reminder = Reminder { id: 9, text: "settle T+1".into() };
let len = NoteEncoder::encoded_length_with_header_from(&reminder)?;
let mut scratch = vec![0u8; len];
let claim = sbe_rt::OfferClaim::new(&mut scratch, |_: &[u8]| -> Result<(), &'static str> { Ok(()) });
NoteEncoder::send(claim, |enc| enc.encode_from(&reminder))?;
}

(From book/examples/claim-send.rs — compiled against the feature-tour codec.)

A fixed getter returns what the field’s *FixedFields entry holds (Option<T> for an optional field, whose None writes the null value and whose Some of the null value, NaN for a float, is refused as SomeNullValue), or its domain type when one is configured. A group iterator whose len() does not match what it yields is GroupCountMismatch or GroupFull, as with a hand-written group.

Rule of thumb: one field on the hot path → flyweight. Always fill or always consume the whole message → FixedFields / Domain for clarity and compile-time breakage on schema growth. More on DTOs in Recipes — Domain DTOs.

Composite Layout & Endianness

On a little-endian host, can a composite be a #[repr(C)] / #[repr(C, packed)] overlay so field access is a free load?

Almost — but not via repr(C) transmute. ergo-sbe does something safer that is still a plain load on LE:

On LE hosts, from_le_bytes lowers to a load. The generator also emits

const _: () = assert!(core::mem::size_of::<Engine>() == 10);

so the Rust type size is locked to the wire size.

*FixedFields is an application struct used to fill the fixed block in one call. It is not a zero-copy overlay; .fixed(&…) writes each field with endian conversion.

Single-field access is already one load. layout_access_bench compares flyweight, preheld [u8; N], and #[repr(C, packed)] on a mid-block field: they measure equivalently. Materialising the whole composite first is the expensive path. zerocopy FromBytes/IntoBytes was evaluated and was not faster than the flyweight mov.

We do not generate packed field structs: packing, unaligned references, big-endian schemas, enums/sets/nested composites. The transparent wire image is the portable form that already optimizes to the packed load on LE.

On encode, encode_style_bench shows .fixed(&CarFixedFields{…}) and individual setters measure equivalently after inlining. Prefer .fixed for completeness, not speed. Building a BE image on an LE host costs a bswap per multi-byte field; once the image exists, write cost matches LE.

composite_layout_test · layout_access_bench · encode_style_bench. Read live Criterion output; do not quote numbers from this page.

Configuration

• Feature Integrations
• with_conversion vs with_domain_type
• GenerationConfig Options
• Code-Generation Hooks

Wire type vs app type

  app  ──price_from / price(v)──►  wire Decimal on the buffer
  buf  ──price_as / price()──►    app value

Feature Integrations

Optional Cargo features. Enable them on both [build-dependencies] and [dependencies] — the generator decides what to emit from its own feature set.

[build-dependencies]
ergo-sbe = { version = "0.1", features = ["compact_str", "chrono"] }

[dependencies]
ergo-sbe = { version = "0.1", features = ["compact_str", "chrono"] }

Measure with var_data_types_bench / chrono_converter_bench rather than quoting numbers from this page. DTO materialisation is never the hot path.

CompactString

Primarily for domain DTOs. Replaces String with compact_str::CompactString (≤24 bytes on the stack). The codec also gains into_<field>_as_compact_str() on text var-data stages.

use ergo_sbe::{DomainVarData, GenerationConfig};

let config = GenerationConfig::new("msgs")
    .with_domain_objects(DomainVarData::CompactStrings);

pub struct QuoteDomain {
    pub symbol: ergo_sbe::compact_str::CompactString,
    pub venue: ergo_sbe::compact_str::CompactString,
    pub price: Decimal,
}

let (symbol, _next_stage) = L3BookDecoder::try_decode(wire, 0)?
    .skip_bids()?
    .skip_asks()?
    .into_symbol_as_compact_str()?;

SmolStr

O(1) clone regardless of length. DomainVarData::SmolStrings plus into_<field>_as_smol_str().

let config = GenerationConfig::new("msgs")
    .with_domain_objects(DomainVarData::SmolStrings);

Bytes

Reference-counted buffer. DomainVarData::BytesCrate plus into_<field>_as_bytes().

let config = GenerationConfig::new("relay")
    .with_domain_objects(DomainVarData::BytesCrate);

let original = bytes::Bytes::copy_from_slice(b"payload");
let clone = original.clone();
let sub = original.slice(4..);

let (payload, next) = stage.into_payload_as_bytes()?;

Chrono

Schema fields are typically uint64 with a timestamp semanticType. The converters take i64. Map them with with_domain_type:

use ergo_sbe::{GenerationConfig, ConversionSelector};

let config = GenerationConfig::new("msgs")
    .with_domain_type(
        ConversionSelector::semantic_type("UTCTimestamp"),
        "chrono::DateTime<chrono::Utc>",
    )
    .with_domain_type(
        ConversionSelector::semantic_type("UTCTimestampMicros"),
        "chrono::NaiveDateTime",
    );

let created: chrono::DateTime<chrono::Utc> = dec.created_at()?;
let updated: chrono::NaiveDateTime = dec.updated_at()?;
enc.created_at(chrono::Utc::now())?;
enc.updated_at(chrono::DateTime::from_timestamp(1_720_000_000, 0).unwrap().naive_utc())?;

One semantic_type("UTCTimestamp") covers every field with that attribute. Worked example: Timestamps.

Direct converters (chrono feature):

use ergo_sbe::chrono_converters::*;

let dt = i64_nanos_to_datetime(1_720_000_000_000_000_000);
let ns = datetime_to_i64_nanos(dt);
let naive = i64_micros_to_naive(1_720_000_000_000_000);
assert_eq!(naive_to_i64_micros(naive), 1_720_000_000_000_000);

Combining

[build-dependencies]
ergo-sbe = { version = "0.1", features = ["compact_str", "bytes", "chrono"] }

[dependencies]
ergo-sbe = { version = "0.1", features = ["compact_str", "bytes", "chrono"] }

let config = GenerationConfig::new("msgs")
    .with_domain_objects(DomainVarData::CompactStrings)
    .with_domain_type(
        ConversionSelector::semantic_type("UTCTimestamp"),
        "chrono::DateTime<chrono::Utc>",
    );

with_conversion vs with_domain_type

Do not call both for the same selector — domain type already enables conversion.

Which fields a selector reaches, and what shape you get

A selector matches by precedence — exact FieldPath, then SemanticType, then NamedType — so a blanket mapping plus one per-field override behaves the way it reads, whatever order you register them in. Paths are "Message.field", extended with group names inside a group ("Order.legs.price").

What the accessor gives you depends on the field’s shape, because it mirrors the raw accessor it delegates to:

The Option layer means “no value on the wire” — absent at this version, or the schema null value. It is never used to report a bad value; an invalid wire value is the Err.

Composites, enums, and sets all take domain types. Fixed arrays and optional scalars keep their wire type in a domain DTO even when a selector matches them — the flyweight still gets the converted accessor, but the owned struct stores [u8; N] / Option<i64>.

Option A — you choose the app type (Cents)

#![allow(unused)]
fn main() {
    use ergo_sbe::{ConversionSelector, GenerationConfig};
    // A — generic converter: one wire type, many app types
    let _cfg =
        GenerationConfig::new("msgs").with_conversion(ConversionSelector::named_type("Decimal"));
}

(From book/examples/conversion-config.rs — a self-contained program that compiles against ergo-sbe.)

#![allow(unused)]
fn main() {
use rust_decimal::Decimal as Rd;
// App adapter: wire Decimal ↔ rust_decimal::Decimal
struct FixedPrice { mantissa: i64, exponent: i8 }

impl TryFromSbe<Decimal> for FixedPrice {
    type Error = &'static str;
    fn try_from_sbe(wire: Decimal) -> Result<Self, Self::Error> {
        Ok(FixedPrice {
            mantissa: wire.mantissa(),
            exponent: wire.exponent(),
        })
    }
}
impl TryToSbe<Decimal> for FixedPrice {
    type Error = &'static str;
    fn try_to_sbe(&self) -> Result<Decimal, Self::Error> {
        Ok(Decimal::new(self.mantissa, self.exponent))
    }
}
}

(From book/examples/conversion-app-code.rs — app adapter pattern, compiles against tour_codec.)

// Encode using the generic conversion API:
let mut buf = [0u8; QuoteEncoder::compute_length_with_header()];
let price = Rd::new(12345, 2); // 123.45
let len = QuoteEncoder::try_wrap_and_apply_header(&mut buf, 0)?
    .price_from(&price)?
    .size_from(&Rd::new(10, 0))?
    .encoded_length_with_header();
// Decode — generic `_as::<T>()` picks your adapter:
let dec = QuoteDecoder::try_from(&buf[..len])?;
let p: Rd = dec.price_as()?;
assert_eq!(p, Rd::new(12345, 2));
// Same buffer, different app type — only possible with with_conversion:
let fixed: FixedPrice = dec.price_as()?;
assert_eq!(fixed.mantissa, 12345);
assert_eq!(fixed.exponent, -2);

(Same file — generic _from/_as encode/decode with with_conversion.)

Option B — one fixed app type

#![allow(unused)]
fn main() {
    use ergo_sbe::{ConversionSelector, GenerationConfig};
    // B — concrete mapping: one Rust type per wire type (already enables conversion)
    let _cfg = GenerationConfig::new("msgs").with_domain_type(
        ConversionSelector::named_type("Decimal"),
        "rust_decimal::Decimal",
    );
}

(Same source file — book/examples/conversion-config.rs.)

// Encode using the generic conversion API:
let mut buf = [0u8; QuoteEncoder::compute_length_with_header()];
let price = Rd::new(12345, 2); // 123.45
let len = QuoteEncoder::try_wrap_and_apply_header(&mut buf, 0)?
    .price_from(&price)?
    .size_from(&Rd::new(10, 0))?
    .encoded_length_with_header();
// Decode — generic `_as::<T>()` picks your adapter:
let dec = QuoteDecoder::try_from(&buf[..len])?;
let p: Rd = dec.price_as()?;
assert_eq!(p, Rd::new(12345, 2));
// Same buffer, different app type — only possible with with_conversion:
let fixed: FixedPrice = dec.price_as()?;
assert_eq!(fixed.mantissa, 12345);
assert_eq!(fixed.exponent, -2);

Both styles on different fields:

pub fn demo_conversion_only() -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let mut buf = [0u8; QuoteEncoder::compute_length_with_header()];

    let price = Rd::new(12345, 2); // 123.45
    let size = Rd::new(10, 0);
    let mut enc = QuoteEncoder::try_wrap_and_apply_header(&mut buf, 0)?;
    enc.price_from(&price)?;
    enc.size_from(&size)?;
    let len = QuoteEncoder::compute_length_with_header();

    let dec = QuoteDecoder::try_from(&buf[..len])?;
    let wire = dec.price_value();
    assert_eq!(wire.mantissa(), 12345);
    assert_eq!(wire.exponent(), -2);

    let price2: Rd = dec.price_as()?;
    let size2: Rd = dec.size_as()?;
    assert_eq!(price2, price);
    assert_eq!(size2, size);

    // Same buffer, different app type — only possible with with_conversion.
    let fixed: FixedPrice = dec.price_as()?;
    assert_eq!(
        fixed,
        FixedPrice {
            mantissa: 12345,
            exponent: -2
        }
    );

    let dto = QuoteDomain::try_from_decoder(dec)?;
    assert_eq!(dto.price.mantissa(), 12345);
    let mut re = [0u8; QuoteEncoder::compute_length_with_header()];
    let n = dto.encode(&mut re)?;
    assert_eq!(&re[..n], &buf[..len]);
    Ok(buf[..len].to_vec())
}

(This code comes from the sbe-feature-tour sample crate.)

Option B, manual impl — concrete signatures, your own conversion logic

with_domain_type(selector, path) is the common case: ergo-sbe also generates the TryFromSbe/TryToSbe impl for bool / rust_decimal::Decimal / chrono::DateTime<Utc>. If you need different conversion behaviour for one of those exact three types — a custom rounding rule, stricter validation, different null handling — call additive with_manual_domain_type instead: same generated price(...)? / price()? signatures, but you write the impl:

    let (_schema, src) = generate_domain_with(&path, "manual_impl_dt", |c| {
        c.with_manual_domain_type(
            ergo_sbe::ConversionSelector::named_type("Decimal"),
            "rust_decimal::Decimal",
        )
    });

        use rust_decimal::Decimal;

        // Caller-supplied impl: deliberately scales mantissa by 10 on the way
        // in/out, so a value only round-trips correctly through THIS impl —
        // proof ergo-sbe didn't quietly generate its own.
        impl TryFromSbe<self::Decimal> for rust_decimal::Decimal {
            type Error = &'static str;
            fn try_from_sbe(wire: self::Decimal) -> Result<Self, Self::Error> {
                Ok(rust_decimal::Decimal::new(wire.mantissa() / 10, (-wire.exponent()) as u32))
            }
        }
        impl TryToSbe<self::Decimal> for rust_decimal::Decimal {
            type Error = &'static str;
            fn try_to_sbe(&self) -> Result<self::Decimal, Self::Error> {
                Ok(self::Decimal::new(self.mantissa() as i64 * 10, -(self.scale() as i8)))
            }
        }

        let mut buf = [0u8; 256];
        let mut enc = OrderEncoder::wrap_and_apply_header(&mut buf, 0)
            .fixed(&OrderFixedFields { price: self::Decimal::new(0, 0), size: self::Decimal::new(0, 0) });
        enc.price(Decimal::new(12345, 2))?;
        enc.size(Decimal::new(100, 0))?;
        let encoded = enc.as_bytes_with_header().to_vec();

        let dec = OrderDecoder::try_decode(&encoded, 0)?;
        assert_eq!(dec.price()?, Decimal::new(12345, 2));
        assert_eq!(dec.size()?, Decimal::new(100, 0));

(From domain_type_manual_impl_uses_callers_own_impl in sbe/tests/baseline_test.rs — a real generated-and-compiled test. Any rust_type string that isn’t one of the three built-ins never gets an auto-generated impl regardless of DomainImpl — it only matters for opting those three in or out.)

Forgot the impl? Two things soften it. First, the compile error names the missing impl directly instead of the default trait-bound message:

error[E0277]: `rust_decimal::Decimal` has no `TryFromSbe<Decimal>` impl
  |
  | missing `impl TryFromSbe<Decimal> for rust_decimal::Decimal`
  |
  = note: if this field uses DomainImpl::Manual, the generated domain
          accessor's doc comment has a ready-to-paste starting point

Second, for the three built-ins, that pointer is real: the generated price method’s own doc comment (visible on hover, or in cargo doc) carries the exact impl DomainImpl::Generated would have written — copy it out and adjust. sbe/tests/baseline_test.rs’s domain_type_manual_impl_doc_comment_has_generated_snippet asserts this snippet is present in the generated source.

What your domain type must implement

Only Debug. The generated Display/Debug bodies format domain values with {:?}, so a plain #[derive(Debug)] struct works — Display is never required. Note that TryFromSbe::Error / TryToSbe::Error is a separate associated type and does need Debug + Display; &'static str satisfies it.

Option C — generated mappings for enums and composites

When the application type mirrors the SBE type — an enum with the same variants, a struct with the same members — with_enum_mapping and with_composite_mapping generate the TryFromSbe / TryToSbe impls (exhaustive, with renames) and register the domain type in one call. The accessors look exactly like Option B’s. See App Types on Composites.

GenerationConfig Options

Every option except new("module_name") is a chained builder method. Boolean flags default to the value shown.

Turn off with_display_debug, with_meta_attributes, and with_dispatch to shrink generated code. Text fields stay bytes unless the schema declares a character encoding (then strict UTF-8/ASCII helpers apply).

Decoder lanes (no configuration needed)

Memoization is a runtime lane, not a generation knob. with_memoized_tail_offsets / with_compact_tail_offsets are gone.

let decoder = CarDecoder::try_from(bytes)?;  // small, Sync, recalculates tails
let decoder = decoder.memoized();            // lazy cache, no allocation

Build it once and share & references. The base decoder is Sync; the memoized one is Send but not Sync. Compact u32 tail-offset storage was tried and removed; the deciding measurement was not archived. Lanes: Decoder Lanes.

Typed error conversions

GenerationConfig::with_error_from_impls is deprecated and scheduled for removal in 1.0. It formats through String, so needed/available are lost. Prefer a typed From on the generated sbe_rt types:

#![allow(unused)]
fn main() {
enum AppError {
    Encode(sbe_rt::EncodeError),
    Decode(sbe_rt::DecodeError),
}

impl From<sbe_rt::EncodeError> for AppError {
    fn from(error: sbe_rt::EncodeError) -> Self {
        match error {
            sbe_rt::EncodeError::BufferTooShort {
                field,
                needed,
                available,
            } => {
                let _ = (field, needed, available);
                Self::Encode(error)
            }
            other => Self::Encode(other),
        }
    }
}

impl From<sbe_rt::DecodeError> for AppError {
    fn from(error: sbe_rt::DecodeError) -> Self {
        Self::Decode(error)
    }
}
}

Code-Generation Hooks

Niche feature. Hooks are aimed at users who need to attach extra impl blocks to generated code — serde, custom validation, company-internal traits. Most workflows don’t need them; skip this section unless you recognise your use case.

Hooks append tokens after each generated item; they cannot add a #[derive(...)] to the item itself (that attribute would have to precede the struct/enum). Emit the trait impl directly instead — that is what a derive would expand to anyway.

Hooks let you append arbitrary Rust tokens after each generated item (enum, set, composite, message decoder/encoder, domain struct). The closure receives an ItemContext with structured field/variant/choice metadata, plus a schema reference for full IR access.

Example — add serde Serialize + Deserialize to every enum and set:

// build.rs
use ergo_sbe::{GenerationConfig, ItemContext};
use quote::quote;

fn serde_hook(ctx: &ItemContext) -> Vec<proc_macro2::TokenStream> {
    match ctx {
        ItemContext::Enum { name, variants, .. } => {
            let ident = quote::format_ident!("{name}");
            let labels: Vec<_> = variants.iter().map(|v| v.label.clone()).collect();
            let names: Vec<_> = variants.iter().map(|v| quote::format_ident!("{}", v.name)).collect();
            let from_labels: Vec<_> = variants.iter().map(|v| quote::format_ident!("{}", v.name)).collect();
            vec![quote::quote! {
                impl serde::Serialize for #ident {
                    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
                        s.serialize_str(match self {
                            #(Self::#names => #labels,)*
                            _ => "NullVal",
                        })
                    }
                }
                impl<'de> serde::Deserialize<'de> for #ident {
                    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
                        let s = <&str>::deserialize(d)?;
                        match s {
                            #(#labels => Ok(Self::#from_labels),)*
                            "NullVal" => Ok(Self::NullVal),
                            // Reject unknown values — fallback is app policy,
                            // not codec behaviour.
                            other => Err(serde::de::Error::unknown_variant(
                                other, &[#(#labels,)* "NullVal"])),
                        }
                    }
                }
            }]
        }
        ItemContext::Set { name, choices, .. } => {
            let ident = quote::format_ident!("{name}");
            let is: Vec<_> = choices.iter().map(|c| quote::format_ident!("is_{}", c.snake_name)).collect();
            let labels: Vec<_> = choices.iter().map(|c| c.label.clone()).collect();
            let froms: Vec<_> = choices.iter().map(|c| quote::format_ident!("{}", c.snake_name)).collect();
            vec![quote::quote! {
                impl serde::Serialize for #ident {
                    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
                        let mut names = Vec::new();
                        #(if self.#is() { names.push(#labels); })*
                        names.serialize(s)
                    }
                }
                impl<'de> serde::Deserialize<'de> for #ident {
                    fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
                        let names: Vec<&str> = <Vec<&str>>::deserialize(d)?;
                        let mut val = Self::default();
                        for n in &names {
                            match *n {
                                #(#labels => { val.#froms(true); })*
                                // Reject unknown labels — don't silently drop.
                                other => return Err(serde::de::Error::unknown_variant(
                                    other, &[#(#labels),*])),
                            }
                        }
                        Ok(val)
                    }
                }
            }]
        }
        _ => vec![],
    }
}

let config = GenerationConfig::new("msgs").with_hook(serde_hook);

Each ItemContext variant carries the fields, variants, or choices defined in the schema — use them to build custom impl blocks or trait implementations. Hooks fire in registration order; the returned tokens are appended after the generated item (so they extend it with impls, not with derives).

Full runnable example with serde + serde_json round-trip: hook_serde_test.

Recipes

Runnable code: sbe-feature-tour src/lib.rs.

• Aeron try_claim
• Display / Debug
• Schema Descriptions → Rustdoc
• Domain DTOs
• App Types on Composites
• Timestamp Conversions

Quick reference

Known vs unknown group count:

#![allow(unused)]
fn main() {
pub fn encode_sample_car(buf: &mut [u8]) -> Result<usize, sbe_rt::EncodeError> {
    let mut extras = OptionalExtras::default();
    extras.cruise_control(true).sports_pack(true);

    // Buffer pre-sized from EncodedLength; try_* still validates extent.
    let len = CarEncoder::try_wrap_and_apply_header(buf, 0)
        .unwrap()
        .fixed(&CarFixedFields {
            serial_number: 1234,
            model_year: 2013,
            available: true.into(),
            code: Model::A,
            some_numbers: [10, 20, 30, 40],
            vehicle_code: [b'A', b'B', b'C', b'D', b'E', b'F'],
            extras,
            engine: Engine::new(
                2000,
                4,
                [b'1', b'2', b'3'],
                0i8,
                false.into(),
                Booster::new(BoostType::TURBO, 210),
            ),
        })
        .fuel_figures(2, |g| {
            g.add(|mut e| {
                e.speed(30).mpg(35.9);
                e.usage_description_as_str("Urban")
            })?;
            g.add(|mut e| {
                e.speed(60).mpg(25.0);
                e.usage_description_as_str("Highway")
            })?;
            Ok(())
        })?
        .performance_figures(1, |g| {
            g.add(|mut e| {
                e.octane_rating(95);
                e.acceleration(2, |a| {
                    a.add(|x| {
                        x.mph(30).seconds(4.0);
                        Ok(())
                    })?;
                    a.add(|x| {
                        x.mph(60).seconds(7.5);
                        Ok(())
                    })
                })
            })?;
            Ok(())
        })?
        .manufacturer_as_str("Honda")?
        .model_as_str("Civic VTi")?
        .activation_code_as_str("abcdef")?
        .encoded_length_with_header();

    Ok(len)
}
}

(From sbe-feature-tour — known-count groups with chaining, tested in CI.)

Unknown size: count back-patched after the closure (streaming producers).

let unknown_len = CarEncoder::wrap_and_apply_header(&mut buf, 0)
    .fixed(&fields)
    .fuel_figures_unknown_size(|g| {
        for row in rows {
            g.add(|mut e| {
                e.speed(row.speed).mpg(row.mpg);
                e.usage_description_as_str(&row.usage)
            })?;
        }
        Ok(())
    })?
    .performance_figures(0, |_| Ok(()))?
    .manufacturer_as_str("Honda")?
    .model_as_str("Civic")?
    .activation_code_as_str("active")?
    .encoded_length_with_header();

println!("known={known_len} unknown={unknown_len}");

Aeron try_claim Integration

ergo-sbe’s exact sizing is built for encoding straight into a claimed region: size the frame, claim exactly that many bytes, encode into the claim, commit. No scratch buffer, no copy. The generated send and send_fixed do the last three steps and check the result, so a frame that does not fill its claim is a typed error and the claim is aborted, never a corrupt publication.

The Claim trait

Every generated module’s sbe_rt declares Claim, a region a transport reserved for one frame. ergo-sbe has no Aeron dependency, so you implement it once for your transport. In the crate that generates the codec the trait is local, so rusteron’s claim type can implement it directly (from another crate, where both are foreign, wrap the claim in a newtype):

use rusteron_client::{AeronCError, AeronClaim};

impl messages::sbe_rt::Claim for AeronClaim {
    type Error = AeronCError;
    fn frame_mut(&mut self) -> &mut [u8] {
        self.data()
    }
    fn commit(self) -> Result<(), AeronCError> {
        AeronClaim::commit(self).map(drop)
    }
    fn abort(self) {
        let _ = AeronClaim::abort(self);
    }
}

send calls abort whenever it publishes nothing — an encoder error, a length or header mismatch, and while unwinding from a panic in your closure — so the term-buffer slot is released at once rather than after Aeron’s unblock timeout.

No encoder writes a block’s padding (the bytes past its last field, up to the schema’s blockLength), so they go out as the claimed region held them. An Aeron try_claim region starts zeroed by the transport; the cost of that zeroing is not measured here. A Claim you implement over a region the transport reuses must hand it out zeroed, as OfferClaim (below) does.

Fixed-only messages: send_fixed

let claim = publication.try_claim_owned(HeartbeatEncoder::ENCODED_LENGTH)?;
HeartbeatEncoder::send_fixed(claim, &HeartbeatFixedFields { sequence: 7, timestamp: 0 })?;

A claim of any other size is SendError::LengthMismatch, and nothing is written into it.

Messages with groups and var-data: send

Size the frame with the encoder’s compute_length* helpers (or the staged EncodedLength builder for nested groups), claim that length, and hand send a closure that writes the message. The closure receives the encoder already wrapped on the claim, header written, and must return the message’s terminal stage — so a frame with tails still to write does not compile:

let len = NoteEncoder::compute_length_with_header(body.len());
NoteEncoder::send(publication.try_claim_owned(len)?, |enc| {
    enc.fixed(&NoteFixedFields { note_id: 1 }).body(body)
})?;

send checks that the frame is exactly the claim’s length (a claim sized for a different frame would otherwise publish stale bytes or a truncated message) and that it starts with the message’s own header. Each failure has its own SendError variant: Encode for the encoder’s error, LengthMismatch, HeaderMismatch, and Commit for the transport refusing the frame — the only case where the claim was not aborted, because the transport already had it.

Offer-style transports: OfferClaim

A transport that copies a finished frame, like Aeron’s offer, uses sbe_rt::OfferClaim over a scratch buffer: the frame is encoded into the buffer, and committing hands it to the closure. The same send and send_fixed work unchanged, with the same checks. OfferClaim::new zeroes the buffer, so a scratch buffer reused for every frame never puts the previous frame’s bytes in the next one’s padding:

#![allow(unused)]
fn main() {
// Offer style: encode into `scratch`; commit hands the frame to the transport.
let mut scratch = [0u8; HeartbeatEncoder::ENCODED_LENGTH];
let mut published: Vec<Vec<u8>> = Vec::new();
let claim = sbe_rt::OfferClaim::new(&mut scratch, |frame: &[u8]| -> Result<(), &'static str> {
    published.push(frame.to_vec()); // publication.offer(frame).map(drop)
    Ok(())
});
HeartbeatEncoder::send_fixed(claim, &HeartbeatFixedFields { sequence: 7, timestamp: 0 })?;
assert_eq!(published.len(), 1);
}

#![allow(unused)]
fn main() {
let body = b"rebalance at close";
let len = NoteEncoder::compute_length_with_header(body.len());
let mut scratch = vec![0u8; len];
let claim = sbe_rt::OfferClaim::new(&mut scratch, |frame: &[u8]| -> Result<(), &'static str> {
    assert_eq!(frame.len(), len);
    Ok(())
});
// The closure gets the encoder wrapped on the claim and must return the
// finished frame: the type-state makes a half-written one a compile error.
NoteEncoder::send(claim, |enc| enc.fixed(&NoteFixedFields { note_id: 1 }).body(body))?;
}

#![allow(unused)]
fn main() {
// A claim one byte too long: nothing is offered, and the error says why.
let body = b"rebalance at close";
let len = NoteEncoder::compute_length_with_header(body.len());
let mut too_long = vec![0u8; len + 1];
let claim = sbe_rt::OfferClaim::new(&mut too_long, |_: &[u8]| -> Result<(), &'static str> {
    unreachable!("an aborted claim is never offered")
});
let sent = NoteEncoder::send(claim, |enc| enc.fixed(&NoteFixedFields { note_id: 1 }).body(body));
assert_eq!(
    sent,
    Err(sbe_rt::SendError::LengthMismatch { claimed: len + 1, frame: len })
);
}

(From book/examples/claim-send.rs — compiled against the feature-tour codec.)

Encoding an application type

With with_source_traits, the encoder can write any type that implements the message’s generated …Source trait, sizing it first with encoded_length_with_header_from. encode_from returns the terminal stage, so it is the whole send closure:

#![allow(unused)]
fn main() {
/// The application's own type: no generated struct is involved.
struct Reminder {
    id: u32,
    text: String,
}

impl NoteSource for Reminder {
    fn note_id(&self) -> u32 {
        self.id
    }
    fn body(&self) -> &[u8] {
        self.text.as_bytes()
    }
}

let reminder = Reminder { id: 9, text: "settle T+1".into() };
let len = NoteEncoder::encoded_length_with_header_from(&reminder)?;
let mut scratch = vec![0u8; len];
let claim = sbe_rt::OfferClaim::new(&mut scratch, |_: &[u8]| -> Result<(), &'static str> { Ok(()) });
NoteEncoder::send(claim, |enc| enc.encode_from(&reminder))?;
}

encode_from refuses what would not read back: Some of an optional field’s null value (NaN for a float) is EncodeError::SomeNullValue, and a value a domain conversion refuses is EncodeError::Conversion, each with the field’s path and entry indices (fills[1].allocs[0].px). In a hand-written closure, the setter of a field under with_enum_mapping or with_composite_mapping returns sbe_rt::MappingError, which converts into EncodeError, so enc.side(side)? works there too.

A frame written some other way: send_frame

sbe_rt::send_frame(claim, header, encode) is what send is built on: it runs a closure that writes raw bytes into the claim and returns the frame’s length, then applies the same length and header checks before committing. Pass the message’s HEADER_TEMPLATE as header. Use it when the frame is not written through one generated encoder, for example a bus that encodes whichever message a caller hands it, and for a message whose own field, or first group or var-data, is named send (or send_fixed): that accessor is a method on the encoder too, so it keeps its name and the message has no helper of that name.

Cluster clients

Cluster clients do not claim from the publication directly: use AeronCluster::try_claim, which claims SessionMessageHeader + payload and hands back the payload region via ClusterClaim::payload_mut().

The cluster-ha-orderbook sample demonstrates the claim pattern in the context of a real Aeron Cluster publication loop.

Display / Debug

Diagnostic only — not a stable wire or log schema. Do not treat either format as a protocol or long-term log contract.

Display currently equals Debug for generated decoders ({car} and {car:?} print the same text). Prefer Debug in logs if you want that intent to stay obvious when/if the two diverge later.

#![allow(unused)]
fn main() {
pub fn demo_display_debug(valid_car: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
    let car = CarDecoder::try_from(valid_car)?;
    let display = format!("{car}");
    let debug = format!("{car:#?}");

    // Display is a compact one-liner; field names use the schema's camelCase.
    assert!(display.contains("serialNumber: 1234"));
    assert!(display.contains("modelYear: 2013"));
    assert!(display.contains("available: true"));
    assert!(display.contains(r#"code: A"#));
    assert!(display.contains("manufacturer: \"Honda\""));
    assert!(display.contains("model: \"Civic VTi\""));
    assert!(display.contains("fuelFigures: ["));
    assert!(display.contains("performanceFigures: ["));
    assert!(display.contains(r#"activationCode: "abcdef""#));

    // Pretty Debug ({:#?}) shows each field on its own line with indentation.
    for expected in &[
        "serialNumber: 1234",
        "modelYear: 2013",
        "available: true",
        r#"manufacturer: "Honda""#,
        r#"model: "Civic VTi""#,
        r#"activationCode: "abcdef""#,
        r#"usageDescription: Urban"#,
        "speed: 30",
        "mpg: 35.9",
        "octaneRating: 95",
    ] {
        assert!(
            debug.contains(expected),
            "Debug missing: {expected}\n--- full debug ---\n{debug}"
        );
    }

    // ── CarDomain DTO ───────────────────────────────────────────────────
    // Owned, heap-allocated, serialisable snapshot of the full message tree.
    // Generated by `with_domain_objects(DomainVarData::Strings)`.
    let dto = CarDomain::try_from_decoder(car)?;
    let dto_dbg = format!("{dto:#?}");
    // DTO field names use Rust snake_case (different from wire decoder camelCase).
    assert!(dto_dbg.contains("serial_number: 1234"));
    assert!(dto_dbg.contains("model_year: 2013"));
    assert!(dto_dbg.contains("available: true"));
    assert!(dto_dbg.contains("fuel_figures: ["));
    assert!(dto_dbg.contains(r#"usage_description: "Urban""#));
    assert!(dto_dbg.contains(r#"manufacturer: "Honda""#));
    assert!(dto_dbg.contains(r#"activation_code: "abcdef""#));

    Ok(())
}
}

(This code comes from the sbe-feature-tour sample crate.)

Real output from the feature-tour Car (demo_car_size_and_encode → CarDecoder):

CarDecoder { serialNumber: 1234, modelYear: 2013, available: true, code: A, fuelFigures: ["{ speed: 30, mpg: 35.9, usageDescription: Urban }", "{ speed: 60, mpg: 25.0, usageDescription: Highway }"], performanceFigures: ["{ octaneRating: 95, acceleration: [{ mph: 30, seconds: 4.0 }, { mph: 60, seconds: 7.5 }] }"], manufacturer: "Honda", model: "Civic VTi", activationCode: "abcdef" }

Truncated / incomplete buffers omit missing tails rather than panicking.

Schema Descriptions → Rustdoc

<field name="serialNumber" id="1" type="uint64" description="VIN-style serial"/>

// Generated (approx):
/// VIN-style serial
pub fn serial_number(&self) -> u64 { … }

Provenance of all four XML doc sources: schema_docs_provenance_test.

Domain DTOs

Use when you want owned values (Vec groups, owned tails) and simple structs — not the zero-copy hot path. DTOs allocate on decode; the flyweight path does not. A DTO-vs-flyweight latency A/B was not measured.

For re-encode, eligible flat groups are bulk-written directly from &[EntryDomain]: no temporary Vec<Entry> and no encode-time allocation. Eligibility requires fixed-size entries whose domain fields have the same wire representation; nested groups, var-data, optional/versioned fields, configured domain conversions, and bool remapping use the general add path. Integer min/max checks are preserved in both paths. with_all_enums_as_option() / with_null_as_option maps a required enum to Option<Enum> on the DTO: None writes the schema NullVal image (including on a reused buffer), and bulk_add_domain / to_wire_entry use that same mapping.

DTO re-encode of eligible flat groups is a DTO-to-DTO diagnostic (group_encode_bench), not an ergon/sbe-tool ratio. Read a fresh run; do not quote numbers from this page.

#![allow(unused)]
fn main() {
// build.rs — DomainVarData picks the DTO field type for var-data:
// .with_domain_objects(DomainVarData::Strings) // String (invalid UTF-8 → InvalidUtf8 error)
// .with_domain_objects(DomainVarData::Bytes)        // Vec<u8> (byte-exact)
}

Generated shape (illustrative — your names follow your schema):

pub struct QuoteDomain {
    pub seq: u32,
    pub some_numbers: [u32; 4],
    pub vehicle_code: [u8; 6],
    pub qty: u32,
    pub legs: Vec<QuoteLegsEntryDomain>,
    pub note: Vec<u8>,              // Bytes|String per DomainVarData
}
impl QuoteDomain {
    // Named methods, not TryFrom/From: two fallible sources (decoder vs framed
    // slice+offset), and materialisation is never infallible.
    pub fn try_from_decoder(dec: QuoteDecoder<'_>) -> Result<Self, DecodeError>;
    pub fn try_from_slice_with_header(buf: &[u8], offset: usize) -> Result<Self, DecodeError>;
    pub fn encode(&self, buf: &mut [u8]) -> Result<usize, EncodeError>;
    pub fn encoded_length_with_header(&self) -> Result<usize, EncodeError>;
}

Wire → DTO → wire round-trip (the docs fixture uses DomainVarData::Bytes):

#![allow(unused)]
fn main() {
  // Encode a message first (the usual flyweight path)
  let mut buf = [0u8; QuoteEncoder::compute_length_with_header(1, 2)];
  let len = QuoteEncoder::wrap_and_apply_header(&mut buf, 0)
      .fixed(&QuoteFixedFields {
          seq: 1,
          some_numbers: [1, 2, 3, 4],
          vehicle_code: *b"ABCDEF",
          qty: 10,
      })
      .legs(1, |legs| {
          legs.add(|leg| { leg.value(99); Ok(()) })?;
          Ok(())
      })?
      .note_as_str("hi")?
      .encoded_length_with_header();
  // Decode → owned DTO (allocates — not for the hot path)
  let dec = QuoteDecoder::try_from(&buf[..len])?;
  let mut dto = QuoteDomain::try_from_decoder(dec)?;
  assert_eq!(dto.seq, 1);
  assert_eq!(&dto.note, b"hi");
  dto.qty = 500;
  // Re-encode (integer min/max checked; eligible groups use bulk write)
  let n = dto.encode(&mut buf)?;
  assert_eq!(n, len);
}

with_domain_objects(DomainVarData)

SBE <data> is length-prefixed bytes. The enum picks the DTO field type:

Strings rejects invalid UTF-8. Materialise returns InvalidUtf8 for bad bytes; there is no silent empty-string fallback. Use Bytes (or stay on flyweights) when you need audit / replay fidelity of non-UTF-8 tails.

Runnable demo (text path): sbe-feature-tour uses DomainVarData::Strings. Flyweight path is unchanged: with schema characterEncoding="UTF-8" you still get into_manufacturer_as_str() without a DTO.

demo_car_domain_dto · domain_objects_test.

App Types on Composites

SBE composite types like Decimal { mantissa, exponent } have a fixed wire layout. Mapping them to Rust domain types is done at configuration time — no hand-rolled per-field converters needed.

Option A — generic converter (with_conversion): the generated codec emits price_from<T: TryToSbe<Decimal>>() and price_as<T: TryFromSbe<Decimal>>(). You implement the trait for any app type. One wire type, many app types.

Option B — concrete mapping (with_domain_type): the generated codec emits price(rust_decimal::Decimal)? and price()? -> rust_decimal::Decimal. Exactly one Rust type per wire type. The trait impls are generated for you.

Option C — generated mapping (with_enum_mapping, with_composite_mapping): for an enum or composite whose application counterpart has the same shape, ergo-sbe writes the TryFromSbe / TryToSbe impls too. See below.

Full comparison with code examples: with_conversion vs with_domain_type.

Generated mappings

An application enum that mirrors an SBE enum, and a struct that mirrors a composite, need no hand-written conversion:

    GenerationConfig::new(module)
        .with_enum_mapping(
            EnumMapping::new("Side", "app::Side")
                .rename("Buy", "Bid")
                .rename("Sell", "Ask"),
        )
        .with_composite_mapping(CompositeMapping::new("Price", "app::Px"))
        .with_composite_mapping(CompositeMapping::new("Leg", "app::Leg").rename("qty", "quantity"))

pub mod app {
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub enum Side { Bid, Ask, SellShort }

    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct Px { pub mantissa: i64, pub exponent: i8 }

    #[derive(Debug, Clone, Copy, PartialEq)]
    pub struct Leg {
        pub price: Px,
        pub side: Side,
        pub quantity: u32,
        pub min_qty: Option<u32>,
        pub ratio: Option<f64>,
        pub flags: super::Flags,
        pub venue: [u8; 4],
    }
}

(From sbe/tests/type_mapping_test.rs, which generates, compiles and runs these against the plain codec.)

Each mapping also acts as a with_domain_type for its type, so every field of that type takes the application type: dec.side()? -> app::Side, enc.leg(leg)?, and the application type in a domain DTO (a DTO field of an enum named BooleanType, or with semanticType="Boolean", stays bool, as under with_domain_type). A presence="constant" field of a mapped enum has the same domain getter beside its *_wire getter, and no setter. The wire bytes are the ones the plain codec writes.

A mapped setter’s error is sbe_rt::MappingError, which converts into sbe_rt::EncodeError, so enc.leg(leg)? works inside an encode or send closure. A domain DTO’s encode and encode_from report the same refusal as EncodeError::Conversion, with the field’s path and the index of its entry in each group on the way (fills[1].leg) and the MappingError itself.

Enum (EnumMapping). A schema variant maps to the application variant of the same generated name (sellShort → SellShort) unless renamed. Both impls are exhaustive matches, so an application enum that lacks a schema variant, or has one the schema lacks, does not compile.

Composite (CompositeMapping). TryFromSbe is a struct literal built from the composite’s getters, TryToSbe calls the composite’s new; a member fills the field of the same snake-case name unless renamed. Constant members have no field (they are not on the wire). An optional scalar member is an Option field: None writes the member’s null value, and Some of the null value — which would read back as None — is refused. A member whose enum or composite has its own generated mapping uses that mapping’s application type (price: app::Px, side: app::Side above); every other member keeps its generated wire type. A struct missing a member’s field, or with a field no member fills, does not compile.

NullVal and unknown values

NullVal has no application value, so decoding it is an explicit sbe_rt::MappingError::NullEnum, never a default variant. The generated decoder folds every discriminant the schema does not declare into NullVal before the mapping sees it, so an unknown value is the same error: the mapping cannot tell it from the schema null, and only the decoder’s raw_<field>() still reads the wire byte. With with_null_as_option on the enum, both read as Ok(None) instead:

        let side_at = dm::OrderEncoder::HEADER_LENGTH + 8;
        assert_eq!(buf[side_at], 5, "sellShort's discriminant");
        for raw in [0u8, 9] {
            // 0 is NullVal; 9 is undeclared and folds into NullVal on decode.
            buf[side_at] = raw;
            let dec = dm::OrderDecoder::decode(&buf, 0)?;
            assert_eq!(dec.side_wire(), dm::Side::NullVal);
            assert_eq!(dec.side(), Err(dm::sbe_rt::MappingError::NullEnum { enum_name: "Side" }));
            assert!(dm::OrderDomain::try_from_slice_with_header(&buf[..len], 0).is_err());

            // with_null_as_option: absent instead of an error — for the
            // undeclared 9 too, the folding limitation.
            let dec = dmo::OrderDecoder::decode(&buf, 0)?;
            assert_eq!(dec.side(), Ok(None));
        }
        buf[side_at] = 2;
        assert_eq!(dmo::OrderDecoder::decode(&buf, 0)?.side(), Ok(Some(dmo::app::Side::Ask)));

On a presence="optional" field, NullVal is not an error but the field being absent, so a mapped enum that such a field uses needs with_null_as_option: without it, generation fails with GenerateError::InvalidConfiguration naming the field, instead of every valid frame that leaves the field out failing to decode.

Optional composites with a null image

A composite member itself can carry presence="optional" with a schema nullValue — e.g. a PriceNull9-style Decimal whose mantissa is optional while exponent stays constant. That member decodes as Option<i64> (checked against the wire null sentinel), not a bare i64. This is distinct from a composite field gated by sinceVersion (which the whole composite accessor wraps in Option<Decoder>), and from a composite with no nullValue anywhere (which has no null image to check, so it decodes as a plain value — see with_conversion vs with_domain_type).

Because the wire null sentinel is not a valid rust_decimal::Decimal, the with_domain_type accessor fails closed with a typed error rather than silently decoding the sentinel as a huge/wrong number:

        use rust_decimal::Decimal;

        // `price: None` writes the schema null image (mantissa = nullValue).
        let mut buf = [0u8; QuoteEncoder::compute_length_with_header()];
        let len = QuoteEncoder::wrap_and_apply_header(&mut buf, 0)
            .fixed(&QuoteFixedFields { price: None, qty: 7 })
            .encoded_length_with_header();

        let dec = QuoteDecoder::try_decode(&buf[..len], 0)?;
        assert_eq!(dec.price_value().mantissa(), None);
        assert!(dec.price().is_err(), "null mantissa is not a valid Decimal");

        // A real price round-trips through the null-aware member accessor.
        let len2 = QuoteEncoder::wrap_and_apply_header(&mut buf, 0)
            .fixed(&QuoteFixedFields { price: None, qty: 7 })
            .price(Decimal::new(12345, 9))?
            .encoded_length_with_header();
        let dec2 = QuoteDecoder::try_decode(&buf[..len2], 0)?;
        assert_eq!(dec2.price_value().mantissa(), Some(12345));
        assert_eq!(dec2.price()?, Decimal::new(12345, 9));

(From optional_composite_member_null_image_roundtrip in sbe/tests/baseline_test.rs — a real generated-and-compiled test, not a standalone snippet.)

Timestamp Conversions

SBE timestamps are typically uint64 fields with a semanticType (UTCTimestamp = nanos, UTCTimestampMicros = micros, UTCTimestampMillis = millis). The chrono feature maps them to DateTime<Utc> / NaiveDateTime. Enable it on both Cargo entries:

[build-dependencies]
ergo-sbe = { version = "0.1", features = ["chrono"] }

[dependencies]
ergo-sbe = { version = "0.1", features = ["chrono"] }
chrono = "0.4"

Then register the converters by semanticType in build.rs:

use ergo_sbe::{ConversionSelector, GenerationConfig};

let config = GenerationConfig::new("msgs")
    .with_domain_type(
        ConversionSelector::semantic_type("UTCTimestamp"),
        "chrono::DateTime<chrono::Utc>",
    )
    .with_domain_type(
        ConversionSelector::semantic_type("UTCTimestampMicros"),
        "chrono::NaiveDateTime",
    );

Schema:

<field name="created_at"  id="1" type="uint64" semanticType="UTCTimestamp"/>
<field name="updated_at"  id="2" type="uint64" semanticType="UTCTimestampMicros"/>

Generated API — created_at() returns DateTime<Utc>, updated_at() returns NaiveDateTime:

// Decode
let created: chrono::DateTime<chrono::Utc> = dec.created_at()?;
let updated: chrono::NaiveDateTime = dec.updated_at()?;

// Encode
enc.created_at(chrono::Utc::now())?;
enc.updated_at(
    chrono::DateTime::from_timestamp_micros(1_720_000_000_000_000)
        .ok_or("micros out of range")?
        .naive_utc(),
)?;

timeUnit on a UTCTimestamp field

A uint64 UTCTimestamp field may say what it counts with timeUnit (second, millisecond, microsecond or nanosecond; nanoseconds when absent). The built-in DateTime<Utc> conversion honours it: the domain accessors read and write the field in its own unit, so one semantic_type("UTCTimestamp") mapping serves fields of every precision.

<field name="sentAt" id="1" type="uint64" semanticType="UTCTimestamp" timeUnit="millisecond"/>

Writing a DateTime more precise than the field — sub-millisecond digits into a millisecond field — is an error rather than a truncation; truncate it first (chrono::DurationRound::duration_trunc) when that is what you mean. Under DomainImpl::Manual your impl receives the field’s own unit.

One selector, many fields

ConversionSelector::semantic_type(..) matches every field in the schema carrying that semanticType — not just one. You register the conversion once, not once per field. A schema with three separate UTCTimestamp timestamps needs no more config than one with a single field:

<field name="createdAt"  id="1" type="uint64" semanticType="UTCTimestamp"/>
<field name="updatedAt"  id="2" type="uint64" semanticType="UTCTimestamp"/>
<field name="expiresAt"  id="3" type="uint64" semanticType="UTCTimestamp"/>

// Same one-time call as the two-field example above — no per-field repeats.
let config = GenerationConfig::new("msgs")
    .with_domain_type(
        ConversionSelector::semantic_type("UTCTimestamp"),
        "chrono::DateTime<chrono::Utc>",
    );

All three fields get their own concrete accessor, generated from that one call:

enc.created_at(chrono::Utc::now())?;
enc.updated_at(chrono::Utc::now())?;
enc.expires_at(chrono::Utc::now())?;

let created: chrono::DateTime<chrono::Utc> = dec.created_at()?;
let updated: chrono::DateTime<chrono::Utc> = dec.updated_at()?;
let expires: chrono::DateTime<chrono::Utc> = dec.expires_at()?;

This is why UTCTimestamp and UTCTimestampMicros need separate with_domain_type calls in the two-field example above — they’re different semanticType strings, so they’re different selectors — but adding a fourth UTCTimestamp field to the same schema needs no config change at all. ConversionSelector::field_path is the escape hatch when one specific field needs to differ from its semantic-type siblings. It works because selectors resolve by precedence, not registration order: an exact FieldPath beats a SemanticType, which beats a NamedType. So a blanket semantic_type("UTCTimestamp") mapping plus one field_path("Order.settledAt") override does what it reads like, regardless of which you register first.

Paths are "Message.field", extended with the group names for fields inside a group: "Order.legs.settledAt".

Mixed precisions, one app type — DomainImpl::Manual

The built-in converters give nanos → DateTime<Utc> and micros → NaiveDateTime — two different app types, because that’s what the built-in impls happen to produce. Real schemas often need the opposite: three fields at three different wire precisions, all normalized to the same DateTime<Utc> so downstream app code never branches on precision. None of the three is the bare uint64 + semanticType="UTCTimestamp" shape the built-in converter matches, so none gets an auto-generated impl — that’s exactly the case DomainImpl::Manual is for: concrete domain accessor signatures from ergo-sbe, conversion body from you.

Distinguish the three precisions with single-element composites (a distinct Rust type per precision — TimestampMillis(u64) is not TimestampNanos(u64) even though the wire shape is identical):

<composite name="TimestampMillis"><type name="ts" primitiveType="uint64"/></composite>
<composite name="TimestampMicros"><type name="ts" primitiveType="uint64"/></composite>
<composite name="TimestampNanos"><type name="ts" primitiveType="uint64"/></composite>

<field name="createdAt" id="1" type="TimestampNanos"/>
<field name="updatedAt" id="2" type="TimestampMicros"/>
<field name="deletedAt" id="3" type="TimestampMillis"/>

One with_manual_domain_type(selector, path) call per composite — same target type, rust_decimal-style — in build.rs:

use ergo_sbe::{ConversionSelector, GenerationConfig};

let config = GenerationConfig::new("msgs")
    .with_manual_domain_type(
        ConversionSelector::named_type("TimestampNanos"),
        "chrono::DateTime<chrono::Utc>",
    )
    .with_manual_domain_type(
        ConversionSelector::named_type("TimestampMicros"),
        "chrono::DateTime<chrono::Utc>",
    )
    .with_manual_domain_type(
        ConversionSelector::named_type("TimestampMillis"),
        "chrono::DateTime<chrono::Utc>",
    );

Each composite is a genuinely new named type, so there is no built-in template to offer — write the three impls yourself, one per precision (the traits live in the generated module as sbe_rt::TryFromSbe / sbe_rt::TryToSbe; import from there, not from ergo_sbe::codegen, which is crate-private):

// my_msgs is the module name passed to GenerationConfig::new("my_msgs")
use my_msgs::sbe_rt::{TryFromSbe, TryToSbe};
use my_msgs::{TimestampMillis, TimestampMicros, TimestampNanos};

impl TryFromSbe<TimestampNanos> for chrono::DateTime<chrono::Utc> {
    type Error = &'static str;
    fn try_from_sbe(wire: TimestampNanos) -> Result<Self, Self::Error> {
        // A single-member composite wraps its wire bytes: TimestampNanos([u8; 8]).
        let ns = u64::from_le_bytes(wire.0);
        chrono::DateTime::from_timestamp((ns / 1_000_000_000) as i64, (ns % 1_000_000_000) as u32)
            .ok_or("timestamp out of range")
    }
}
impl TryToSbe<TimestampNanos> for chrono::DateTime<chrono::Utc> {
    type Error = &'static str;
    fn try_to_sbe(&self) -> Result<TimestampNanos, Self::Error> {
        // The wire type is uint64: pre-epoch has no representation, so it is
        // an error. `as u64` on a negative i64 would wrap silently.
        let ns = self.timestamp_nanos_opt().ok_or("overflow")?;
        let ns = u64::try_from(ns).map_err(|_| "timestamp before 1970")?;
        Ok(TimestampNanos(ns.to_le_bytes()))
    }
}

impl TryFromSbe<TimestampMicros> for chrono::DateTime<chrono::Utc> {
    type Error = &'static str;
    fn try_from_sbe(wire: TimestampMicros) -> Result<Self, Self::Error> {
        let us = u64::from_le_bytes(wire.0);
        chrono::DateTime::from_timestamp((us / 1_000_000) as i64, ((us % 1_000_000) * 1_000) as u32)
            .ok_or("timestamp out of range")
    }
}
impl TryToSbe<TimestampMicros> for chrono::DateTime<chrono::Utc> {
    type Error = &'static str;
    fn try_to_sbe(&self) -> Result<TimestampMicros, Self::Error> {
        let us = u64::try_from(self.timestamp_micros()).map_err(|_| "timestamp before 1970")?;
        Ok(TimestampMicros(us.to_le_bytes()))
    }
}

impl TryFromSbe<TimestampMillis> for chrono::DateTime<chrono::Utc> {
    type Error = &'static str;
    fn try_from_sbe(wire: TimestampMillis) -> Result<Self, Self::Error> {
        let ms = u64::from_le_bytes(wire.0);
        chrono::DateTime::from_timestamp((ms / 1000) as i64, ((ms % 1000) * 1_000_000) as u32)
            .ok_or("timestamp out of range")
    }
}
impl TryToSbe<TimestampMillis> for chrono::DateTime<chrono::Utc> {
    type Error = &'static str;
    fn try_to_sbe(&self) -> Result<TimestampMillis, Self::Error> {
        let ms = u64::try_from(self.timestamp_millis()).map_err(|_| "timestamp before 1970")?;
        Ok(TimestampMillis(ms.to_le_bytes()))
    }
}

All three fields now return the exact same app type despite three different wire precisions — the caller never has to know or care which precision a given field was wire-encoded at:

let created: chrono::DateTime<chrono::Utc> = dec.created_at()?;
let updated: chrono::DateTime<chrono::Utc> = dec.updated_at()?;
let deleted: chrono::DateTime<chrono::Utc> = dec.deleted_at()?;

enc.created_at(chrono::Utc::now())?;
enc.updated_at(chrono::Utc::now())?;
enc.deleted_at(chrono::Utc::now())?;

If you forget one of the three impls, the compile error names it directly — `chrono::DateTime<Utc>` has no `TryFromSbe<TimestampMillis>` impl — instead of the default trait-bound message.

Design Notes

• Type-state and runtime cost
• API freeze decisions
• Why NullVal Instead of Option
• Feature Matrix

Type-state and runtime cost

Stage identity adds no runtime tag. The named structs carry buffer and cursor state; markers such as HeaderPresent are zero-sized. A transition moves that state into the next concrete type:

(buf, msg_offset, pos)  +  PhantomData / zero-sized stage identity

No heap, no vtable, no enum discriminant, no “which stage am I in?” branch — the stage is the type, so the methods that exist are the ones legal at that point. Inlining can remove the intermediate moves. Decoder stages also carry acting version and block length; dynamic group callbacks check that the returned completion belongs to the supplied entry.

The sbe-tool gate compares two different codecs, so it cannot isolate the cost of type-state, and no benchmark here measures that cost on its own. A measurable type-state tax would be a codegen defect. Gate and method: Benchmarks.

Named stages (CarEncoder → CarAfterFuelFigures → CarComplete) are the type-state pattern. The other spelling is Encoder<'a, Stage> with phantom markers. This crate uses named stages; the two were not compared.

Tail stages drop F — they are already past the fixed block.

pub struct BookEncoder<'a, H: HeaderState = HeaderPresent, F: FieldsState = FieldsUnfixed> { /* … */ }
pub struct BookAfterBids<'a, H: HeaderState = HeaderPresent> { /* same layout */ }

impl BookEncoder<'a, H, FieldsFixed> {
    pub fn bids(self, …) -> Result<BookAfterBids<'a>, …> { … }
    // no asks() — bids first on the wire
}

Stage names: After{GroupPascal} (fuelFigures → CarAfterFuelFigures). Reserved method names: reserved_name_clash_test. Product rationale: Wire order. Migration: Coming from sbe-tool.

API freeze decisions (pre-1.0)

Deliberate decisions on the generated public surface. Changing any of these after 1.0 is a major version. Golden file sbe/tests/golden/car_example.rs is the artifact for API shape review.

1. wrap takes message start (not body offset)

Decision: keep ergon semantics. One offset works for encode wrap, wrap_and_apply_header, and claim buffers. sbe-tool refugees who pass 8 for a frame at zero will mis-align every field — that is the #1 migration trap. Loud rustdoc on every generated wrap / wrap_and_apply_header / decode documents this; the book chapter Coming from sbe-tool is the full mapping.

2. *FixedFields is intentionally exhaustive

Generated CarFixedFields (and peers) are not #[non_exhaustive].

Decision: exhaustive is a feature. When the schema adds a fixed field, every fixed(&…) call site must update. Silent Default / ignored new fields would hide schema drift. Do not “fix” this with #[non_exhaustive] without a major-version design review.

3. Stage struct naming

Pattern: {Message}After{GroupPascal} for intermediate stages, {Message}Complete for the terminal encoder stage; decoder stages use {Message}DecoderAfter{…} similarly. Multi-word group names go through the same PascalCase path as other types (fuelFigures → FuelFigures → CarAfterFuelFigures). Reserved-name clash coverage: sbe/tests/reserved_name_clash_test.rs.

Decision: keep named monomorphic stages (not Encoder<State = AfterBids>). Rationale: Type-state design note.

4. _unchecked companions are a supported opt-in

Decision: supported production opt-in after a proven trust boundary — not “benchmarking only” framing.

• Default generation exposes the three-tier constructor boundary: try_* (Result), bare wrap (panic after extent proof), bare decode (panic if short, Err on wrong template/schema), and unsafe fn *_unchecked.
• Safety contract: validate with try_decode / try_from / try_wrap / verify at trust edges; only *_unchecked may skip the extent proof (UB if wrong).
• Hot loops after validation are an intended use case for the unchecked lane. Checked constructors remain the default for untrusted input.

See Trust boundaries.

5. Header marker default

H: HeaderState = HeaderPresent on encoder stages so the common full-frame path needs no turbofish. Body-only encoding uses wrap / HeaderAbsent explicitly.

6. No renames bundled with this note

This audit records decisions; it does not rename public generated types.

7. #[non_exhaustive] policy for generated structs

Decision: keep generated consumer-facing structs non-exhaustive via pub(crate) fields rather than #[non_exhaustive]. A downstream crate cannot construct one directly, so adding a field is not a breaking change. #[non_exhaustive] is reserved for public enums that will gain variants over time (GenerateError, ConnectStep). Any future rename lands in one release with CHANGELOG entries.

Why NullVal Instead of Option

An SBE enum may declare a nullValue in the schema — an explicit wire sentinel that means “not present” / “not set”. When the schema doesn’t specify one, SBE defaults to the encoding type’s null sentinel: the maximum value for unsigned types (e.g. 255 for uint8) and the minimum value for signed types (e.g. -128 for int8).

nullValue / minValue / maxValue on a type or field must fit the declared primitive width. nullValue="256" on uint8 is a parse error — it would otherwise collapse to 0 on the wire and make Some(0) indistinguishable from None. See Error Diagnostics.

An early design tried wrapping every enum field in Option<EventCode> at the field site:

// Option approach — REJECTED
pub fn event_code(&self) -> Option<EventCode> { … }
pub fn set_event_code(&mut self, val: Option<EventCode>) { … }

This was rejected for three reasons:

1. API complexity. Using Option<EventCode> at every access point forces every consumer to .unwrap() or match, even when the field is known to be populated. The NullVal approach gives you a plain EventCode type — if you care about null, check code == EventCode::NullVal; if you don’t, just use it. (The wire encoding itself would be compatible either way: None maps to the null sentinel, Some(v) maps to v. The issue is ergonomics, not wire format.)

2. Generated code complexity. Every field site that uses Option<EventCode> needs value↔Option mapping in both accessor directions, inflating the generated code for no wire-format gain.

3. Schema intent. The schema declares a null sentinel as part of the enum’s own value domain, not as a separate presence flag. A NullVal variant reflects that intent directly in the Rust type.

The chosen design adds a NullVal variant to every generated enum. It is the same size as any other variant and wire-compatible with sbe-tool. Its runtime cost is not measured here:

// ergo-sbe generated (conceptual)
pub enum EventCode {
    NullVal = 255,  // or schema-declared nullValue
    Ok = 200,
    Error = 400,
    Timeout = 408,
}

For an Optional field (schema presence="optional"), the generated accessor returns Option<EventCode> — but the null check compares against the NullVal discriminant on the wire, never allocates, and is transparent to the caller.

On encode, fixed(&FixedFields) always writes every fixed field: Some(v) writes the value and None writes the exact schema null wire image (including nested optional composite members). Dirty buffer reuse is therefore safe when you go through fixed. Prefer that path for whole-message encodes.

apply_nulls() remains on the unfixed encoder after wrap_and_apply_header when you set individual optional fields piecemeal instead of using FixedFields. See Encode and Decode.

Opting into Option<T> with with_null_as_option

The NullVal is the right default, but some codebases prefer Option throughout. Use with_null_as_option to make generated enum accessors return Option<Enum> — NullVal maps to None, all other values to Some(v). Wire bytes are identical either way.

use ergo_sbe::{ConversionSelector, GenerationConfig};

// Individual enum → Option<Enum>
let config = GenerationConfig::new("msgs")
    .with_null_as_option(ConversionSelector::named_type("EventCode"));

// Every enum in the schema → Option<Enum>
let config = GenerationConfig::new("msgs")
    .with_all_enums_as_option();

Generated diff (individual setter):

// Default (NullVal)                         // with_null_as_option
pub fn code(&self) -> EventCode { … }   →   pub fn code(&self) -> Option<EventCode> { … }

The as_option() method is also generated on every enum for manual use: event_code.as_option() → Option<EventCode>.

Null-aware accessors on BooleanType

For BooleanType fields, ergon emits a {field}_bool() accessor alongside the standard enum getter. One name at every shape and location, the same name as the {field}_bool(v) encoder setter; it returns Result because the decode is fallible:

// Standard getter — returns the enum variant (raw wire discriminant).
pub fn available(&self) -> BooleanType { … }

// Null-aware — rejects NullVal (returns Err); Ok(true/false) otherwise.
pub fn available_bool(&self) -> Result<bool, DecodeError> { … }

// A `sinceVersion > 0` field can also be absent, so its getter adds the
// `Option` layer — the only shape difference, at message and group level:
pub fn added_later_bool(&self) -> Result<Option<bool>, DecodeError> { … }

For enums and other types, the NullVal variant remains the default. with_null_as_option (above) is the opt-in Option<T> mapping; the wire encoding is identical either way.

Generated enum mappings

with_enum_mapping maps an SBE enum onto an application enum that has no NullVal (see App Types). There, NullVal is never turned into a variant: it decodes as sbe_rt::MappingError::NullEnum, or as None when the enum is also under with_null_as_option. Because the decoder folds an undeclared discriminant into NullVal, an unknown value reaches the mapping as that same NullVal.

Feature Matrix

Scannable map of capabilities. Use the More links for samples and tests.

Benchmarks

The maintained benchmarks show ergo-sbe is not slower than official sbe-tool on equal work. They are not a speed claim. Method, fairness rules, ceilings and the gate: sbe/BENCHMARKS.md.

This book records no benchmark result. Quote a ratio with its run id, commit, host, rustc and profile, or do not quote it.

Build your own code with lto = true and codegen-units = 1. Generated hot-path methods carry #[inline], so a non-LTO build can inline them too.

Also compare against your own previous release: see Methodology.

Benchmark Methodology

The fairness rules and the gate are in sbe/BENCHMARKS.md; how a pair is built, its observation barriers and the A/A control in sbe/benchmarks/methodology.md. Two rules to keep in mind:

• Treat a surprising ratio as a benchmark defect until wire parity, equal work, optimizer opacity, amplified timing, both LTO profiles and instruction counts agree.
• Compare against your own previous release as well as against sbe-tool. Two releases can both pass the sbe-tool ceiling while the second is slower.

Gate summary: Benchmarks.

Teaching Path

Standalone crates that exercise repository APIs. They are excluded from the workspace, set publish = false, and are not production reference implementations — they move with experimental APIs on purpose.

Start here (product teaching path)

# 1 — always start here
cargo run  --manifest-path samples/sbe-feature-tour/Cargo.toml

# 2 — pick the conversion style you want in product code
cargo run  --manifest-path samples/l3-book/Cargo.toml
cargo test --manifest-path samples/exchange-example/Cargo.toml

Rule of thumb: one conversion style per schema type (with_domain_type or with_conversion, not both for the same selector).

Conversion: which sample uses what

Rule: one style per selector. with_domain_type already enables conversion; do not stack with_conversion on the same selector.

#![allow(unused)]
fn main() {
    use ergo_sbe::{ConversionSelector, GenerationConfig};
    // A — generic converter: one wire type, many app types
    let _cfg =
        GenerationConfig::new("msgs").with_conversion(ConversionSelector::named_type("Decimal"));
}

#![allow(unused)]
fn main() {
    use ergo_sbe::{ConversionSelector, GenerationConfig};
    // B — concrete mapping: one Rust type per wire type (already enables conversion)
    let _cfg = GenerationConfig::new("msgs").with_domain_type(
        ConversionSelector::named_type("Decimal"),
        "rust_decimal::Decimal",
    );
}

Rules

• Keep every sample outside the workspace and unpublished.
• Do not expose sample-only abstractions as product APIs.
• Size SBE buffers from generated encoded-length APIs (prefer stack when const).
• Propagate fallible operations with Result and ?.
• Delete a sample when it no longer exercises a distinct repository behavior.

SBE Feature Tour

Standalone laboratory sample for ergo-sbe (publish = false). This is the crates.io / docs.rs teaching entry.

Conversion: three styles in one crate

build.rs uses different APIs for different selectors:

#![allow(unused)]
fn main() {
    let generated_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src/generated");
    let config = ergo_sbe::GenerationConfig::new("feature_tour")
        .with_domain_objects(ergo_sbe::DomainVarData::Strings)
        .with_domain_type(
            ergo_sbe::ConversionSelector::named_type("BooleanType"),
            "bool",
        )
        .with_domain_type(
            ergo_sbe::ConversionSelector::semantic_type("UTCTimestamp"),
            "chrono::DateTime<chrono::Utc>",
        )
        .with_conversion(ergo_sbe::ConversionSelector::named_type("Decimal"))
        // Same shape as Decimal, but the app supplies the impl itself — see
        // demo_domain_type_manual_impl in src/lib.rs.
        .with_manual_domain_type(
            ergo_sbe::ConversionSelector::named_type("ManualDecimal"),
            "rust_decimal::Decimal",
        );

    ergo_sbe::generate_to_dir("schemas/feature-tour.xml", config, &generated_dir)?;
}

(The real build.rs — this code is compiled and tested in CI.)

The generated code is included via #[path = "generated/feature_tour.rs"] — no sbe_mod! needed. See Build Patterns.

Runnable proof for the Decimal row: demo_conversion_only in src/lib.rs (uses both rust_decimal and a tiny FixedPrice adapter on the same buffer). Runnable proof for the ManualDecimal row: demo_domain_type_manual_impl — same concrete manual_price(...)? signature DomainImpl::Generated would give you, but the impl TryFromSbe<ManualDecimal> / TryToSbe<ManualDecimal> above it are a literal copy-paste of the doc comment ergo-sbe put on the generated method (see with_conversion vs with_domain_type).

Quick rule

• One fixed app type, ergo-sbe writes the impl → with_domain_type(selector, path)
• One fixed app type, you write the impl (custom rounding/validation, or overriding the three built-ins) → with_manual_domain_type(selector, path)
• Pluggable / no forced dep → with_conversion
• Never call more than one of these for the same selector

Other samples:

Feature map → demo

Run

cargo run  --manifest-path samples/sbe-feature-tour/Cargo.toml
cargo test --manifest-path samples/sbe-feature-tour/Cargo.toml

After build, generated source is under src/generated/feature_tour.rs.

L3 Order Book

Deep nested / ragged L3 order-book sample for ergo-sbe. publish = false.

Conversion style: with_domain_type only

#![allow(unused)]
fn main() {
    use ergo_sbe::{ConversionSelector, GenerationConfig};
    // B — concrete mapping: one Rust type per wire type (already enables conversion)
    let _cfg = GenerationConfig::new("msgs").with_domain_type(
        ConversionSelector::named_type("Decimal"),
        "rust_decimal::Decimal",
    );
}

(From book/examples/conversion-config.rs. Full L3 build.rs: l3-book.)

Generated API (concrete):

enc.price(rust_decimal::Decimal::new(100, 0))?;
let p: rust_decimal::Decimal = dec.price()?;
let ts: DateTime<Utc> = dec.exchange_timestamp()?;

with_domain_type already enables conversion for that selector. Do not also call with_conversion(Decimal) here — it would not change the surface.

Encoding: size exactly, then write

Nothing here guesses a buffer size. The staged L3BookEncodedLength builder walks the same shape the encoder will write — bids_ragged with a nested orders count per level, then asks_ragged, then the var-data symbol — and returns the exact header-inclusive length:

pub fn book_encoded_length(
    bids: &Side<'_>,
    asks: &Side<'_>,
    symbol: &str,
) -> Result<usize, sbe_rt::EncodeError> {
    let after_bids = L3BookEncoder::compute_length().bids_ragged(bids.len() as u16, |g| {
        for (_, _, orders) in bids {
            g.add()?.orders(|og| {
                og.uniform(orders.len())?;
                Ok(())
            })?;
        }
        Ok(())
    })?;
    let after_asks = after_bids.asks_ragged(asks.len() as u16, |g| {
        for (_, _, orders) in asks {
            g.add()?.orders(|og| {
                og.uniform(orders.len())?;
                Ok(())
            })?;
        }
        Ok(())
    })?;
    let complete = after_asks.symbol(symbol.len())?;
    Ok(complete.encoded_length_with_header())
}

_ragged is the point for an order book: every level has a different number of orders, so the count cannot be multiplied out. g.add()?.orders(|og| …) declares one level and then that level’s own order count.

The encoder then writes into a buffer of precisely that length, in wire order, one chained expression:

pub fn encode_book(
    buf: &mut [u8],
    bids: &Side<'_>,
    asks: &Side<'_>,
    symbol: &str,
) -> Result<usize, sbe_rt::EncodeError> {
    let complete = L3BookEncoder::try_wrap_and_apply_header(buf, 0)?
        .fixed(&L3BookFixedFields {
            exchange_timestamp: 1_720_000_000_000_000_000u64,
            sequence: 42,
            is_active: true.into(),
        })
        .bids(bids.len() as u16, |g| {
            for (price, size, orders) in bids {
                g.add(|mut e| {
                    e.price(*price)
                        .map_err(|_| sbe_rt::EncodeError::DomainConversionFailed {
                            field: "price",
                            reason: "conversion",
                        })?;
                    e.size(*size)
                        .map_err(|_| sbe_rt::EncodeError::DomainConversionFailed {
                            field: "size",
                            reason: "conversion",
                        })?;
                    e.orders(orders.len() as u16, |og| {
                        for (oid, qty) in *orders {
                            let raw_qty =
                                SbeDecimal::new(qty.mantissa() as i64, -(qty.scale() as i8));
                            og.add_struct(&L3BookBidsOrdersEntry {
                                order_id: *oid,
                                quantity: raw_qty,
                            })?;
                        }
                        Ok(())
                    })
                })?;
            }
            Ok(())
        })?
        .asks(asks.len() as u16, |g| {
            for (price, size, orders) in asks {
                g.add(|mut e| {
                    e.price(*price)
                        .map_err(|_| sbe_rt::EncodeError::DomainConversionFailed {
                            field: "price",
                            reason: "conversion",
                        })?;
                    e.size(*size)
                        .map_err(|_| sbe_rt::EncodeError::DomainConversionFailed {
                            field: "size",
                            reason: "conversion",
                        })?;
                    e.orders(orders.len() as u16, |og| {
                        for (oid, qty) in *orders {
                            let raw_qty =
                                SbeDecimal::new(qty.mantissa() as i64, -(qty.scale() as i8));
                            og.add_struct(&L3BookAsksOrdersEntry {
                                order_id: *oid,
                                quantity: raw_qty,
                            })?;
                        }
                        Ok(())
                    })
                })?;
            }
            Ok(())
        })?
        .symbol_as_str(symbol)?;
    Ok(complete.encoded_length_with_header())
}

Both functions end with encoded_length_with_header(), and the tests assert the two agree — a length that does not match the bytes written is a bug in the sizing API, not something to paper over with a larger buffer.

symbol declares characterEncoding="ASCII" in the schema, so the generated encoder carries a symbol_as_str(&str) setter alongside the raw symbol(&[u8]) one. Every caller here always holds text, so encode_book takes symbol: &str and writes through symbol_as_str — the ASCII check runs before any byte is written rather than leaving it to the caller. Both setters write identical bytes for the same text; reach for the raw symbol(&[u8]) setter only when the caller genuinely starts from bytes.

let len = book_encoded_length(bids, asks, symbol)?;   // exact, header-inclusive
let mut storage = vec![0u8; len];                     // no oversize, no truncate
let actual = encode_book(&mut storage, bids, asks, symbol)?;
assert_eq!(len, actual);

See Exact sizing and Buffer sizing.

Decoding: random access or one staged chain

L3Book is the shape that makes the decoder lanes worth distinguishing: two sibling groups, each entry carrying a nested orders group, then a trailing var-data symbol. Reaching symbol means walking past every order of every level.

tests/l3_tests.rs encodes one ragged fixture and decodes it through the generated lanes, asserting they produce an identical snapshot. Note what the snapshot holds: the schema’s domain types (rust_decimal::Decimal, DateTime<Utc>, bool) because that is what with_domain_type generates, and a borrowed &'a str for symbol — copying it would defeat the flyweight.

/// Everything the fixture contains, in wire order — in the schema's *domain*
/// types, not its wire types.
///
/// This sample generates with `with_domain_type`, so `price` is
/// `rust_decimal::Decimal`, `exchangeTimestamp` is `DateTime<Utc>` and
/// `isActive` is `bool`. Comparing at that level is what proves the
/// conversions round-trip; comparing raw mantissas would pass even if the
/// domain layer were broken.
///
/// `symbol` is borrowed, not owned: every lane hands back `&'a str` pointing
/// into the wire buffer. Copying it would defeat the flyweight. The `Vec`s
/// are the *test's* comparison scaffolding — a decode has to materialise
/// something to compare — not part of the decode path, which allocates
/// nothing.
#[derive(Debug, PartialEq, Eq)]
struct Snapshot<'a> {
    timestamp: chrono::DateTime<chrono::Utc>,
    sequence: u64,
    is_active: bool,
    /// `(price, size, [(order_id, quantity)])` per level.
    bids: Vec<OwnedLevel>,
    asks: Vec<OwnedLevel>,
    symbol: &'a str,
}

/// A decoded level, owned so lanes can be compared. The decode itself borrows
/// — see `best_bid_and_depth` for the shape a hot path actually uses.
type OwnedLevel = (Rd, Rd, Vec<(u64, Rd)>);

/// Ragged on purpose: 3 bid levels with 2/1/3 orders and 2 ask levels with
/// 1/2. A uniform fixture would let a lane compute entry positions by
/// multiplication and still look correct.
fn fixture() -> (Vec<u8>, Vec<OwnedLevel>, Vec<OwnedLevel>) {
    let o_b1 = [(101u64, d(5)), (102, d(7))];
    let o_b2 = [(103u64, d(25))];
    let o_b3 = [(104u64, d(1)), (105, d(2)), (106, d(3))];
    let bids: &[l3_book::Level<'_>] = &[
        (d(50800), d(15), &o_b1),
        (d(50750), d(40), &o_b2),
        (d(50700), d(60), &o_b3),
    ];
    let o_a1 = [(201u64, d(10))];
    let o_a2 = [(202u64, d(20)), (203, d(30))];
    let asks: &[l3_book::Level<'_>] = &[(d(50850), d(20), &o_a1), (d(50900), d(35), &o_a2)];
    let symbol = "BTCUSDT";

    // Exact sizing through the staged builder, then encode into a buffer of
    // precisely that length: no oversize, no truncate.
    let len = l3_book::book_encoded_length(bids, asks, symbol).expect("length");
    let mut storage = vec![0u8; len];
    let actual = l3_book::encode_book(&mut storage, bids, asks, symbol).expect("encode");
    assert_eq!(len, actual, "computed length must match encoded length");

    let own = |lv: &(Rd, Rd, &[(u64, Rd)])| (lv.0, lv.1, lv.2.to_vec());
    (
        storage,
        bids.iter().map(own).collect(),
        asks.iter().map(own).collect(),
    )
}

Random access — any order, Sync, re-walks

/// Lane 1 — random access (the base decoder from `try_decode`).
///
/// Getters may be called in any order and the decoder is `Sync`. Each
/// dynamic-tail getter re-walks from the fixed block, so reading `bids`,
/// `asks` and `symbol` walks the bid orders three times over. Correct
/// everywhere, cheapest when you want one or two fields.
fn decode_random_access(wire: &[u8]) -> Result<Snapshot<'_>, Box<dyn std::error::Error>> {
    let dec = L3BookDecoder::try_decode(wire, 0)?;

    // Deliberately out of wire order: symbol (the last tail) first, then back
    // to the groups. Only a lane that resolves tails independently can do
    // this. The `&str` borrows the wire buffer — nothing is copied.
    let symbol = dec.symbol_as_str()?;

    let mut bids = Vec::new();
    for level in dec.bids()? {
        let level = level?;
        let mut orders = Vec::new();
        // `orders` is fixed-stride, so its whole region was proven in bounds
        // when the group was entered and the iterator yields entries directly.
        // The outer `bids`/`asks` iterators yield `Result` because a dynamic
        // entry's extent can only be known once it is reached.
        for order in level.orders()? {
            orders.push((order.order_id(), order.quantity()?));
        }
        bids.push((level.price()?, level.size()?, orders));
    }

    let mut asks = Vec::new();
    for level in dec.asks()? {
        let level = level?;
        let mut orders = Vec::new();
        for order in level.orders()? {
            orders.push((order.order_id(), order.quantity()?));
        }
        asks.push((level.price()?, level.size()?, orders));
    }

    Ok(Snapshot {
        timestamp: dec.exchange_timestamp()?,
        sequence: dec.sequence(),
        is_active: dec.is_active()?,
        bids,
        asks,
        symbol,
    })
}

Note it reads symbol — the last tail — first, then goes back to the groups. Only a lane that resolves each tail independently can do that. The cost is that every dynamic-tail getter re-walks from the fixed block.

Staged — wrong order is a compile error

/// Sequential decode — `into_*` / `skip_*`, compile-time order. The group
/// iterator is the stage: `into_asks` skips unread bids.
fn decode_staged(wire: &[u8]) -> Result<Snapshot<'_>, Box<dyn std::error::Error>> {
    let dec = L3BookDecoder::try_decode(wire, 0)?;
    let timestamp = dec.exchange_timestamp()?;
    let sequence = dec.sequence();
    let is_active = dec.is_active()?;

    // Levels carry a nested `orders` group, so they have no stride and take a
    // visit closure — the completion it returns is where the next level starts.
    // `orders` entries are fixed-stride, so they are a plain iterator.
    let mut bids = Vec::new();
    let mut asks = Vec::new();
    let (symbol, _complete) = dec
        .into_bids(|level| -> Result<_, Box<dyn std::error::Error>> {
            let price = level.price()?;
            let size = level.size()?;
            let mut orders = Vec::new();
            let mut order_iter = level.into_orders()?;
            for order in &mut order_iter {
                orders.push((order.order_id(), order.quantity()?));
            }
            bids.push((price, size, orders));
            Ok(order_iter.finish()?)
        })?
        .into_asks(|level| -> Result<_, Box<dyn std::error::Error>> {
            let price = level.price()?;
            let size = level.size()?;
            let mut orders = Vec::new();
            let mut order_iter = level.into_orders()?;
            for order in &mut order_iter {
                orders.push((order.order_id(), order.quantity()?));
            }
            asks.push((price, size, orders));
            Ok(order_iter.finish()?)
        })?
        .into_symbol_as_str()?;

    Ok(Snapshot {
        timestamp,
        sequence,
        is_active,
        bids,
        asks,
        symbol,
    })
}

into_symbol exists only on the stage reached after asks completes, so the out-of-order read above is not expressible here. One wire-order pass.

Memoized — any order, each boundary walked once

/// Lane 3 — memoized (`decoder.memoized()`).
///
/// Same getter names as the base lane, plus a progressive cache of discovered
/// tail boundaries. Read here in the worst order for the base lane — symbol
/// first, then back to the groups, then symbol again — which is exactly the
/// shape the cache exists for.
fn decode_memoized(wire: &[u8]) -> Result<Snapshot<'_>, Box<dyn std::error::Error>> {
    let dec = L3BookDecoder::try_decode(wire, 0)?.memoized();

    let symbol = dec.symbol_as_str()?;

    let mut bids = Vec::new();
    for level in dec.bids()? {
        let level = level?;
        let mut orders = Vec::new();
        for order in level.orders()? {
            orders.push((order.order_id(), order.quantity()?));
        }
        bids.push((level.price()?, level.size()?, orders));
    }

    let mut asks = Vec::new();
    for level in dec.asks()? {
        let level = level?;
        let mut orders = Vec::new();
        for order in level.orders()? {
            orders.push((order.order_id(), order.quantity()?));
        }
        asks.push((level.price()?, level.size()?, orders));
    }

    // Re-reading a tail is free once its boundary is known: the base lane
    // would re-walk every bid and ask order to get back here.
    assert_eq!(dec.symbol_as_str()?, symbol, "re-read must be identical");

    Ok(Snapshot {
        timestamp: dec.exchange_timestamp()?,
        sequence: dec.sequence(),
        is_active: dec.is_active()?,
        bids,
        asks,
        symbol,
    })
}

Same getter names as random access. Read in the order shown — symbol, then back to the groups, then symbol again — the base lane re-walks every bid and ask order to return to symbol; this lane reuses the boundary it already found. Build it once and pass &L3BookMemoizedDecoder around: calling .memoized() in each function creates a separate empty cache.

Ordered — one spelling, all the way down

/// Lane 4 — ordered (`decoder.ordered()`). One callback per tail, in wire
/// order, with the *same spelling* at every tail, plus an `EntryInfo` giving
/// each entry's position.
///
/// Compare with `decode_staged`: there, `bids` takes a visit closure and
/// `orders` is an iterator, because their shapes genuinely differ. Here every
/// message-level tail — fixed block, both groups, and the var-data — reads the
/// same way. That uniformity is why this lane exists: code that walks whole
/// messages writes one form instead of branching on each tail's shape.
///
/// It goes all the way down. A `bids` level carries its own tail (the nested
/// `orders` group), so it has an `ordered()` of its own, and the spelling does
/// not change at the entry boundary. Returning that nested walk is the
/// completion the parent owes — no `.done()` on the way out. The message
/// chain ends on `encoded_length_with_header()`, like encode.
///
/// The staged `level.into_orders()` iterator is still generated beside it and
/// is still the better tool when you want to `break` early — `orders` is
/// fixed-stride, so its iterator is an `ExactSizeIterator` and stopping short
/// still reaches the next tail by arithmetic. The lane adds a spelling; it
/// removes nothing.
///
/// `EntryInfo::count` is the wire-declared `numInGroup`, read from the group's
/// dimension header before the walk starts, so the `Vec` is sized once rather
/// than grown. It costs no scan. `bids` and `asks` still need separate bodies
/// because their entry decoders are distinct types — the lane unifies how a
/// tail is *reached*, not what its entries are.
fn decode_ordered(wire: &[u8]) -> Result<Snapshot<'_>, Box<dyn std::error::Error>> {
    // Ordered callbacks return `DecodeError`; a domain getter fails with its
    // conversion's own error, mapped the way the generated DTO maps it.
    fn domain<T, E>(field: &'static str, r: Result<T, E>) -> Result<T, sbe_rt::DecodeError> {
        r.map_err(|_| sbe_rt::DecodeError::DomainConversionFailed {
            field,
            reason: "domain conversion rejected wire value",
        })
    }

    let mut timestamp = None;
    let mut sequence = 0u64;
    let mut is_active = false;
    let mut bids: Vec<OwnedLevel> = Vec::new();
    let mut asks: Vec<OwnedLevel> = Vec::new();
    let mut symbol: Option<&str> = None;

    let len = L3BookDecoder::try_decode(wire, 0)?
        .ordered()
        .fixed(|d| {
            timestamp = Some(domain("exchange_timestamp", d.exchange_timestamp())?);
            sequence = d.sequence();
            is_active = domain("is_active", d.is_active())?;
            Ok(())
        })?
        .bids(|level, info| {
            if info.is_first() {
                bids.reserve_exact(info.count);
            }
            let price = domain("price", level.price())?;
            let size = domain("size", level.size())?;
            // Nested `ordered()` returns the completion the parent owes —
            // no `.done()` on the way out.
            let mut orders = Vec::new();
            let complete = level.ordered().orders(|order, _oinfo| {
                orders.push((order.order_id(), domain("quantity", order.quantity())?));
                Ok(())
            })?;
            bids.push((price, size, orders));
            Ok(complete)
        })?
        .asks(|level, info| {
            if info.is_first() {
                asks.reserve_exact(info.count);
            }
            let price = domain("price", level.price())?;
            let size = domain("size", level.size())?;
            let mut orders = Vec::new();
            let complete = level.ordered().orders(|order, _oinfo| {
                orders.push((order.order_id(), domain("quantity", order.quantity())?));
                Ok(())
            })?;
            asks.push((price, size, orders));
            Ok(complete)
        })?
        .symbol_as_str(|s| {
            symbol = Some(s);
            Ok(())
        })?
        .encoded_length_with_header();
    debug_assert_eq!(len, wire.len());

    Ok(Snapshot {
        timestamp: timestamp.ok_or("fixed callback must run")?,
        sequence,
        is_active,
        bids,
        asks,
        symbol: symbol.ok_or("symbol callback must run")?,
    })
}

Compare it with the staged lane above: there bids takes a visit closure and orders is an iterator, because those two shapes genuinely differ. Here every message-level tail — fixed block, both groups, then the var-data — reads the same way, and each entry callback also receives an EntryInfo carrying index, the wire-declared count, and the acting block_length. Count and block length come from the group decoder the staged walk already opened; the index advances with the walk. Using info.count to reserve space needs no entry scan. Empty groups never deliver EntryInfo; <group>_count() on the ordered stage still reports the declared count.

It recurses. A bids level carries its own tail — the nested orders group — so the level decoder has an ordered() too, and the callback above uses it. The spelling does not change at the entry boundary, and returning that nested walk is the completion the parent closure owes — no .done() on the way out. An entry with no tails of its own (a fixed-stride entry) has nothing to order and gets no lane. An entry whose existing getter is named ordered also keeps its getter and uses the staged spelling for its tails.

The staged spelling is still generated beside it: level.into_orders() hands back a real ExactSizeIterator you can break out of and still reach the next tail by arithmetic. Pick the iterator when you want to stop early and continue at the next tail, or the ordered lane when you want callbacks throughout.

It is a façade over the staged stages, so it keeps their single traversal and compile-time tail order. The message chain ends on encoded_length_with_header(), like encode. Dynamic groups fill EntryInfo from that walk; fixed-stride groups reuse the iterator’s count and stride. Neither shape pre-scans entries or re-opens the dimension header. The optimizer and measured workload determine the callback wrapper’s final cost. Message-level fixed receives a fixed-fields-only view. Callbacks return DecodeError; convert to an application error after the walk.

On a hot path, collect nothing

The four functions above build owned Vecs because a test has to materialise something to compare. Real consumption does not: the decoders are flyweights over the wire buffer, &str and &[u8] borrow from it, and a full nested walk needs no allocation at all.

/// The shape you actually want on a hot path: no `Vec`, no `String`, no copy.
///
/// The lane functions above build owned collections because a test has to
/// materialise something to compare. Real consumption does not. Here every
/// level and every nested order is visited, `symbol` is used as a borrowed
/// `&str`, and the only state is a handful of scalars in registers — the
/// generated decoders are flyweights over the wire buffer and allocate
/// nothing, so this whole walk is allocation-free.
///
/// A price is compared as a price, not as a raw mantissa: the wire `Decimal`
/// carries its own exponent, and `1.00` (mantissa 100, exponent −2) is less
/// than `99` (mantissa 99, exponent 0). The fallible domain conversion is the
/// one place that knows how to align the two.
fn best_bid_and_depth(wire: &[u8]) -> Result<(Rd, u64, usize, &str), sbe_rt::DecodeError> {
    let mut best_bid: Option<Rd> = None;
    let mut total_orders = 0u64;
    let mut levels = 0usize;

    let (symbol, _done) = L3BookDecoder::try_decode(wire, 0)?
        .into_bids(|level| -> Result<_, sbe_rt::DecodeError> {
            levels += 1;
            let px = level
                .price()
                .map_err(|reason| sbe_rt::DecodeError::DomainConversionFailed {
                    field: "price",
                    reason,
                })?;
            if best_bid.is_none_or(|b| px > b) {
                best_bid = Some(px);
            }
            let mut orders = level.into_orders()?;
            // Fixed stride, so the count is exact without walking.
            let entries = &mut orders;
            total_orders += entries.len() as u64;
            orders.finish()
        })?
        .skip_asks()?
        .into_symbol_as_str()?;

    Ok((
        best_bid.ok_or(sbe_rt::DecodeError::DomainConversionFailed {
            field: "bids",
            reason: "no bid levels",
        })?,
        total_orders,
        levels,
        symbol,
    ))
}

hot_path_walk_borrows_everything asserts the returned &str points inside the wire buffer rather than at a copy. Repository-wide, allocation_count_test pins the same property for generated decode under a counting allocator.

Which one

Full comparison, including how each differs from sbe-tool’s single limit cursor: Decoder lanes.

Layout

Run

cargo run  --manifest-path samples/l3-book/Cargo.toml
cargo test --manifest-path samples/l3-book/Cargo.toml

Exchange Example

Multi-schema exchange-shaped sample. with_conversion only for Decimal — no with_domain_type. publish = false.

Conversion style

#![allow(unused)]
fn main() {
    use ergo_sbe::{ConversionSelector, GenerationConfig};
    // A — generic converter: one wire type, many app types
    let _cfg =
        GenerationConfig::new("msgs").with_conversion(ConversionSelector::named_type("Decimal"));
}

(From book/examples/conversion-config.rs. Full multi-schema build.rs: exchange-example.)

That emits generic methods. The app supplies TryFromSbe / TryToSbe:

// encode: app Decimal → wire
e.price_from(&d)?;

// decode: wire → app Decimal
let d: rust_decimal::Decimal = level.price_as()?;

You still have wire accessors (price_value / price_wire). You do not get a concrete price() -> rust_decimal::Decimal — that requires with_domain_type(..., "rust_decimal::Decimal") (see L3 Order Book).

Run

cargo test --manifest-path samples/exchange-example/Cargo.toml

Codegen as Library

Generator-API examples — how to call ergo-sbe as a library to generate and inspect codecs programmatically (without a build.rs).

The other samples (l3-book, sbe-feature-tour, exchange-example) all use build.rs to generate codecs at compile time and then exercise them end-to-end. These examples complement them by showing the generator API itself — useful for tooling, golden-file workflows, and understanding what the generator produces.

Examples

# From the repository root — this crate is not a workspace member.
cargo run --manifest-path samples/sbe-codegen-examples/Cargo.toml --example flyweight
cargo run --manifest-path samples/sbe-codegen-examples/Cargo.toml --example domain_objects
cargo run --manifest-path samples/sbe-codegen-examples/Cargo.toml --example l3_nested
cargo run --manifest-path samples/sbe-codegen-examples/Cargo.toml --example dump_gen

What each shows

All examples parse the canonical car schema.

Cluster Tutorial

End-to-end walkthrough: launch a test cluster, connect a session, offer messages, poll events, send keep-alives, and close. The best starting point for the ergo-aeron-cluster client lifecycle.

Source: samples/cluster-tutorial/src/main.rs

See also: Cluster Client → Overview

just build-aeron-jars
cargo run --manifest-path samples/cluster-tutorial/Cargo.toml

Requires a JDK 25 (17 or newer) and built Aeron artifacts; see Java for Archive and Cluster.

Cluster HA Orderbook

Claim-based Cluster publishing with an HA-shaped limit order book. Proves try_claim patterns and never-stale book snapshots under leader transitions.

• Offline pipeline (ha_offline_pipeline) — claim + encode + verify without a live cluster.
• Kill-leader test (ha_kill_leader) — validates book integrity across leader changes (requires Java harness).

Source: samples/cluster-ha-orderbook/src/

# Service-free
cargo test --manifest-path samples/cluster-ha-orderbook/Cargo.toml \
  --lib --test ha_offline_pipeline

# Full harness (needs Java)
just build-aeron-jars
cargo test --manifest-path samples/cluster-ha-orderbook/Cargo.toml \
  --features test-harness

Cluster RFQ

RFQ / auction protocol codecs with cluster-backed examples. Demonstrates e-sniping timer, auction state machine, and multi-participant message flows over Aeron Cluster.

• rfq_client — sends RFQ, receives quotes, places order.
• auction_client — auction lifecycle with e-sniping.
• rfq_roundtrip — encode/decode parity for all RFQ message types.

Source: samples/cluster-rfq/

cargo build --manifest-path samples/cluster-rfq/Cargo.toml --examples
cargo run --manifest-path samples/cluster-rfq/Cargo.toml --example rfq_roundtrip

Build Patterns

Generated codecs ship their own embedded sbe_rt module. Linking the app does not require ergo-sbe unless you use its macros or call the generator library at runtime.

Seeing generated code (without committing it)

include!(concat!(env!("OUT_DIR"), …)) and sbe_mod! put files under a hashed path like target/debug/build/<crate>-<hash>/out/….rs, which is awkward to open by hand.

Samples instead write to a stable, local path:

samples/<name>/src/generated/*.rs   # created on cargo build, gitignored

1. cargo build --manifest-path samples/sbe-feature-tour/Cargo.toml
2. Open samples/sbe-feature-tour/src/generated/feature_tour.rs
3. From app code, Go to definition on CarEncoder / etc. should land there

Root .gitignore has **/src/generated/. Do not commit those trees (Binance alone is multi‑MB). Rebuild after a clean clone.

  // build.rs
  let out = Path::new(env!("CARGO_MANIFEST_DIR")).join("src/generated");
  ergo_sbe::generate_to_dir("schemas/messages.xml", config, &out)?;

  // src/lib.rs — real path → IDE go-to-definition works
  #[allow(dead_code, unused_imports, non_camel_case_types, non_snake_case, clippy::all, warnings)]
  #[path = "generated/messages.rs"]
  mod messages;

Buffer Sizing Guide

Size buffers with the generated length APIs (compute_length_with_header(), the staged *EncodedLength builders). A MAX_ENCODED_LENGTH stack array is fine when that constant is a true fixed upper bound — check first: it counts one entry per group and only var-data that declares maxLength, so multi-entry groups need the staged builder. Avoid guess constants such as vec![0u8; 4096]: they hide size bugs.

Const-sized messages — stack array, no heap:

#![allow(unused)]
fn main() {
  let mut buf = [0u8; HeartbeatEncoder::compute_length_with_header()];
}

Dynamic / ragged messages — compute exact size first with *EncodedLength, then encode into a claim or slot of that exact length:

#![allow(unused)]
fn main() {
pub fn demo_car_size_and_encode() -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    // Fuel: 2 entries with usage ASCII lengths 5 and 7.
    // Performance: 1 entry with 2 nested acceleration rows (fixed-only entries).
    // Message var-data: manufacturer / model / activationCode lengths.
    let complete_len = CarEncoder::compute_length()
        .fuel_figures_ragged(2, |ff| {
            ff.add()?.usage_description(5)?; // "Urban"
            ff.add()?.usage_description(7)?; // "Highway"
            Ok(())
        })?
        .performance_figures_ragged(1, |pf| {
            pf.add()?.acceleration(|acc| {
                acc.uniform(2)?;
                Ok(())
            })?;
            Ok(())
        })?
        .manufacturer(5)? // "Honda"
        .model(9)? // "Civic VTi"
        .activation_code(6)? // "abcdef"
        .encoded_length_with_header();

    // Exact size from compute_length → stack pad (this demo fits well under 512).
    const CAR_PAD: usize = 512;
    assert!(
        complete_len <= CAR_PAD,
        "sample car length {complete_len} exceeds stack pad {CAR_PAD}"
    );
    let mut storage = [0u8; CAR_PAD];
    let written = encode_sample_car(&mut storage[..complete_len])?;
    assert_eq!(
        written, complete_len,
        "CarEncodedLength must equal encoder-produced length"
    );
    Ok(storage[..written].to_vec())
}
/// Encode the canonical sample car into `buf` (must be pre-sized).
pub fn encode_sample_car(buf: &mut [u8]) -> Result<usize, sbe_rt::EncodeError> {
    let mut extras = OptionalExtras::default();
    extras.cruise_control(true).sports_pack(true);

    // Buffer pre-sized from EncodedLength; try_* still validates extent.
    let len = CarEncoder::try_wrap_and_apply_header(buf, 0)
        .unwrap()
        .fixed(&CarFixedFields {
            serial_number: 1234,
            model_year: 2013,
            available: true.into(),
            code: Model::A,
            some_numbers: [10, 20, 30, 40],
            vehicle_code: [b'A', b'B', b'C', b'D', b'E', b'F'],
            extras,
            engine: Engine::new(
                2000,
                4,
                [b'1', b'2', b'3'],
                0i8,
                false.into(),
                Booster::new(BoostType::TURBO, 210),
            ),
        })
        .fuel_figures(2, |g| {
            g.add(|mut e| {
                e.speed(30).mpg(35.9);
                e.usage_description_as_str("Urban")
            })?;
            g.add(|mut e| {
                e.speed(60).mpg(25.0);
                e.usage_description_as_str("Highway")
            })?;
            Ok(())
        })?
        .performance_figures(1, |g| {
            g.add(|mut e| {
                e.octane_rating(95);
                e.acceleration(2, |a| {
                    a.add(|x| {
                        x.mph(30).seconds(4.0);
                        Ok(())
                    })?;
                    a.add(|x| {
                        x.mph(60).seconds(7.5);
                        Ok(())
                    })
                })
            })?;
            Ok(())
        })?
        .manufacturer_as_str("Honda")?
        .model_as_str("Civic VTi")?
        .activation_code_as_str("abcdef")?
        .encoded_length_with_header();

    Ok(len)
}
}

(This code comes from the sbe-feature-tour sample crate.)

Key rules:

• compute_length_with_header() is const when the message has no var-data fields or groups — use it directly for stack array sizes.
• For messages with groups or var-data, use the staged *EncodedLength builder.
• Assert computed length equals actual encoded length after writing.
• Oversize vec![0u8; 4096] “guess” buffers hide size bugs — avoid them.

Cluster Client

ergo-aeron-cluster is an experimental Rust client for Aeron Cluster. It uses rusteron for transport and ergo-sbe-generated codecs for Aeron’s Cluster protocol.

Hobby project. Do not use it as a production substitute for official Aeron Cluster client support.

Scope

The crate implements client-side operations:

• synchronous and poll-driven connection;
• ingress offer and explicit try_claim;
• regular and controlled egress polling;
• authentication challenges and credentials;
• keep-alives and close requests;
• session events, administrative responses, and leader changes.

The Java Aeron process still provides the media driver, archive, consensus module, clustered services, election, recovery, and operational tooling. This crate implements none of those server-side components.

Features and harness

The published crate has no extra features. Java Cluster launch support lives in the unpublished workspace crate ergo-aeron-cluster-test-harness and requires a JDK (17 or newer; CI runs Temurin 25) plus locally built Aeron artifacts. See Java for Archive and Cluster for which Java to run the cluster on and the recommended JVM and Aeron settings:

just build-aeron-jars
just test-aeron-cluster-harness

The harness, examples, integration tests, reference codecs, and benchmarks are excluded from the published crate package.

Verify the crate

cargo test -p ergo-aeron-cluster
cargo clippy -p ergo-aeron-cluster --all-targets -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc -p ergo-aeron-cluster --no-deps
cargo bench -p ergo-aeron-cluster --no-run
cargo package -p ergo-aeron-cluster --list --allow-dirty

Run just bench-cluster for the maintained codec comparisons. See sbe/BENCHMARKS.md for the common benchmark rules.

Limitations

Limitations, Aeron and rusteron versions, schema identities, failure modes and what CI runs against a live cluster: Compatibility.

Apache-2.0.

SessionBuilder

SessionBuilder is the supported configuration entry point:

use std::sync::Arc;
use std::time::Duration;
use ergo_aeron_cluster::{SessionBuilder, StaticCredentials};

fn main() -> Result<(), ergo_aeron_cluster::ClusterError> {
    let session = SessionBuilder::default()
        .ingress_channel("aeron:udp?endpoint=localhost:9010")?
        .egress_channel("aeron:udp?endpoint=localhost:9020")?
        .credentials(Arc::new(StaticCredentials::from_utf8("user:pass")))
        .message_timeout(Duration::from_secs(5))?;

    session.validate()?;
    let mut client = session.connect("/path/to/aeron-dir")?;
    client.offer(b"application payload")?;
    client.close()
}

Connection remains poll-driven internally; the crate does not require Tokio or another async runtime. AsyncClusterConnect is a poll-driven Aeron state machine, not a Rust Future. When the application owns the poll loop, the shortest supported path is SessionBuilder → connect_async → default_idle → poll_connect_until_done → finish:

#![allow(unused)]
fn main() {
use ergo_aeron_cluster::{default_idle, poll_connect_until_done, SessionBuilder};

fn connect(aeron_dir: &str) -> Result<ergo_aeron_cluster::AeronCluster, ergo_aeron_cluster::ClusterError> {
    let builder = SessionBuilder::default()
        .ingress_channel("aeron:udp?endpoint=localhost:9010")?
        .egress_channel("aeron:udp?endpoint=localhost:9020")?;
    let mut connecting = builder.connect_async(aeron_dir);
    let mut idle = default_idle();
    poll_connect_until_done(&mut connecting, &mut idle)?;
    connecting.finish()
}
}

Drive poll / step yourself when you need to inspect connect steps or plug in a custom idle strategy.

No poll waits on the media driver. AsyncClusterConnect::poll adds the egress subscription and ingress publication, and the publication a REDIRECT asks for, with Aeron’s async add and picks them up on later polls. poll_egress handles a NewLeaderEvent the same way: the session stays AwaitingNewLeader until the new leader’s publication has connected, for up to the message timeout. Only the first poll, which creates the Aeron client, can wait, and only while the media driver is not running yet.

Check message sizes once, at start-up: offer takes payloads up to ingress_max_message_length() and try_claim up to ingress_max_payload_length() (when smaller), each less AeronCluster::SESSION_HEADER_LENGTH. A REDIRECT or a new leader re-adds the configured ingress channel, changing only a unicast endpoint (IPC and multicast channels stay as they are), so the limits hold across failover.

Multi-member ingress: ingress_endpoints

For first-connect against a cluster whose current leader isn’t known ahead of time, use ingress_endpoints instead of (or alongside) ingress_channel:

let session = SessionBuilder::default()
    .ingress_endpoints("0=host-a:9010,1=host-b:9010,2=host-c:9010")?
    .egress_channel("aeron:udp?endpoint=localhost:9020")?;

The grammar is member_id=host:port pairs separated by commas — no aeron: prefix, member IDs need not be sorted or contiguous. The setter parses and validates eagerly: a missing =, non-numeric member ID, empty endpoint, empty map, or duplicate member ID fails immediately at the call site rather than at validate() or the first poll().

Egress Listeners

Implement EgressListener and pass it through EgressAdapter to AeronCluster::poll_egress. Use ControlledEgressListener and ControlledEgressAdapter when callbacks must return Aeron controlled-poll actions.

Protocol errors, listener panics, keep-alive failures, publication failures, and reconnect failures are returned as ClusterError. Application payloads, credentials, challenges, and binary response data remain byte slices. Text fields declared by the protocol are validated before being exposed as &str.

The high-level client, configuration, listener, state, error, offer, and claim types are the consumer-facing surface. The generated protocol codecs are also reachable, for advanced direct encode/decode, through the cluster_codec_types module — but that module is #[doc(hidden)] and not a stable API: it exists for repository tests and low-level experimentation, and its shape may change without a semver bump. Normal applications should use AeronCluster.

Multi-Message & Framing

Ergon supports two framing approaches for adjacent messages, and an AnyMessage dispatch enum for multi-message streams where the next type isn’t known until runtime.

Normal Cluster applications use AeronCluster and its egress listeners. The protocol-codec examples below illustrate framing through the repository’s cluster_codec_types test/benchmark seam, which is not a stable consumer API.

Two framing approaches

1. Back-to-back with encoded length

Pre-compute each message’s exact size, lay them out at known offsets, and validate after encoding. Safest when you know all messages ahead of time.

// Size every message from its own payload length.
let len_a = MsgAEncoder::compute_length_with_header(data_a.len());
let len_b = MsgBEncoder::compute_length_with_header(data_b.len());

let mut buf = vec![0u8; len_a + len_b];

// Encode MsgA at offset 0.
let a_len = MsgAEncoder::wrap_and_apply_header(&mut buf[..len_a], 0)
    .fixed(&fields_a)
    .data(data_a)?
    .encoded_length_with_header();
assert_eq!(a_len, len_a);

// Encode MsgB at offset len_a.
let b_len = MsgBEncoder::wrap_and_apply_header(&mut buf[len_a..], 0)
    .fixed(&fields_b)
    .data(data_b)?
    .encoded_length_with_header();
assert_eq!(b_len, len_b);

// Both schemas are known, so their tails determine their message boundaries.
let wire = &buf[..len_a + len_b];

2. Stream / remaining() slot

Write sequentially; use remaining() to find where the next message starts. Idiomatic for Aeron cluster sessions where a SessionMessageHeader is immediately followed by application payload.

use ergo_aeron_cluster::cluster_codec_types::*;

let mut buf = [0u8; SessionMessageHeaderEncoder::compute_length_with_header()
    + SessionKeepAliveEncoder::compute_length_with_header()];

// Encode the outer message. `fixed()` writes the required body so a reused
// buffer cannot publish leftover bytes.
let tail = SessionMessageHeaderEncoder::wrap_and_apply_header(&mut buf, 0)
    .fixed(&SessionMessageHeaderFixedFields {
        leadership_term_id: 7,
        cluster_session_id: 99,
        timestamp: 42,
    })
    .into_remaining_mut();

// into_remaining_mut() returns the unwritten tail.
let keep_alive_len = SessionKeepAliveEncoder::wrap_and_apply_header(tail, 0)
    .fixed(&SessionKeepAliveFixedFields {
        leadership_term_id: 7,
        cluster_session_id: 99,
    })
    .encoded_length_with_header();
assert_eq!(keep_alive_len, SessionKeepAliveEncoder::compute_length_with_header());

// Decode: remaining() gives bytes after the first message.
let smh = SessionMessageHeaderDecoder::decode(&buf, 0)?;
let tail = smh.get_metadata().remaining();
assert_eq!(tail.len(), SessionKeepAliveEncoder::ENCODED_LENGTH);

AnyMessage dispatch

Cluster sessions multiplex many message types on a single stream. AnyMessage::try_decode reads the 8-byte session SBE header, validates its schema identity, and selects the template. For known templates it also checks the acting fixed-body extent. Dynamic tails are checked when consumed:

use ergo_aeron_cluster::cluster_codec_types::*;

fn dispatch(data: &[u8]) -> Result<(), Box<dyn std::error::Error>> {
    match AnyMessage::try_decode(data, 0)? {
        AnyMessage::SessionMessageHeader(decoder) => {
            // This wraps application payload. The application owns its
            // schema; do not recursively dispatch it as Cluster protocol.
            let payload = decoder.get_metadata().remaining();
            println!("application payload: {} bytes", payload.len());
        }
        AnyMessage::SessionEvent(decoder) => {
            let code = decoder.code();
            let (detail, _) = decoder.into_detail_as_str()?;
            println!("event {code}: {detail}");
        }
        AnyMessage::NewLeaderEvent(decoder) => {
            let (endpoints, _) = decoder.into_ingress_endpoints_as_str()?;
            println!("new leader at {endpoints}");
        }
        AnyMessage::Challenge(decoder) => {
            let (chal, _) = decoder.into_encoded_challenge()?;
            println!("challenge: {} bytes", chal.len());
            // respond to challenge...
        }
        AnyMessage::AdminResponse(decoder) => {
            let (msg, after) = decoder.into_message()?;
            let (payload, _) = after.into_payload()?;
            println!("admin response: {msg:?}, {} payload bytes", payload.len());
        }
        AnyMessage::SessionKeepAlive(_) => {
            // heartbeat — nothing to do
        }
        AnyMessage::Unknown { .. } => {
            // Produced by decode_frame when an external length is supplied.
        }
        _ => {
            // Other known session templates are not handled by this example.
        }
    }
    Ok(())
}

SBE headers do not carry a complete message length. try_decode returns UnknownTemplateLength for an unknown template because its tail cannot be located without the schema. Use AnyMessage::decode_frame / FrameCursor with an external frame length when unknown templates must be preserved or skipped. The high-level Cluster client can ignore an unknown protocol message because Aeron already supplies the fragment boundary.

Metadata

Every decoder exposes get_metadata() which returns a Metadata struct:

Metadata remaining() starts immediately after the fixed block. That is the application payload for a fixed-only SessionMessageHeader; for a message with groups or var-data, it starts at that message’s first tail. To locate the next message after a tailed message, complete its staged walk and use the complete stage’s remaining(). Calling the base decoder’s full-length helper instead requires a separate tail scan.

Cluster Compatibility

Supported stacks

Schema identities

These are pinned in cluster/schemas/ and generated by cluster/build.rs. The generated codec API is unstable — use the high-level AeronCluster client, not the cluster_codec_types module directly.

Failure modes

The client handles these documented transitions:

What CI runs against a live cluster

The harness (cluster-test-harness/tests/) runs in ci.yml (aeron-cluster-integration, Aeron 1.53.3, Java 25) and in cluster-compatibility.yml (Aeron 1.46.8, Java 21, when cluster/ or sbe/src/ changes).

Not covered by the harness: auth challenge and rejection, controlled-poll abort, and connect or poll timeout expiry. Unit tests in cluster/src/ (run by ci.yml’s test job) cover challenge dispatch (egress.rs), the challenge response (credentials.rs, client.rs) and the new-leader timeout (client.rs, test_new_leader_timeout_disconnects). No test drives ClusterError::AuthRejected, a controlled-poll abort, or a connect or poll timeout.

Limitations

• No dynamic membership (static cluster only).
• No snapshot/recovery integration.
• No TLS/mTLS at the Aeron transport layer.
• The cluster_codec_types module is #[doc(hidden)] and not stable API.

ergon-io

Network I/O for an exchange client on one busy-spinning thread: WebSocket and HTTP/1.1 over TLS 1.3.

• The driver is Linux-only; the protocol code builds everywhere.
• Written with heavy AI assistance (disclosure). Not production-ready.

cargo add ergon-io --features webpki-roots

• Features: uring (on by default) adds the io_uring backends; webpki-roots adds Mozilla’s root store (tls::webpki_roots); curl adds libcurl as an HttpClient implementation.
• API reference: docs.rs/ergon-io.
• Every measured figure, with its max and its data file: io/benches/BENCHMARK.md (its first table answers the common questions).

Glossary

Terms this chapter uses. Each links to the section that explains it.

When to use it

How it works

• Driver<E> owns the connections. Driver::poll makes one non-blocking pass (receive, decrypt, decode, deliver, send) and returns.
• Your handler gets Handler::on_open, on_closed, and the protocol’s callback, such as WsHandler::on_message. A payload is a slice of the receive buffer, valid during the call.
• One failure closes one connection. It goes to on_closed; the others keep running. poll fails only when the backend fails.
• Resources are owned. A socket closes when its connection drops. Dropping a Driver cancels in-flight io_uring work before freeing its buffers.

Pages: WebSocket (a complete client), HTTP client, Backends and configuration, Rate limits and errors, Kubernetes (where the helper threads run inside a pod).

Choosing a backend

The backend is configuration: Config::parse("recv-busy"). Count every socket the loop thread polls: WebSocket feeds, order connections and every HttpClient pool connection (each Driver and HttpClient on the thread adds its own). Then pick by what CPUs you have:

Evidence: fair run, Graviton (all six backends, 1–64 sockets, HTTP pool of 1 and 20) and polling backends, x86 (1–256 connections).

• Plain recv-busy reads every socket on every poll. Its poll grows with sockets, so a message waits longer for its socket’s turn. It leads at 1 socket and falls behind from about 16.
• per_queue reads one socket per NIC queue, then the ready ones. Its poll stops growing at the queue count. It trails uring-sqpoll at 16–64 sockets. Not the default: set it when the count can pass 4.
• The interrupt backends (epoll-spin, uring-spin, mio) matched uring-sqpoll from 4 sockets in the fair run, which had moderation off and their interrupts on a core of their own. Both are node settings; a pod cannot set them. With the interrupts on the loop’s CPU their p99 rose from 4 sockets.
• One physical core with two hyperthreads: uring-sqpoll with the SQPOLL thread on the loop’s sibling (the default in a cpu: 2 x86 pod: Kubernetes).
• The loop’s CPU time in the kernel matters: uring-spin. It equals epoll-spin’s latency with thousands of times fewer syscalls (data).
• Many streams on one exchange: pack them onto a few combined-stream connections; fewer sockets decode sooner.
• uring-napi, epoll-busy poll the NIC inside a timed wait, then sleep. In the one run they trailed uring-sqpoll and spent most of the loop’s time in the kernel (data).
• How each one waits, every key, and how to find the crossover on your own host: Backends and configuration.

Connecting

The loop’s worst poll per connect, both ways: connection set-up.

• TLS 1.3 only. TLS 1.2 is refused with a clear error.
• Trust is the rustls configuration you pass (tls::client_config(roots)); feature webpki-roots adds Mozilla’s roots.
• Which TLS stack: the in-place tls::RecordLayer, on every native connection. rustls does the handshake (UnbufferedClientConnection, then dangerous_into_kernel_connection); the custom layer then does the record cryptography in place in the receive buffer, no allocation per record. Native connections (TlsStream, WsConn) take it unconditionally — there is no stock-rustls record path to choose. The layer owns the record cryptography that rustls would own after the handshake: post-handshake messages, key updates and the cipher’s confidentiality limit. Its effect on a whole request is not measured (only a decrypt-only microbench exists).

Defaults

• TCP settings apply on Driver::connect, connect_background and add. HttpClient’s libcurl connections get TCP_NODELAY, keepalive and TCP_USER_TIMEOUT too.
• Keepalive adds one kernel timer per socket. For a WebSocket-only loop, Pings already find a dead server: keepalive_idle_s=0 is an option.

What it checks for you

• Driver::new checks the loop’s CPU (ergon-tune): isolation (T1), transparent hugepages (T3), scheduling policy (T7), SMT sibling (T8), and a CPU quota on the process’s cgroup (T9).
• Each egress device, from a warning thread: NIC interrupts on the loop’s CPU (T2), ENA adaptive moderation (N1), deferred interrupts with no busy poller (N2), an Azure VF that is down (N3).
• Each route, once, for quick ACK. Default: one warning with the exact ip route change that fixes it. quickack_check=require refuses the connection before its TLS handshake. The latency effect of quick ACK is not measured here.
• Each finding prints once, with its fix, never from the polling thread.

Best practice

Node-level means the setting is on the host, not in the pod spec (deployment: Kubernetes).

Measured with no consistent effect: SCHED_FIFO for the loop, one NIC queue, capped idle states. Not measured here: route quickack and rto_min, prefer_busy_poll, busy_poll_budget.

Verify

cargo test -p ergon-io -- --test-threads=1
cargo clippy -p ergon-io --all-targets -- -D warnings

Measured results

Every figure, with its max and its data file: io/benches/BENCHMARK.md. WebSocket and HTTP round trips: WebSocket, HTTP client.

Backends and Configuration

A backend is the kernel interface the Driver waits and reads with. It is configuration, so one binary can run with each. Which to pick: Choosing a backend.

• epoll_wait(0) never blocks, but never polls the NIC either. mio, and so tokio, is this path too.
• Plain recv-busy reads every socket on every poll, so each socket adds a little to every poll. per_queue reads one socket per NIC queue instead: see cost per poll.
• uring-sqpoll costs a spinning kernel thread per ring. Rings in one process can share one; other processes cannot. Its kernel thread polls each NIC queue once per pass, so it has no per-socket scan.

Configuration strings

backend[,key=value...], parsed and checked by Config::parse:

#[test]
fn keys_override_defaults() -> R {
    let c =
        Config::parse("uring-sqpoll, sqpoll_cpu=3, busy_poll_us=2, rcvbuf=0, rx_timestamps=false")?;
    assert_eq!(c.backend, Backend::UringSqpoll);
    assert_eq!(c.sqpoll_cpu, Some(3));
    assert_eq!(c.busy_poll_us, 2);
    assert_eq!(c.rcvbuf, None);
    assert!(!c.rx_timestamps);
    Ok(())
}

(From io/tests/backend_config.rs; cargo test -p ergon-io runs it on every platform.)

An unknown key, a bad value or a setting the backend cannot use is an error (Config::validate), never ignored.

The four one-core backends

recv-busy, recv-busy,per_queue, epoll-spin and uring-spin run on the loop’s CPU alone: no SQPOLL kernel thread. uring-sqpoll is the only backend that needs another CPU; it is not in this section. The interrupt backends (epoll-spin, uring-spin) were measured with the NIC’s interrupts on a core of their own; on the loop’s CPU their p99 rose from 4 sockets (fair run).

/// The four backends that cost one core each. `uring-sqpoll` is not here:
/// its SQPOLL kernel thread spins on a CPU of its own.
#[test]
fn the_one_core_backends() -> R {
    // recv-busy: one recvmsg per socket per poll. Best at 1-4 sockets.
    let plain = Config::parse("recv-busy")?;
    assert_eq!(plain.backend, Backend::RecvBusy);
    assert!(!plain.per_queue);

    // per_queue: one busy-polled read per NIC queue, then only the sockets
    // epoll_wait(0) reports ready. The same latency as plain at 1-16 sockets,
    // and the only one-core choice still flat at 256.
    let queued = Config::parse("recv-busy,per_queue=true")?;
    assert_eq!(queued.backend, Backend::RecvBusy);
    assert!(queued.per_queue);
    assert_eq!(queued.busy_poll_us, 1);

    // epoll-spin: epoll_wait(0), then recvmsg on the ready sockets. Cheapest
    // per socket, but it waits for the NIC interrupt.
    let epoll = Config::parse("epoll-spin")?;
    assert_eq!(epoll.backend, Backend::EpollSpin);
    assert!(!epoll.per_queue);

    // uring-spin: IORING_OP_RECVMSG with DEFER_TASKRUN. The fewest syscalls of
    // any spin loop; also interrupt-driven.
    let uring = Config::parse("uring-spin")?;
    assert_eq!(uring.backend, Backend::UringSpin);
    assert!(!uring.per_queue);

    Ok(())
}

(From io/tests/backend_config.rs; cargo test -p ergon-io runs it on every platform.)

What one poll does:

Which one to take: choosing a backend.

per_queue: one read per NIC queue

Plain recv-busy calls recvmsg on every socket every poll. Each call runs one NAPI busy-poll pass even when the socket is idle, so almost all of those reads return nothing and much of the core sits in the kernel. A message then waits for its socket’s turn, half a poll on average and up to a whole one.

per_queue changes the scan. It reads one socket per NIC queue (that read polls the queue), then calls epoll_wait(0) and reads only the sockets that are ready. The cost stops growing at the queue count.

As struct fields, for when more than one setting changes:

/// The same choice as struct fields, for when more than one setting changes.
#[test]
fn per_queue_as_struct_fields() {
    let mut cfg = Config::new(Backend::RecvBusy);
    cfg.per_queue = true; // one read per NIC queue, then epoll_wait(0)
    cfg.busy_poll_us = 1; // one NAPI pass per empty read
    cfg.rcvbuf = Some(4 << 20);

    assert!(cfg.per_queue);
    assert_eq!(cfg.busy_poll_us, 1);
    assert_eq!(cfg.rcvbuf, Some(4 << 20));
}

It is recv-busy and nothing else. On any other backend it is a parse error, never ignored:

    for bad in [
        "epoll-spin,per_queue=true",   // error
        "uring-spin,per_queue=true",   // error
        "uring-sqpoll,per_queue=true", // error
        "recv-busy,per_queue=1",       // error: not true/false
    ] {
        assert!(Config::parse(bad).is_err(), "{bad:?} accepted");
    }

On the lab command line:

# plain: one recvmsg per socket per poll
io_bench lab --variants recv-busy --cpus 2 --busy-poll 1 --wait-us 0 \
  --server SENDER:9447 --conns 100 --duration 60 --out res/c100-recv-busy

# per_queue: one read per NIC queue, then the ready sockets
io_bench lab --variants recv-busy --per-queue --cpus 2 --busy-poll 1 --wait-us 0 \
  --server SENDER:9447 --conns 100 --duration 60 --out res/c100-per-queue

$B/analyse --warmup-s 2 res/c100-*

Measured against plain recv-busy and uring-sqpoll at 1–256 connections: polling backends.

Kernel

An older kernel gives Error::Unsupported from Driver::new.

Host settings

The loop is only as quiet as its core. What mattered on AWS and Azure, for x86 and Graviton: Deployment: AWS and Azure hosts. ergon-io’s own checks (ergon-tune) report what is missing at start-up.

Cost per poll

One poll is 1 ÷ the loop’s polls per second. Measured poll times: polling backends.

One poll per backend. Where the NIC’s NAPI pass runs is what separates them:

flowchart TD
    P["one Driver::poll"]
    P --> RB["recv-busy"]
    P --> ES["epoll-spin"]
    P --> US["uring-spin"]
    P --> SQ["uring-sqpoll"]

    RB --> RB1["recvmsg on every socket"]
    RB1 --> RB2["NAPI pass per socket, even idle"]
    RB2 --> RB3["cost grows with sockets"]

    ES --> ES1["epoll_wait(0)"]
    ES1 --> ES2["recvmsg on ready only"]
    ES2 --> ES3["interrupt path, no NIC poll"]

    US --> US1["submit RECVMSG"]
    US1 --> US2["DEFER_TASKRUN complete"]
    US2 --> US3["interrupt path, no NIC poll"]

    SQ --> SQ1["SQPOLL kernel thread"]
    SQ1 --> SQ2["polls each NIC queue"]
    SQ2 --> SQ3["NAPI pass per queue"]

recv-busy,per_queue sits between the first two: one busy-polled read per NIC queue (so one NAPI pass per queue), then epoll_wait(0) and only the ready sockets. Its cost stops at the queue count.

• Plain recv-busy grows with sockets: each non-blocking recvmsg runs one NIC busy-poll pass even on an idle socket, so most reads return nothing and the core sits in the kernel.
• What it costs in latency: a message waits for its socket’s turn, half a poll on average and up to a whole poll.
• per_queue reads one socket per NIC queue (which polls that queue), then only the ready sockets. Its poll stops growing at the queue count.
• epoll-spin and uring-spin do not scan idle sockets; they wait for the NIC interrupt instead. Against the polling backends: fair run.
• Where each polling backend stops winning: choosing a backend.

Find the crossover on your own host

The crossover depends on the NIC, its queue count, the interrupt path and the traffic. Measure it with the lab tools in io/benches, on two hosts: the many-connection market-data test the tables above come from, once per backend, at your socket count (here 20).

cargo build --release --manifest-path io/benches/Cargo.toml --bin replay_server --bin io_bench --bin analyse
B=io/benches/target/release

# sender: one stream per connection; restart it before each run, copy cert-many.pem to the receiver
sudo $B/replay_server --listen 0.0.0.0:9447 --cert-out cert-many.pem --clients 20 --mode mixed --cpu 1 --duration 120 \
  --trickle-min-us 1000 --trickle-max-us 10000 --burst-every-us 2000 --burst-slots 10 --burst 10 --seed 42

# receiver, loop on isolated CPU 2
sudo $B/io_bench lab --variants recv-busy --cpus 2 --busy-poll 1 --wait-us 0 --server SENDER:9447 \
  --ca cert-many.pem --sni lab.local --conns 20 --capacity 8000000 --duration 60 --out res/c20-recv-busy
# then the same with --variants recv-busy --per-queue (out res/c20-per-queue),
# --variants epoll-spin (res/c20-epoll-spin), --variants uring-sqpoll --sqpoll-cpu 3 (res/c20-sqpoll)

$B/analyse --warmup-s 2 res/c20-*

• Compare the backends’ sender → decoded p50, p99 and max within the same session, and repeat in reversed order: the two clocks drift.
• On AWS, set the NIC on the node before each run (node-level): ethtool -C <nic> adaptive-rx off rx-usecs 0, with the NIC’s interrupts on a core of their own, as in the fair run. Otherwise the interrupt backends wait for moderation.
• HTTP with a pool: HTTP with many connections.
• Everything about the method: io/benches/BENCHMARK.md.

WebSocket

WsConn is a TLS 1.3 WebSocket client that a Driver owns.

• Frames are parsed in place: WsHandler::on_message gets a slice of the buffer the kernel wrote into (one copy per byte).
• RxMeta carries the read’s kernel receive timestamp and, where the NIC has one, its hardware timestamp.
• Timers (Pings, timeouts, the close wait) run on the driver’s deadline check (every 250 µs), never on the read or send path.

A complete client

Connect, subscribe, print each message, reconnect and subscribe again after a drop, then close cleanly:

use ergon_io::reconnect::{Closed, LinkId, LinkState, Retry};
use ergon_io::{ConnId, Error, Handler, Reconnect, RxMeta, WsDial, WsHandler};

/// Sent on every connect and reconnect.
pub const SUBSCRIBE: &str = r#"{"method":"SUBSCRIBE","params":["btcusdt@bookTicker"],"id":1}"#;

/// The application. `Driver::poll` calls it.
pub struct App {
    /// Keeps the connection open: reopens it with backoff after a drop.
    pub links: Reconnect<WsDial>,
    /// The one link (a connection that `links` keeps open).
    pub link: LinkId,
    /// Connections opened during the last poll: subscribe on them.
    opened: Vec<ConnId>,
    /// Close after this many messages.
    pub limit: u64,
    /// Messages received.
    pub messages: u64,
    /// Connections opened; more than 1 means it reconnected.
    pub opens: u32,
}

impl App {
    /// `dial` builds a fresh connection set-up for each attempt.
    ///
    /// # Errors
    /// `retry` is out of range.
    pub fn new(
        retry: Retry,
        dial: impl FnMut() -> ergon_io::Result<WsDial> + 'static,
        limit: u64,
    ) -> ergon_io::Result<Self> {
        let mut links = Reconnect::new(retry)?;
        let link = links.add(dial);
        Ok(Self {
            links,
            link,
            opened: Vec::new(),
            limit,
            messages: 0,
            opens: 0,
        })
    }

    /// Closed cleanly, or the link gave up.
    #[must_use]
    pub fn finished(&self) -> bool {
        matches!(
            self.links.state(self.link),
            Some(LinkState::Stopped | LinkState::GaveUp)
        )
    }
}

impl Handler for App {
    fn on_open(&mut self, id: ConnId) {
        if let Some(opened) = self.links.on_open(id) {
            self.opens += 1;
            if opened.reconnect {
                println!("reconnected: subscribing again");
            }
            // Sends wait until `poll` returns: remember the connection.
            self.opened.push(id);
        }
    }

    fn on_closed(&mut self, id: ConnId, error: Error) {
        println!("closed: {error}");
        if let Some(Closed::Retry { delay_ms, .. }) = self.links.on_closed(id) {
            println!("reconnecting in {delay_ms} ms");
        }
    }
}

impl WsHandler for App {
    fn on_message(&mut self, _: ConnId, _: u8, payload: &[u8], _: &RxMeta, _: u16) {
        // `payload` points into the receive buffer: use it during this call only.
        println!("{}", std::str::from_utf8(payload).unwrap_or("<binary>"));
        self.messages += 1;
    }
}

/// The loop: runs until the clean close, or until the link gives up.
///
/// # Errors
/// The backend failed. A connection that fails goes to `on_closed` instead.
#[cfg(target_os = "linux")]
pub fn run(config: ergon_io::Config, app: &mut App) -> ergon_io::Result<()> {
    use ergon_io::{Driver, WsConn};

    let mut driver: Driver<WsConn> = Driver::new(config)?;
    let mut closing = false;
    while !app.finished() {
        driver.poll(app)?; // receive, decrypt, deliver, send
        app.links.poll(&mut driver); // start a reconnect when one is due
        for id in app.opened.drain(..) {
            // A connection the server is already closing takes no sends.
            if let Some(mut conn) = driver.get_mut(id)
                && !conn.is_closing()
            {
                conn.send_text(SUBSCRIBE)?;
            }
        }
        if app.messages >= app.limit && !closing {
            closing = true;
            app.links.stop(app.link); // no reconnect after this close
            if let Some(LinkState::Open(id)) = app.links.state(app.link)
                && let Some(mut conn) = driver.get_mut(id)
                && !conn.is_closing()
            {
                // `on_closed` follows once the server answers.
                conn.close(1000, "done")?;
            }
        }
    }
    Ok(())
}

#[cfg(all(target_os = "linux", feature = "webpki-roots"))]
fn main() -> Result<(), Box<dyn std::error::Error>> {
    use ergon_io::{Config, Target, WsOptions, tls};

    let mut args = std::env::args().skip(1);
    let limit: u64 = args.next().map_or(Ok(20), |a| a.parse())?;
    let config = Config::parse(&args.next().unwrap_or_else(|| "recv-busy".into()))?;
    // In production, pin this thread to an isolated core first.
    let tls = tls::client_config(tls::webpki_roots())?;
    let target = Target::new("stream.binance.com", 9443, "/ws");
    // Limits, pings and timeouts: WsOptions.
    let dial = move || WsDial::with_options(target.clone(), tls.clone(), WsOptions::default());
    let mut app = App::new(Retry::default(), dial, limit)?;
    run(config, &mut app)?;
    println!("{} messages, {} connection(s)", app.messages, app.opens);
    Ok(())
}

(From io/examples/websocket.rs. cargo test -p ergon-io builds it, and io/tests/example_websocket.rs runs it against a local server on every backend: a server close, the reconnect, the second subscribe and the clean close.)

Run it (Linux):

cargo run -p ergon-io --features webpki-roots --example websocket -- 20 recv-busy

• Arguments: messages to print before closing, then the backend configuration.
• The feed is Binance’s public spot stream; any public feed will do.

Options

WsOptions, on WsDial::with_options or WsConn::connect_with:

• Any byte received after a Ping counts as the answer, not only a Pong.
• Server Pings are answered at once.

Close

• Data that arrives after a server Close is dropped.
• A protocol error drops the connection (RFC 6455 allows it): no Close 1002.

Reconnect

Reconnect is optional. You own it (in your handler, as in the example) and feed it every open and close.

• on_open(id) returns Opened { link, reconnect }: subscribe either way; with reconnect, resync any state kept from the old connection.
• on_closed(id) returns the next step: Retry, GaveUp or Stopped.
• stop(link) vetoes reconnects; resume(link) starts again.
• Driver::close reports nothing: call on_closed(id) yourself after it.
• poll starts due attempts. It costs one branch while nothing waits.

Connect limits and the server’s wait

Venues limit connect attempts per IP (Binance: 300 per 5 minutes; OKX: 3 per second). One Budget bucket is the gate of every link on that IP:

    // Connect attempts per IP: 3 per second (OKX). One bucket, the gate of
    // every WebSocket link on that IP.
    let mut budget = Budget::new(vec![BucketSpec::rolling("ws-connects", 3, 1_000, 10)])?;
    let connects = budget.id("ws-connects").ok_or("no bucket")?;
    let mut links = Reconnect::new(Retry::default())?;

        // Once per loop pass; `now` is the budget's clock, read once.
        let started = links.poll_at_gated(&mut f, now, || {
            budget
                .try_charge(&[Charge::new(connects, 1)], Class::Normal, now)
                .map(drop) // passed: connect now
                .map_err(|l| l.wait_ns(now)) // refused: ask again after this
        });

(From io/tests/reconnect.rs, which cargo test -p ergon-io runs on every platform, with a stand-in connector and a fake clock.)

• poll_gated(driver, gate) starts an attempt only when the gate passes it, the first attempt after add included: 50 links added at once start at the gate’s pace, not in one burst.
• A refusal is not a failed attempt: the backoff does not grow. The link asks again after the gate’s wait, at most max_ms later.
• Each pass starts after the last link the gate passed, so links that keep failing cannot starve the others.
• defer(link, wait_ns): no attempt before then. It stays with the link across later closes and resume.

A refused handshake, in on_closed:

    // Binance's documented minimum for a 418: 2 minutes.
    let ban_min = NonZeroU64::new(120_000).ok_or("zero")?;
    // In `Handler::on_closed(id, error)`: a refused handshake holds the
    // connect bucket (429) or halts it (418), and the link waits it out.
    let on_closed = |rc: &mut Reconnect<u32>, budget: &mut Budget, id, error: &Error, now| -> R {
        let link = rc.link_of(id).ok_or("not a link")?;
        if let Some(Verdict::Throttled { until_ns, .. } | Verdict::Banned { until_ns, .. }) =
            outcome::refused_upgrade(
                error,
                connects,
                budget,
                ban_min,
                Now {
                    ns: now,
                    real_ns: now,
                },
            )?
        {
            rc.defer_at(link, u64::try_from(until_ns - now)?, now);
        }
        rc.on_closed_at(id, now);
        Ok(())
    };

• 429: the bucket is held for Retry-After (or its backoff without one).
• 418: the bucket is halted. No link on that IP connects again until a person calls Budget::clear_halt, even after the server’s wait.
• Give the HTTP pool a bucket of its own (HTTP client): venues count WebSocket connects.

Sending

• send_text, send_binary, ping, or send_frame(opcode, payload).
• A message larger than one TLS record goes out over several.
• On a driver-owned connection: driver.get_mut(id), then the same methods.
• Sends go out on the next poll, or at once with Driver::flush.
• Handlers cannot send (they have no driver): remember the id, send after poll returns (as the example does).
• stats().auto_frames counts the frames the connection sends by itself: Pongs, Pings on a quiet connection, the echo of a server Close. A venue that limits messages per connection may count them (Binance spot does): charge the change each pass with Budget::force.

Handshake

• Checks status 101, Upgrade, Connection and Sec-WebSocket-Accept.
• Any other status is Error::Upgrade { status, retry_after_ms, .. }: a 429 or 418 can be told apart, and retry_after_ms is the server’s Retry-After (seconds or a date). Wait at least that long before connecting again: outcome::refused_upgrade and Reconnect::defer (see Reconnect).
• Refuses a subprotocol it did not offer.
• Offers no extension and refuses a server that picks one.
• Extra headers (auth, say) go on the Target: Target::new(host, port, path).with_header(name, value).

Not supported

• Compression (permessage-deflate) and other extensions: decompressing breaks in-place parsing and costs CPU per message.
• Proxies.
• Sending fragmented messages (receiving them works).

Measured results

Order round trip: a 64-byte echo, one message in flight. Every figure, with its max:

• Fair run, Graviton: all six backends with 1, 4, 16 and 64 sockets on the loop.
• Round trips on x86: 1 connection.

Pick the backend by the total socket count on the loop, feeds included: choosing a backend.

HTTP client

HttpClient keeps a pool of warm HTTP/1.1 connections behind one API. The implementation is configuration:

• Same code for both: switching is a configuration change.
• Linux only (like the Driver).
• One level down, HttpConn is a single keep-alive connection on your own Driver (the API reference has it).

Example

The handler gets every result, keyed by request id:

#[derive(Default)]
struct Seen {
    ok: Vec<(u64, u16, String)>,
    errors: Vec<(u64, Sent, String)>,
}

impl ClientHandler for Seen {
    fn on_response(&mut self, request: u64, r: &Response<'_>) {
        self.ok.push((
            request,
            r.status,
            String::from_utf8_lossy(r.body).into_owned(),
        ));
    }
    // `Sent::No`: the server cannot have seen it; `Sent::Maybe`: it may
    // have run (reconcile an order by its client order id).
    fn on_error(&mut self, request: u64, sent: Sent, error: Error) {
        self.errors.push((request, sent, error.to_string()));
    }
}

Native:

/// The native implementation: `recv-busy`, connections opened in the
/// background.
fn native(lab: &Lab) -> R<HttpClient> {
    let mut cfg = HttpClientConfig::new(HttpImpl::Native);
    cfg.pool = 2; // warm connections, one request in flight each
    // A pod with one CPU has no core for the connect helper: opt in to
    // opening on the loop there (without this, `new` returns `Error::Cpu`).
    cfg.driver.inline_connect_fallback = true;
    let client = HttpClient::new(&cfg, lab.target("")?, lab.client_cfg.clone())?;
    Ok(client)
}

libcurl:

/// libcurl (feature `curl`): the same API. Without the feature, `new`
/// returns `Error::Unsupported`.
fn curl(lab: &Lab) -> R<HttpClient> {
    let mut cfg = HttpClientConfig::new(HttpImpl::Curl);
    cfg.pool = 2; // the most connections libcurl may use at once
    cfg.curl_ca_file = Some(lab.ca_file()?.display().to_string()); // libcurl's trust store
    let client = HttpClient::new(&cfg, lab.target("")?, lab.client_cfg.clone())?;
    Ok(client)
}

One request, the same code for both:

/// One GET, the same code for both implementations: wait for a free
/// connection, send, then poll until the answer.
fn get(client: &mut HttpClient, path: &str) -> R<(u16, String)> {
    let mut seen = Seen::default();
    let end = Instant::now() + Duration::from_secs(10);
    while client.idle() == 0 {
        client.poll(&mut seen)?; // the pool connects in the background
        if Instant::now() > end {
            return Err("no connection".into());
        }
    }
    let id = client.request("GET", path, &[], &[])?; // returns at once
    while seen.ok.is_empty() && seen.errors.is_empty() {
        client.poll(&mut seen)?; // one non-blocking pass
        if Instant::now() > end {
            return Err("no answer".into());
        }
    }
    let (got, status, body) = seen.ok.pop().ok_or_else(|| format!("{:?}", seen.errors))?;
    assert_eq!(got, id);
    Ok((status, body))
}

(From io/tests/client.rs. cargo test -p ergon-io runs get through the native client against a local TLS server on Linux; with --features curl, through libcurl too. lab is that server: in your code use Target::new("api.binance.com", 443, "") and tls::client_config(tls::webpki_roots())?.)

Rules

• One request in flight per connection. All busy: Error::Busy at once, no hidden queue. Each pooled connection is one more socket the loop polls: read many connections before sizing pool.
• A timed-out request closes its connection (request_timeout_ms, 5 s): HTTP/1.1 cannot drop one request on a live connection. The pool opens a replacement. Both implementations report it as Error::Timeout("http request").
• A failed request says whether it was sent: on_error(request, sent, error).
  • Sent::No: the request never reached the kernel whole, so the server cannot have seen it. Safe to send again.
  • Sent::Maybe: it may have run. Look an order up by its client order id; never send it again blindly.
• libcurl takes no method but GET, HEAD, OPTIONS and DELETE (Error::CurlResend) unless curl_allow_non_idempotent_methods is set. Why: libcurl sends a request again, up to 5 times, when the reused connection it went out on dies before any reply byte, so an order could be placed twice (io/tests/client.rs shows it happening). The native client never re-sends: send orders through it.
• Connections open in the background (background_connect, on by default): the handshake runs off the loop, unless the driver’s inline_connect_fallback is set. A failed connect goes to ClientHandler::on_connect_error and is retried with backoff.
• Reconnects spread out: a dropped connection reopens after a random delay of up to 100 ms (the limit doubles per failed connect, up to 5 s), so connections that drop together do not reconnect together. reconnect_seed fixes the delays (tests).
• A venue’s connect limit (native only): with connect_gate, new opens nothing and every connect waits for the gate passed to poll_gated; poll then refuses. A refusal does not grow the backoff. Give the pool a Budget bucket of its own: venues’ connect limits count WebSocket connects.
• buf_size (1 MiB) is each native connection’s receive buffer: it must hold the largest response.
• Responses: Content-Length or chunked bodies. The body in on_response borrows the client’s buffer: copy what you keep.
• libcurl: curl_drive picks curl_multi_perform on every poll (default) or curl_multi_socket_action; both never block. Compared once on Azure at 1,000/s: curl_multi_perform was 1–6 µs ahead at the median in both rounds and had the higher max (data). Trust comes from curl_ca_file or the system store, not from the rustls configuration.

Signing

Signer signs request parameters as Binance’s signed endpoints expect, without allocating. HttpClient::signed_request appends the timestamp and the signature itself; signed_request_at takes the timestamp from you (your clock, or replay time).

Cost per signature: request signing.

Checked against Binance’s documented example:

/// Binance "SIGNED endpoint" example (HMAC-SHA256, parameters in the query).
const SECRET: &str = "NhqPtmdSJYdKjVHjA7PZj4Mge3R5YNiP1e3UZjInClVN65XAbvqqM6A7H5fATj0j";
const PARAMS: &str =
    "symbol=LTCBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000";
const TS: u64 = 1_499_827_319_559;
const SIGNATURE: &str = "c8db56825ae71d6d79447849e617115f4a920fa2acdcab2b053c4b2838bd6b71";

#[test]
fn hmac_matches_binance_documented_example() -> R {
    let signer = Signer::hmac_sha256(SECRET.as_bytes());
    assert_eq!(signer.kind(), SignatureKind::HmacSha256);
    let mut out = Vec::new();
    auth::append_signed_params(&mut out, PARAMS, TS, &signer);
    let expected = format!("{PARAMS}&timestamp={TS}&signature={SIGNATURE}");
    assert_eq!(String::from_utf8(out)?, expected);
    Ok(())
}

(From io/tests/auth.rs; cargo test -p ergon-io runs it on every platform.)

• Set the API key once as a header: Target::with_header("X-MBX-APIKEY", key).

Measured results

Every figure, with its max: HTTP clients (1 connection, x86) and the fair run (pool of 1 and 20, Graviton).

• Native against libcurl, same interrupt path: native is ahead at the median on Azure and AWS. Its p99 and max are lower on Azure, not on AWS.
• HttpClient with a pool of 1 was within 1 µs of a raw HttpConn at the median and p99; one of its rounds had a higher max.
• reqwest parks its thread between requests and trailed both on Azure.

Many connections

Measured on Graviton with a pool of 20 on one loop, one request in flight (fair run): uring-sqpoll and the interrupt backends lead, per_queue is behind them and plain recv-busy further behind.

• Count the pool with every other socket the thread polls: feeds, order connections, other pools. Each HttpClient has its own Driver, so its poll adds to theirs. Then pick: choosing a backend.
• Set it with HttpClientConfig::driver, for example Config::parse("recv-busy,per_queue=true")?.

Measure it on your own two hosts with io/benches: one run per backend, and --pool 1 as the reference.

cargo build --release --manifest-path io/benches/Cargo.toml --bin replay_server --bin http_bench --bin analyse
B=io/benches/target/release

# sender: a keep-alive HTTP server; copy cert-http.pem to the receiver.
# It spins one thread per connection: run it unpinned, with more free CPUs than connections.
sudo $B/replay_server --listen 0.0.0.0:9445 --cert-out cert-http.pem --mode http --busy-poll 50

# receiver, loop on isolated CPU 2: 20 pooled connections, one request in flight, 10,000/s
sudo $B/http_bench --client client --backend recv-busy --pool 20 --server SENDER:9445 --ca cert-http.pem \
  --sni lab.local --cpu 2 --rate 10000 --duration 60 --out res/http20-recv-busy
# then the same with: --backend recv-busy --per-queue (out res/http20-per-queue),
# --backend epoll-spin (res/http20-epoll-spin), --backend uring-sqpoll --sqpoll-cpu 3 (res/http20-sqpoll)

$B/analyse --warmup-s 2 res/http20-*

• On AWS, set the NIC on the node first (node-level): ethtool -C <nic> adaptive-rx off rx-usecs 0, with the NIC’s interrupts on a core of their own, as in the fair run.
• Compare p50, p99 and max per backend; repeat in reversed order.

Rate Limits and Errors

Venues limit how fast you send. Break a limit and they refuse requests; keep going and they ban your IP. ergon-io checks each request against the limits before it goes out, and tells you what became of it after.

• It never sleeps, queues or retries. You decide: wait, drop or alert.
• No venue tables in the published crate: venues change them without notice. Binance, Bybit and OKX adapters live in the repository’s io/examples/venues.rs.

What venues do

Checked 2026-10-17 against each venue’s docs (linked). Values change: load them at start where the venue publishes them (Binance exchangeInfo). Where a number is not on the linked page, the source is named in the cell.

• One order counts against several limits at once: a Binance order against IP weight, raw requests, orders per 10 s and orders per day.
• Errors often come as HTTP 200 with a code in the body (Bybit, OKX). Classify on status and code.
• WebSocket limits count control frames (Binance spot: 5 messages/s, Pongs included) and connect attempts per IP (Binance 300/5 min, OKX 3/s).
• HTTP status is not the code. The same body code can arrive with 200, 429 or another status: read the code.

What ergon-io gives you

One order, start to end

A Binance adapter: limits at start, the charge before sending, the verdict after:

    // At start: Binance's limits from `GET /api/v3/exchangeInfo`.
    let limits = binance::limits(example::BINANCE_EXCHANGE_INFO.as_bytes())?;
    let (b, mut budget) = binance::Binance::new(limits)?;
    // Before sending: every bucket the order counts against, or none.
    let ticket = budget.try_charge(b.new_order()?.as_slice(), Class::Normal, T0)?;
    // On its response (`on` replays a recorded one): usage, then the verdict.
    let v = on(example::BINANCE, "order-ack", |r| {
        b.on_response(r, &mut budget, NOW)
    })??;

What it reads in a response:

            match r.status {
                // Bans (403: the WAF limit, 418): the IP scope stops until a
                // person clears it. Before any header: a ban always halts.
                // The gate every request and every connect charges, so one
                // ban stops them all.
                403 | 418 => return super::ban(r, self.ip, BAN_MIN_MS, budget, now),
                _ => {}
            }
            let code = match super::json_body(r)? {
                Some(body) if r.status >= 400 => {
                    body.get("code")?.map(json::Value::as_i64).transpose()?
                }
                _ => None,
            };
            // 409 cancel-replace: -2022 ran nothing (both halves failed);
            // -2021 may have run one half.
            if r.status == 409 {
                return Ok(match code {
                    Some(-2022) => Verdict::NotRun,
                    _ => Verdict::Unknown,
                });
            }
            let verdict = match code {
                Some(-1003) => {
                    // "Too many requests queued." is a queue depth, not the
                    // weight window: filling the weight bucket would stop
                    // everything on the IP for a whole window. The queued
                    // variant holds the raw-requests scope, else a short hold
                    // on weight that does not fill it.
                    if super::contains_ignore_case(r.body, b"queued") {
                        if let Some(raw) = self.raw {
                            super::throttle(r, raw, budget, now)
                        } else {
                            let wait = outcome::retry_after_ms(r, super::utc_ms(now))?.or(Some(0));
                            let until_ns = budget.throttled(self.weight, wait, now.ns)?;
                            Ok(Verdict::Throttled {
                                bucket: self.weight,
                                until_ns,
                            })
                        }
                    } else {
                        super::throttle(r, self.weight, budget, now)
                    }
                }
                Some(-1015) => self.too_many_orders(r, budget, now),
                Some(-1021) => Ok(Verdict::ClockSkew),
                // -1006, -1007 and -1008: -1006/-1007 lost track of the
                // request; spot -1008 is only "server is currently
                // overloaded" and does not say the order failed. All three
                // mean it may have run.
                Some(-1008..=-1006) => Ok(Verdict::Unknown),
                // Status alone: 2xx done, 429 throttled, 4xx rejected, 5xx unknown.
                _ => outcome::generic(r, self.weight, budget, now),
            }?;
            // Server truth, after the hold or halt stands: other senders on
            // this IP or account show up here. A malformed usage header is
            // reported but does not undo the hold.
            for (name, bucket) in &self.usage {
                if let Some(used) = super::usage(r, name)? {
                    budget.observe_used(*bucket, used, now.ns)?;
                }
            }
            Ok(verdict)

What to do next with the order:

/// The re-send rules: only what did not run, through the budget, inside
/// its own deadline; never an order that may have run.
///
/// [`Budget::resend`] makes that last rule structural: it answers
/// `Reconcile` for an unknown outcome instead of a re-send.
#[must_use]
pub fn next(order: &Order, verdict: Verdict, budget: &mut Budget, now_ns: i64) -> Next {
    match verdict {
        Verdict::Done => Next::Applied,
        Verdict::Rejected => Next::Dropped,
        Verdict::Banned { bucket, .. } => Next::Halted(bucket),
        _ => match budget.resend(
            verdict,
            order.parts.as_slice(),
            order.class,
            order.deadline_ns,
            now_ns,
        ) {
            Resend::Send(ticket) => Next::SendNow(ticket),
            Resend::Wait(limited) => Next::RetryAt(limited.ready_at_ns),
            Resend::Stale(_) => Next::Dropped,
            Resend::Reconcile => Next::Reconcile(order.client_order_id),
        },
    }
}

(From io/examples/venues.rs and io/tests/example_venues.rs, which cargo test -p ergon-io runs on every platform against responses written from each venue’s docs, in io/tests/fixtures/venues/. cargo run -p ergon-io --example venues prints each decision.)

Over the wire, one order with the pooled client:

1. try_charge → keep the Ticket by request id.
2. HttpClient::request returns at once; the answer comes to ClientHandler::on_response or on_error.
3. on_response → the adapter’s on_response above, then Budget::resend for the verdict.
4. on_error(request, sent, error) → Sent::No: refund the ticket and Budget::resend; Sent::Maybe: Unknown, reconcile by client order id.

Error policy

• A timeout is not a free re-send. A 408, and a Binance -1007 (“timeout waiting for response from backend server”), are Unknown: the backend may have taken the order. Re-send only what the venue says did not run (a Binance -2022), never what might have.
• The code decides before the status. On a 409 the body code picks NotRun (-2022) or Unknown (-2021).
• Hold the narrowest bucket the error names. A -1015 for 10 s holds the 10 s order bucket; cancels (not orders) still go.
• A hold blocks cancels too. On Binance a request sent into a 429 risks a ban. Arm the venue’s cancel-on-disconnect before trading: it is the only cancel path during a hold.
• Refund only Sent::No and Busy. Venues count rejected and throttled requests too.
• A server wait is the server’s answer. A 429 with Retry-After holds for that wait plus the guard; the bucket keeps its count. With no wait, the bucket is marked full for one window (the local count was wrong).
• A ClockSkew that repeats is the host clock. Re-signing with a new timestamp fixes one; if they keep coming, the clock is off: fix the host clock (chrony; see Clocks), not the re-send.

Rules

1. A ban stops sending until a person clears it. Budget::banned halts the scope. The end of the venue’s wait does not resume it: Budget::clear_halt, called by a person’s action, does. Budget::halted() and BucketStats::halted show it, so the loop can alert. Halt an IP-scope gate that every request and every connect charges, so one ban stops them all. The minimum waits differ: Binance 418 is 2 minutes (to 3 days for repeats); Bybit 403 is 10 minutes. A second ban costs more than a pause.
2. One sender per account and IP. The budget sees only this process. Budgets are not shared between processes.
3. Send again only what did not run, and only inside its deadline (Throttled, ClockSkew, NotRun). The application sets each order’s deadline (a few ms, say). Budget::try_resend charges it again, or says when to ask, or calls it stale.
4. Never send an order with an unknown outcome again. Every order carries a unique client order id; look it up by that id (or watch the user data stream). Only Coinbase Advanced Trade returns the existing order for a repeated id.
5. libcurl takes no method but GET, HEAD, OPTIONS and DELETE unless you opt in (below).

A ban, step by step:

    let v = on(example::BINANCE, "ban-418", |r| {
        b.on_response(r, &mut budget, NOW)
    })??;
    // Retry-After 300 s. The IP gate has no window to align to, so no
    // guard: this is the end of the server's wait. The halt does not end
    // there; a person clears it.
    assert_eq!(
        v,
        Verdict::Banned {
            bucket: b.ip(),
            until_ns: T0 + 300 * S
        }
    );
    // Ten minutes later the server's wait is long over: still stopped.
    let later = T0 + 600 * S;
    assert_eq!(why(&mut budget, &b.request(1)?, later), Some(Why::Banned));
    // Every connect is stopped too: it charges the same gate.
    assert_eq!(
        why(&mut budget, &b.connect(), later),
        Some(Why::Banned),
        "a banned IP must not reconnect"
    );
    // The loop's alert check names it.
    let mut alerted = Vec::new();
    example::alerts(&budget, later, |name, stats| {
        alerted.push((name.to_owned(), stats.bans));
    })?;
    assert_eq!(alerted, [("ip".to_owned(), 1)]);
    // A person decides; then sending resumes.
    budget.clear_halt(b.ip())?;
    assert_eq!(why(&mut budget, &b.request(1)?, later), None);
    assert_eq!(why(&mut budget, &b.connect(), later), None);

What it cannot do

• See other senders. The venue counts every process, host behind the same NAT and script on the same key or IP. Usage headers show them late (one round trip) and only in part; Kraken, Coinbase, Deribit and OKX send none. So run one sending process per account and IP. Put bulk REST on another IP, or in the same process and budget.
• Know a WebSocket request’s fate when its connection drops: ergon-io does not know WebSocket request ids. Treat pending ones as unknown.
• Retry or queue. Only the application knows whether a request is still wanted, and it must sign it again with a new timestamp.

libcurl sends requests twice

• What happens: when a reused connection dies before any reply byte, libcurl sends the request again, POST included, up to 5 times (Curl_retry_request in lib/transfer.c, curl 8.22.0). No option turns this off. An order that ran just before the connection died runs twice.
• What ergon-io does: the libcurl HttpClient refuses every method but GET, HEAD, OPTIONS and DELETE, with Error::CurlResend, unless curl_allow_non_idempotent_methods is set. io/tests/client.rs shows libcurl re-sending, and the refusal.
• Send orders through the native client: it never re-sends.

Cost

try_charge, the check before each request, is on the send path. Its cost is not measured here: no committed run holds it. Measure it with io/benches limit_bench:

cargo build --release --manifest-path io/benches/Cargo.toml --bin limit_bench
io/benches/target/release/limit_bench --samples 200000 --batch 64   # Linux: --cpu <isolated cpu>

• The bench reports ns per call (the mean of a --batch-call batch, not a per-call percentile), the slowest batch, stalls and allocs (allocations in the timed loop; expect 0).
• Catch-up walk. A ring stepped just under one full turn walks every slot instead of taking the fill(0) path a longer idle would. Budget::tick during idle keeps this off the send path: the send path only ever pays for the slots since the last charge.
• macOS cannot pin or isolate the thread; a quiet max needs an isolated Linux CPU.
• Inside ergon-io the send path adds one store per request and one add per send (for Sent), and one add per automatic WebSocket frame.

Kubernetes

Where ergon-io’s helper threads run inside a pod. On a host they run on the housekeeping CPUs. In a pod there are none. This page says what to do instead, for every pod size.

Terms: io glossary, deployment glossary.

Why a pod has no housekeeping CPUs

• On a host, the housekeeping CPUs are the ones the kernel leaves out of isolcpus: everything except the isolated cores.
• Those files describe the node, not the pod. /sys/devices/system/cpu/{online,isolated} are host-wide. A pod runs only on the CPUs the kubelet gave it: its cpuset (cpuset.cpus.effective). A Guaranteed pod with the static CPU manager gets exactly its whole-number cpu request. The node’s housekeeping CPUs are outside that set.
• A thread outside the cpuset never starts. The kernel refuses the mask (EINVAL), and io_uring_setup refuses an SQPOLL CPU outside it the same way.
• So the helper threads run on the pod’s own CPUs. Driver::new reads the pod’s cpuset once and chooses from it (placement): helper_cpus / ERGON_HELPER_CPUS first, then the loop CPU’s SMT sibling, then the pod’s other CPUs, preferring ones the host does not isolate. Never the polling CPU when it is known: set loop_cpu, or pin the loop thread before Driver::new. When it is not known the choice cannot keep off it, and the start-up line says the helpers may include the CPU the loop ends up on. The line reports the choice.

Pod layouts

Every layout: Guaranteed QoS (requests equal limits), a whole-number CPU request, and the kubelet’s cpuManagerPolicy: static (on x86 with SMT on, cpuManagerPolicyOptions: full-pcpus-only) — the node settings are under deployment: Kubernetes.

Minimal pod, cpu: 2 (change to "1" for one CPU). Requests equal limits, and the CPU request is a whole number:

apiVersion: v1
kind: Pod
spec:
  containers:
  - name: app
    resources:
      requests: { cpu: "2", memory: 1Gi }
      limits:   { cpu: "2", memory: 1Gi }

cpu: 1

connect_background refuses at once with Error::Cpu (NoSpareCpu) rather than start a dial helper on the polling CPU, and uring-sqpoll refuses at Driver::new. The warning thread shares the core, parked until there is work. One warning line at start says all this.

/// A pod with one CPU (`cpu: 1`). `connect_background` refuses: its dial
/// helper would time-slice the polling thread. With
/// `inline_connect_fallback=true` it connects as `Driver::connect` does
/// (the TLS handshake on the loop, about 0.7 ms of CPU once per connect
/// or reconnect). Never `uring-sqpoll` here: it is refused at
/// `Driver::new`.
fn one_cpu_pod() -> ergon_io::Result<Config> {
    Config::parse("recv-busy,inline_connect_fallback=true")
}

• With inline_connect_fallback=true, connect_background connects as Driver::connect does: the TLS handshake runs on the loop, a long poll per connect or reconnect (connection set-up). A helper thread sharing the loop’s CPU was not measured.
• For production, give the pod 2 CPUs (the warning line ends with that). ERGON_HOST_CHECKS=off silences the line; the typed refusals stay.

x86 with SMT, cpu: 2: one physical core

cpuManagerPolicyOptions: full-pcpus-only: the pod holds one core’s two hyperthreads. The loop takes one; SQPOLL, the dial helper and the warning thread take the other. Nothing to configure.

/// x86 with SMT, `cpu: 2` and the kubelet's `full-pcpus-only`: one
/// physical core, its two hyperthreads. The loop takes one; `SQPOLL`, the
/// dial helper and the warning thread take the other (the loop's SMT
/// sibling). Nothing to configure.
fn x86_two_cpu_pod() -> ergon_io::Result<Config> {
    Config::parse("uring-sqpoll")
}

What the SQPOLL thread on the sibling costs against a core of its own: SMT sibling cost.

• It needs both hyperthreads and nothing else on the sibling.
• For a core of its own instead: a cpu: 4 pod (two physical cores) with sqpoll_cpu on the second core, or SMT off on the node.

Graviton, cpu: 2: two cores

Graviton has no SMT: two vCPUs are two cores. The loop takes one; the helpers take the other. Nothing to configure.

/// Graviton (no SMT), `cpu: 2`: two cores. The loop takes one; the
/// helpers take the other. Nothing to configure.
fn graviton_two_cpu_pod() -> ergon_io::Result<Config> {
    Config::parse("recv-busy")
}

Shared CPUs from the node

A node-level mechanism can add shared CPUs to the pod’s cpuset for the helper threads (dial, warnings), and keep the loop on its exclusive CPU: deployment: shared CPUs. Name those CPUs in Config::helper_cpus, or let the mechanism set ERGON_HELPER_CPUS (same value: ERGON_SHARED_CPUS).

/// Shared CPUs a node-level mechanism added to the pod's cpuset: name
/// them for the helper threads. A CPU outside the process's CPUs is
/// refused (`Error::Cpu`), never used.
fn shared_cpu_pod() -> ergon_io::Result<Config> {
    Config::parse("recv-busy,helper_cpus=3-4")
}

/// The same from the pod's environment: `ERGON_HELPER_CPUS` is a kernel
/// CPU list (`3`, `3,7`, `2-3`). `Config::helper_cpus` wins when both are
/// set. `Driver::new` reads the variable; the application does not.
const fn helper_cpus_env_name() -> &'static str {
    HELPER_CPUS_ENV
}

env:
- name: ERGON_HELPER_CPUS
  value: "3-4"          # a kernel CPU list: 3, 3,7, 2-3

• A CPU outside the pod’s cpuset is refused (Error::Cpu, Outside), never used. Config::helper_cpus wins over the variable.
• Keep uring-sqpoll off shared CPUs: its SQPOLL thread spins (io_uring_setup(2), IORING_SETUP_SQPOLL). The default never puts it there: with no sqpoll_cpu it takes the lowest CPU of the pod’s own outside that list, and refuses (Error::Cpu, NoExclusiveCpu) when the list holds every CPU but the loop’s. Then set sqpoll_cpu to an exclusive CPU of the pod, or pick a single-CPU backend (recv-busy, per_queue). The dial helper and the warning thread are the ones that belong on the shared CPUs.

Pin the loop thread inside the pod

The kubelet gives the pod its CPUs; it never pins threads to them. Each busy thread pins itself to one CPU of the pod’s cpuset before Driver::new, so the host checks and the helper choice know the polling CPU. Node settings: deployment: Kubernetes.

/// Pin the loop thread to one of the pod's CPUs, before `Driver::new`.
/// The kubelet gives the pod its CPUs (its cpuset); it never pins threads
/// to them. `Driver::new` then knows the polling CPU, for its host checks
/// and for the helper-thread choice.
fn pin_loop() -> R {
    let (cpus, source) = placement::process_cpus(&Host::system());
    let cpu = cpus
        .iter()
        .next()
        .ok_or_else(|| format!("no CPU to pin to: {source}"))?;
    ergon_io::clock::pin_current_thread(usize::try_from(cpu)?)?;
    Ok(())
}

• The pod’s CPUs: cpuset.cpus.effective (what placement::process_cpus reads), or Cpus_allowed_list in /proc/self/status.
• Pinned by other means? Name the CPU as loop_cpu in the backend configuration (backends).

What the driver reports

• One start-up line with the helper CPUs and why (HostReport::helper_line), or, in a pod with one CPU, the warning above.
• Driver::host_report() carries the same (HostReport::helpers).
• ERGON_HOST_CHECKS=off silences the warning lines. The typed refusals (Error::Cpu) are never silenced.

ergon-tune

ergon-tune checks a Linux host’s low-latency settings. Each finding says what is wrong, the exact fix, and its evidence: an archived A/B where one exists (evidence), otherwise the kernel’s, Kubernetes’, Aeron’s or a vendor’s documentation and “not measured here”. It changes nothing. ergon-io and the ergon-md-dpdk media driver run the checks for you (where).

AI assistance. Like the rest of ergon, this crate was written with heavy AI assistance (disclosure). It is not production-ready.

[dependencies]
ergon-tune = { version = "0.1", features = ["nic"] }   # `nic` adds N1–N4

Glossary

In brackets: the check (T1–N4). Times are in µs.

Why check the host

• A busy-spinning thread loops on one CPU and never sleeps. It loses time only when something takes that CPU: a timer tick, an interrupt (IRQ), a kernel thread, a busy hyperthread on its core.
• Those pauses set the tail: p99.99 (the slowest 1 in 10,000) and the max.
• Each comes from a host setting, and a reboot, a new image or a NIC reset can undo it. Check at start-up and again later.

What it checks