IndexBus Layouts

    This page documents the v1 shared-memory layouts used by IndexBus.

    Layout Principles

    • All exported types use #[repr(C)] for cross-language compatibility
    • Layouts are header-versioned for forward compatibility
    • Field alignment follows C struct packing rules
    • Cache-line awareness for producer/consumer hot fields

    Region Layout

    A shared-memory region contains:

    1. Region header — magic, version, lane count, region size
    2. Lane headers — one per lane, at fixed offsets
    3. Lane data — entry storage for each lane
    ┌──────────────────────┐
│    Region Header     │  Fixed size
├──────────────────────┤
│   Lane Header [0]    │  Fixed size per lane
├──────────────────────┤
│   Lane Header [1]    │
├──────────────────────┤
│        ...           │
├──────────────────────┤
│   Lane Data [0]      │  capacity × entry_size
├──────────────────────┤
│   Lane Data [1]      │
├──────────────────────┤
│        ...           │
└──────────────────────┘

    Lane Header Fields

    FieldTypePurpose
    magicu32Validation marker
    versionu32Layout version
    kindu32Lane kind discriminant
    capacityu64Maximum entries
    entry_sizeu64Bytes per entry
    write_posu64Producer write position (producer-owned)
    read_pos[N]u64Per-reader positions
    on_fullu32Backpressure policy

    Hot fields (write position, read positions) are placed on separate cache lines to minimize false sharing between producer and consumer.

    Router Counter Layout

    Routers maintain per-output counters for monitoring:

    CounterMeaning
    routedTotal messages routed
    per_output[N]Messages sent to each output lane
    dropsMessages dropped (if applicable)

    Message Format

    indexbus-msg-v1 defines the message envelope:

    • Fixed header with message type, length, and sequence number
    • Payload follows immediately after the header
    • No padding between header and payload unless required by alignment

    ABI Compatibility

    The layout is part of the IndexBus ABI contract:

    • repr(C) layouts must not change without a version bump
    • Generated C headers (indexbus_v1.h) are the reference for non-Rust consumers
    • ByteOr's generated header (byteor_v1.h) includes indexbus_v1.h
    • Additive changes are preferred; breaking layout changes require explicit versioning
    Provenance
    Need the canonical source?
    Use the public hub to orient yourself, then jump to repo-owned docs or rustdoc when you need contract-level detail.
    Source-of-truth modelRepo docs index