From 625b47541f73b99c04d7f80b48633290aeae5f77 Mon Sep 17 00:00:00 2001 From: jbailes Date: Sun, 1 Nov 2026 00:14:56 +0100 Subject: [PATCH] docs: bring the contract and docs up to 0.4.0; add performance, configuration and a changelog The wire spec described none of D13 to D16. It now states the doorbell protocol, liveness and detach, the telemetry region, record, hand-off and pacing, and the attach capabilities with their 3, 5 or 7 descriptors. It also corrects the decision range, the wire vector counts, and the open question on arena routing, which D12 settled. The docs pages had the same drift: three descriptors, no waiting flags or telemetry region in the memory map, release at the next attach rather than at process exit, unannounced detach, and a CI list without the Release build. New pages: performance (what the bench measures, why a number belongs to its machine, what the budget enforces), configuration (every variable, flag and build option the implementations read), and CHANGELOG.md for 0.1.0 to 0.4.0, sourced from the merged pull requests. --- CHANGELOG.md | 118 +++++++++++++++++ README.md | 3 +- docs/README.md | 3 + docs/architecture.md | 31 +++-- docs/attach-and-admission.md | 40 ++++-- docs/configuration.md | 72 ++++++++++ docs/implementations-and-conformance.md | 30 ++++- docs/performance.md | 84 ++++++++++++ docs/versions-and-releases.md | 10 +- spec/README.md | 8 +- spec/wire-and-segment.md | 169 ++++++++++++++++++++---- 11 files changed, 508 insertions(+), 60 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 docs/configuration.md create mode 100644 docs/performance.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b636c63 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,118 @@ +# Changelog + +What each release changed for a consumer. Every release is tagged `v` +and `go/v`, and the pull requests named here carry the full evidence. +Within 0.x a minor release may break consumers +([versions and releases](docs/versions-and-releases.md)). + +## 0.4.0 (2026-10-31) + +The telemetry consumer is paced, so a busy host no longer wakes it once per +pump (#15). + +- **Pacing.** The telemetry region publishes `drain_interval_ns` and + `idle_after_ns`, taken from reserved space. A consumer that found records + recently drains on the interval without asking to be woken; an idle one + sleeps on the doorbell. Defaults 10 µs and 1 ms, set with + `OURO_TELEMETRY_DRAIN_INTERVAL_US`, `OURO_TELEMETRY_IDLE_AFTER_US` or + `ouro_host_telemetry_pacing`. The C and Go readers follow them, and so does + the exporter, unchanged. +- **Cost.** On a Threadripper 3970X with pinned threads, telemetry now adds 5–6 + ns per event instead of 17–30, and the host rings the doorbell 0–2 times in + 2 million events instead of about 30,000. +- **Breaking, C ABI.** `ouro_telemetry_reader_t` gained a field. The wire, + layout and contract versions are unchanged, and a 0.3.0 host's zeroed fields + give 0.3.0 behaviour. +- **Gated.** `scripts/check_perf_budget.sh` holds the doorbell-write count of a + busy consumer under 400. The bench pins its threads and prints + `telemetry_wakes=`; the host counts `telemetry_wakes`. +- **Fixed.** A `Release` build defined `NDEBUG`, which compiled every `assert` + out of the C tests and harnesses. They now keep their assertions, and CI + builds and runs `Release` too. + +## 0.3.0 (2026-10-30) + +Every event the host stamps is described off the host the moment it is stamped +([D16](spec/decisions.md#d16-tap-telemetry-leaves-the-host-the-moment-an-event-is-stamped), #14). + +- **The record and region.** A 128-byte, content-free record per stamped event, + written before the tap and routing into a ring in its own region. A full ring + is counted and reported by a gap record, never by blocking. +- **The grant.** `ouro_host_telemetry_enable`, `ouro_host_grant_telemetry`, and + `telemetry=yes` in a runtime grant file. Attach capability bit 2 hands one + slot two more descriptors. +- **Readers.** C `ouro_client_attach_telemetry` and `ouro_telemetry_*`; Go + `ring.AttachTelemetry`, `ConnectTelemetry` and `TelemetryReader`. Rust holds + the layout only. +- **The reference exporter.** `go/cmd/ouroboros-ring-otlp`, with its core in + `go/otlpexport`, sends OTLP/HTTP logs and releases records only once the + collector accepts them. `go/ring` still depends on nothing beyond the + standard library and `golang.org/x/sys`. +- **Compatibility.** `layout_version` stays 1. A grant file whose `telemetry` + value is neither `yes` nor `no` is now refused as malformed. + +Also: the module-call docs say a service stop must interrupt the client (#13). + +## 0.2.0 (2026-10-30) + +An idle ring makes no wakeups (#12). + +- **Doorbells ([D13](spec/decisions.md#d13-doorbells-idle-ends-sleep-in-the-kernel)).** + Each end of a queue pair sleeps on an `eventfd` and is signalled only while + asleep. `ouro_host_wait` (split into `_begin` and `_end` for a locked + embedding), `ouro_client_wait`, `Client.Wait` and `Client::wait`. The module + runtimes and callers in all three languages sleep on them, and the runtime's + accept loop blocks in `poll(2)`. +- **Notifications ([D14](spec/decisions.md#d14-notifications-reach-module-processes-and-callers)).** + Module processes and concurrent callers deliver subscribed notifications and + `overflow` to handlers, and can publish on their own slot. The Go concurrent + caller takes per-kind overflow handlers. +- **Liveness ([D15](spec/decisions.md#d15-liveness-is-the-process-not-a-timer)).** + A host holding a pidfd on a client releases its slot when the process exits + and grants it process liveness, so it need not heartbeat. Detach is announced. + A client watches the host's process too. +- **Compatibility.** The attach request grew to 20 bytes with a `capabilities` + word, negotiated so either side may be older. `layout_version` stays 1. + +## 0.1.3 (2026-10-29) + +- **Module client pool.** `ouro_module_client_pool_*` makes many module calls + at once over a pool of attached clients, waiting no longer than each call's + deadline (#10). A convenience of the C implementation, not part of the + contract. +- **Documentation.** `docs/`, with the architecture and a page for each part of + the ring (#9, #11). + +## 0.1.2 (2026-10-28) + +Machinery aimee had built on top of the ring moved into it (#8). + +- **`ouro_host_attach_local`** attaches a client to a host in the same process. +- **`ouro_capture_flush_fd`** appends a capture stream to a file. +- **Flow-control tests** for block, shed, `control_lost` and `producer_reaped`, + which until then were tested only in aimee. +- **The dispatch budget:** `c/bench/dispatch.c`, `c/bench/baseline.json` and + `scripts/check_perf_budget.sh`, now run in CI. + +## 0.1.1 (2026-10-27) + +- **GCC workaround.** The ring's own build turns off GCC's IPA bit-CP pass, + which in GCC 15.2 was observed to pass a live count as 0 in a consumer built + `-Os -flto` (#7). A consumer using the ring's CMake build gets this without + knowing about it. + +## 0.1.0 (2026-10-27) + +The ring moved out of aimee as a contract with three reference implementations +held to it (#1). + +- **The contract.** `spec/` (requirements R1 to R6, decisions D1 to D12) and + `vectors/`, generated from the spec and checked against every + implementation. +- **C.** The host, the client and the module runtime, as `libouroboros-ring` + and `libouroboros-ring-client`, with an installed CMake package and + pkg-config files. Owned in-process module services (#3). +- **Go and Rust.** Clients, module callers and module runtimes; pure Go with no + cgo, and Rust depending only on `libc`. +- **Releases** are cut from `VERSION` on `main` (#6). Nothing in the repository + builds, tests or runs against another project (#5). diff --git a/README.md b/README.md index 3d7ce6b..5c64ed3 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,8 @@ and pins a release of it like any other. - **The documentation** in [`docs/`](docs/README.md) explains how it works: the [architecture](docs/architecture.md), attach and admission, routing and flow control, module calls, arena payloads, capture, telemetry, conformance, - and versions. + versions, performance and configuration. What each release changed is in the + [changelog](CHANGELOG.md). ## Implementations diff --git a/docs/README.md b/docs/README.md index 4ddf274..1b83352 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,6 +16,9 @@ could disagree. | [Telemetry](telemetry.md) | every stamped event described off the host at once: the record, the hand-off to one exporter process, loss, and the reference OTLP exporter | | [Implementations and conformance](implementations-and-conformance.md) | what C, Go and Rust each provide, the evidence that holds them to the contract, and adding a language | | [Versions and releases](versions-and-releases.md) | release tags, the contract's own version numbers, and how consumers pin a release | +| [Performance](performance.md) | what the benchmark measures, why a number belongs to its machine, and what the budget enforces | +| [Configuration](configuration.md) | every environment variable, flag and build option the implementations read | +| [Changelog](../CHANGELOG.md) | what each release changed for a consumer | New to the ring: read the architecture page, then whichever of the others matches what you are building. Implementing the ring in another language: read diff --git a/docs/architecture.md b/docs/architecture.md index e0ce59e..a6cd5e9 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -55,10 +55,14 @@ the kernel, not the client library, decides what a client can see flowchart TB subgraph host["Host address space"] DIR["queue directory
(ordinary private memory:
slot → handle, principal, grants)"] - CTL["control region
magic · versions · geometry ·
host_epoch · host_heartbeat ·
lease view (D12)"] + CTL["control region
magic · versions · geometry ·
host_epoch · host_heartbeat ·
host_waiting · lease view (D12)"] ARENA["arena region
payload spans, by (offset, len)"] - QA["queue pair, slot 0
inbound ring · outbound ring ·
credits · heartbeat · control_lost"] + QA["queue pair, slot 0
inbound ring · outbound ring ·
credits · heartbeat · control_lost ·
client_waiting"] QB["queue pair, slot 1"] + TLM["telemetry region (D16, if enabled)
pacing · consumer_waiting ·
ring of records"] + end + subgraph exporter["Telemetry exporter"] + X1["telemetry region"] end subgraph ca["Client A"] CA1["control (read-only)"] @@ -76,19 +80,28 @@ flowchart TB ARENA -.-> CB2 QA -.-> CA3 QB -.-> CB3 + TLM -.-> X1 ``` +The exporter is an ordinary client too: it also maps control, arena and its own +queue pair, left out of the diagram. + | Region | Backing | Host | Each client | Holds | |---|---|---|---|---| -| Control | one `memfd` | read/write | read-only | magic, `spec_version`, `layout_version`, flags, `slot_size`, `inline_budget`, `arena_size`, `host_epoch`, `host_heartbeat`, and the lease view | -| Queue pair | one `memfd` per admitted slot | read/write | read/write, its own slot only | inbound and outbound SPSC rings, credit counters, the client heartbeat, the sticky `control_lost` flag | +| Control | one `memfd` | read/write | read-only | magic, `spec_version`, `layout_version`, flags, `slot_size`, `inline_budget`, `arena_size`, `host_epoch`, `host_heartbeat`, `host_waiting`, and the lease view | +| Queue pair | one `memfd` per admitted slot | read/write | read/write, its own slot only | inbound and outbound SPSC rings, credit counters, the client heartbeat, the sticky `control_lost` flag, `client_waiting` | | Arena | one `memfd` | read/write | read/write | payloads too large to travel inline | +| Telemetry | one `memfd`, only once enabled | read/write | read/write, the one granted consumer only | pacing values, `dropped`, `consumer_waiting`, the record ring ([telemetry](telemetry.md)) | | Queue directory | not a region | private | none | which slot is whom, principals, grants, pending requests | -Because a client receives exactly three descriptors at attach (control, arena, -its own queue pair) it cannot map another client's rings, cannot enumerate other -slots, and cannot write the geometry its peers read. Those properties are -enforced. Arena bounds are not: every client maps the arena read-write for +The doorbells are `eventfd`s, not regions: one the host reads and every client +writes, and one per client that only the host writes. + +A client receives only the descriptors for what it may map: control, arena and +its own queue pair, then the two doorbells if it was granted them, then the +telemetry region and its doorbell if it is the granted consumer. So it cannot +map another client's rings, cannot enumerate other slots, and cannot write the +geometry its peers read. Those properties are enforced. Arena bounds are not: every client maps the arena read-write for zero-copy fan-out, so staying inside one's leases is a contract the client libraries keep and conformance checks, not something hardware enforces ([D2](../spec/decisions.md#d2-threat-model)). @@ -232,3 +245,5 @@ and Rust code creates no regions and accepts no attaches. three implementations and how a new one is proven. - [Versions and releases](versions-and-releases.md): what each version number means and how a consumer pins the ring. +- [Performance](performance.md): measuring dispatch overhead, and the budget. +- [Configuration](configuration.md): every setting the implementations read. diff --git a/docs/attach-and-admission.md b/docs/attach-and-admission.md index c638e1d..9d455ce 100644 --- a/docs/attach-and-admission.md +++ b/docs/attach-and-admission.md @@ -25,7 +25,7 @@ sequenceDiagram H->>H: allocate a directory slot, create its queue-pair memfd H->>B: bind(ctx, host, slot, request) B-->>H: OK (subscriptions, served kinds, outbound grants set) - H-->>C: reply (magic ABRP, OK, handle, negotiated version, granted capabilities, geometry, host_epoch)
+ SCM_RIGHTS: control, arena, queue pair (+ host and client doorbells) + H-->>C: reply (magic ABRP, OK, handle, negotiated version, granted capabilities, geometry, host_epoch)
+ SCM_RIGHTS: control, arena, queue pair (+ host and client doorbells) (+ telemetry region and doorbell) C->>C: map control read-only, arena and queue pair read/write else refused at either hook H->>H: roll the slot back @@ -63,6 +63,11 @@ sequenceDiagram bound the slot to the client's process (`ouro_host_bind_process`), and tells the client it need not heartbeat ([D15](../spec/decisions.md#d15-liveness-is-the-process-not-a-timer)). + `OURO_ATTACH_CAP_TELEMETRY` (bit 2), asked for together with bit 0, adds two + more descriptors, the telemetry region and its doorbell, for the one slot the + embedding granted it ([telemetry](telemetry.md#granting-it)). A reply's + descriptor count is therefore 3, 5 or 7, and always matches its + `capabilities`. The client reads its geometry from the reply and the control region. It is never compiled against those values, which is why the host can re-tune them @@ -105,7 +110,7 @@ flowchart TB dup -- "yes, and its process
is still running" --> deny dup -- "no, or its process has exited
(pidfd)" --> bind["release the stale slot if any,
enforce grants, subscribe,
serve, grant outbound kinds"] bind --> live["bind the slot to the peer's pidfd
(D15: released when it exits)"] - live --> ok["OK: reply + three descriptors
(five with a doorbell)"] + live --> ok["OK: reply + three descriptors
(five with a doorbell,
seven with telemetry)"] ``` A grant is one file per installed program in a policy directory @@ -133,14 +138,18 @@ host hands its telemetry ring ([telemetry](telemetry.md), [D16](../spec/decisions.md#d16-tap-telemetry-leaves-the-host-the-moment-an-event-is-stamped)). The host still grants it only while no other live slot holds it. -The listener also handles the case heartbeats alone handle badly. A process that +The listener also handles the case heartbeats alone handle badly: a process that crashes cannot detach its slot, and its supervisor may restart it at once. When -the kernel supports `pidfd`, the runtime keeps a handle on each admitted -process: a new attach for a principal whose previous holder has exited releases -the stale slot immediately, while a live duplicate is still refused. Without -`pidfd` the stale slot waits for heartbeat reaping. `ouro_runtime_maintain`, -called periodically under the host lock, advances the host heartbeat and reaps -slots whose client heartbeat has stopped. +the kernel supports `pidfd`, the runtime keeps a handle on each admitted process +and watches it in the same `poll(2)` as the socket, so the slot is released the +moment the process exits +([D15](../spec/decisions.md#d15-liveness-is-the-process-not-a-timer)). A restarted +process therefore finds its principal free, while a live duplicate is still +refused. Without `pidfd` the stale slot waits for heartbeat reaping. +`ouro_runtime_maintain`, called under the host lock, advances the host +heartbeat and reaps slots whose client heartbeat has stopped; +`ouro_runtime_maintenance_due` says whether any slot still needs it, and when +none does the owner can sleep with no reap timer. `refused_role_refs` lets a host that composes several ring instances refuse role identities that belong to another instance, so a role cannot attach where @@ -160,9 +169,14 @@ lock. This is a convenience of the C implementation, not part of the contract. ## Detach, reap and restart - A client that is done calls `ouro_client_detach` (or its Go and Rust - equivalents) and closes its socket. -- A client whose heartbeat stops is reaped. Reaping drops every arena reference - the slot holds, discards its rings, and frees the slot. An event that was - blocked in flight for a reaped producer becomes a `producer_reaped` record. + equivalents). The detach is announced: the client marks its heartbeat + `OURO_HEARTBEAT_DETACHED` and rings the host, whose next pump drains what the + client queued and releases the slot. +- A process-bound client whose process exits is released at once, and is never + reaped for a stale heartbeat. +- Any other client whose heartbeat stops is reaped. +- Releasing a slot, by any of these, drops every arena reference it holds, + discards its rings and frees it. An event that was blocked in flight for a + released producer becomes a `producer_reaped` record. - `ouro_host_bump_epoch` (or a host restart) changes `host_epoch`. Every client sees `epoch_changed`, every mapping is stale, and clients re-attach. diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..2a0b5a9 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,72 @@ +# Configuration + +The ring's libraries read two environment variables. Everything else is set by +the embedding through the C API, because the embedding owns policy. This page +lists every environment variable, flag and build option the reference +implementations read, and the API settings an operator is most likely to ask +about. + +## Host operator + +| Variable | Default | Read by | Sets | +|---|---|---|---| +| `OURO_TELEMETRY_DRAIN_INTERVAL_US` | 10 | `ouro_host_telemetry_enable` | how often a busy telemetry consumer looks for records, in microseconds; 0 makes it sleep on the doorbell after every drain | +| `OURO_TELEMETRY_IDLE_AFTER_US` | 1000 | `ouro_host_telemetry_enable` | how long a consumer goes without records before it sleeps on the doorbell, in microseconds | + +Both are read once, when telemetry is enabled, and published in the telemetry +region, so every consumer in any language follows the host's values. A value +that is not a plain decimal number keeps the default. An embedding can set +them instead with `ouro_host_telemetry_pacing`, in nanoseconds. What they trade +is in [telemetry: pacing](telemetry.md#pacing). + +## The reference exporter + +`ouroboros-ring-otlp` takes its ring settings as flags and its collector +settings from the standard OpenTelemetry variables. + +| Setting | Default | Sets | +|---|---|---| +| `-socket` | none, required | the host's ring socket | +| `-principal-class` | 0 | the principal class it attaches as | +| `-principal-ref` | 0 | the principal ref the host grants telemetry to | +| `-service-name` | `ouroboros-ring` | OTLP `service.name`, unless `OTEL_SERVICE_NAME` is set | +| `OTEL_EXPORTER_OTLP_*` | the OpenTelemetry defaults | endpoint, headers, TLS and timeouts | + +It exits 3 when the host goes away, so a supervisor can restart it against the +new host. + +## Set through the API + +These are not environment variables, and the reference host reads none of them +from one. They are listed because they are the settings that change how a +deployment behaves. + +| Setting | Where | Default | +|---|---|---| +| telemetry ring size | `ouro_host_telemetry_enable(h, capacity)` | 0 means 65,536 records, 8 MiB | +| shed or block per kind | `ouro_host_set_kind_policy` | block | +| stale heartbeat window | `ouro_runtime_config_t.stale_after_ns` | none; the embedding chooses, and 0 turns heartbeat reaping off | +| socket path, mode and backlog | `ouro_runtime_config_t` | none; the embedding chooses | +| who may attach, and with which kinds | grant files, `ouro_runtime_policy_load_dir` | a missing directory refuses everyone ([attach and admission](attach-and-admission.md#the-runtime-listener)) | + +## Benchmarks and tests + +| Variable | Read by | Sets | +|---|---|---| +| `OURO_BENCH_TELEMETRY` | `c/bench/dispatch.c` | 1 runs the benchmark with the telemetry hand-off on | +| `OURO_BENCH_HOST_CPU`, `OURO_BENCH_DRAIN_CPU` | `c/bench/dispatch.c` | the CPUs the host and telemetry drain threads are pinned to ([performance](performance.md)) | +| `OURO_CONFORMANCE_HOST` | the Go and Rust conformance tests | path to the built `ouroboros-ring-conformance-host`; the Go tests skip without it, and the Rust test is `#[ignore]`d and requires it | +| `OURO_TEST_MODULE_CALLER` | the module-runtime harness | path to another language's module caller, which must reach the same outcomes as the C caller against the C runtime's module | +| `TMPDIR` | the C and Rust socket tests | where test sockets go; keep it short, because a Unix socket path is limited to 108 bytes | + +## Build options + +| CMake option | Default | Does | +|---|---|---| +| `OURO_TSAN` | `OFF` | builds the arena ThreadSanitizer test | +| `CMAKE_BUILD_TYPE` | none | `Release` defines `NDEBUG` for the libraries; tests and harnesses keep their assertions regardless | + +The ring's own build also turns off GCC's IPA bit-CP for its sources, a +compiler workaround, so a consumer that compiles the sources itself instead of +using that build has to apply it too +([versions and releases](versions-and-releases.md#release-versions)). diff --git a/docs/implementations-and-conformance.md b/docs/implementations-and-conformance.md index f52eedc..42ab66b 100644 --- a/docs/implementations-and-conformance.md +++ b/docs/implementations-and-conformance.md @@ -74,10 +74,19 @@ flowchart TB module, and checks it reaches the same outcomes as the C caller. CI runs all of it on every change: the vector check and the single-host check, -the C suite under release, ASan/UBSan and (for the arena) TSan builds, the Go -suite with `CGO_ENABLED=0` and under the race detector, the Rust suite with -`clippy -D warnings`, each client against the conformance host, and the module -harness against the Go and Rust module processes and the Rust caller. +the C suite under four builds, the Go suite with `CGO_ENABLED=0` and under the +race detector, the Rust suite with `clippy -D warnings`, each client against +the conformance host, and the module harness against the Go and Rust module +processes and the Rust caller. The four C builds are: + +- **`-O2`**, which also runs the [performance budget](performance.md) and builds + the external module example against the installed package; +- **`CMAKE_BUILD_TYPE=Release`**, which defines `NDEBUG`. The tests and + harnesses undefine it again, because they assert with `assert`: before that, + a Release build compiled every check out and the suite passed while testing + nothing; +- **ASan/UBSan**; +- **TSan**, for the arena. ## Adding an implementation @@ -110,8 +119,17 @@ are easy to get wrong, roughly in order: ([D12](../spec/decisions.md#d12-cross-process-arena-reads-a-lease-view-and-a-release-message)). - **Returning arena references.** Send `LEASE_RELEASE` once per arena frame received, queueing (bounded) when the outbound ring is full. -- **Heartbeats.** Advance the queue-pair heartbeat while attached, or the host - will reap the slot. +- **Heartbeats.** Advance the queue-pair heartbeat while attached, unless the + reply granted `OURO_ATTACH_CAP_PROCESS_LIVENESS`, or the host will reap the + slot. On detach, store `OURO_HEARTBEAT_DETACHED` and ring the host doorbell. +- **The doorbell fences.** A sleeper stores its waiting flag, fences, then + re-checks its ring before it sleeps; a signaller commits, fences, then loads + the flag. Drop either fence and a wakeup is lost under load, which no + single-threaded test will show + ([wire spec: doorbells](../spec/wire-and-segment.md#doorbells)). +- **Telemetry pacing.** A telemetry consumer follows the region's + `drain_interval_ns` and `idle_after_ns`. One that sleeps on the doorbell after + every drain still works, but costs a busy host a system call per pump. ## Building and testing diff --git a/docs/performance.md b/docs/performance.md new file mode 100644 index 0000000..fc99773 --- /dev/null +++ b/docs/performance.md @@ -0,0 +1,84 @@ +# Performance + +Speed is a guardrail for the ring, not the point of it. The budget is a set of +absolute ceilings that catch a gross regression, such as a system call or a +lock on the per-event path, rather than a comparison with the last build. This +page says what is measured, how to measure it so the number means something, +and what the budget enforces. + +## What is measured + +`c/bench/dispatch.c` measures **dispatch overhead**: a producer writing its +outbound ring, the host routing, and a subscriber reading its inbound ring, +with a 16-byte inline payload and no work on it. It is the cost the ring adds +to move one event. It reports the median per-event time over batched samples, +and the p99. + +With `OURO_BENCH_TELEMETRY=1` the host also writes a telemetry record per event +([telemetry](telemetry.md)), and a second thread drains them through the +reader's own paced wait, as an exporter would. That run also prints how many +times the host wrote the telemetry doorbell. + +```sh +cmake -S c -B build/c && cmake --build build/c --target ouroboros-ring-dispatch-bench +build/c/ouroboros-ring-dispatch-bench 2000000 +# dispatch_overhead_ns=... +# dispatch_overhead_p99_ns=... +OURO_BENCH_TELEMETRY=1 build/c/ouroboros-ring-dispatch-bench 2000000 +# ... and telemetry_wakes=... +``` + +The benchmark target is always built `-O2`, whatever the rest of the build +uses. + +## A number belongs to its machine + +**A result compares only with results from the same machine, with the same +pinning.** This repository's own record shows why: the benchmark reported +83 ns per event in PRs #8 and #12 and 127 ns in PR #15, on different machines. +The code changed in between too, and nothing in the record separates the two +effects, so the pair says nothing about the ring. + +Placement matters as much as the machine. On a Threadripper 3970X with pacing +off (the 0.3.0 behaviour), telemetry cost 144 ns per event with both threads on +one CCX and 157 ns with them on different CCXs, because each record's cache +lines crossed further. So pin both threads, and say where they are: + +| Variable | Pins | +|---|---| +| `OURO_BENCH_HOST_CPU` | the host thread (producer, routing and subscriber) | +| `OURO_BENCH_DRAIN_CPU` | the telemetry drain thread | + +To compare two builds, run both on one idle machine, pinned the same way, +several times each, and report the machine and the cores with every figure. +Judge "idle" by CPU use, not load average, which also counts processes waiting +on I/O: a host can have a high load average and idle cores. + +## The budget + +`scripts/check_perf_budget.sh BUILD_DIR` runs the benchmark from an optimized +build and fails if a metric is over its ceiling in `c/bench/baseline.json`. CI +runs it on the `-O2` build of every change. + +| Metric | Ceiling | Last observed | Catches | +|---|---|---|---| +| `dispatch_overhead_ns` | **1000 ns** | 134 ns | a system call or lock on the hot path | +| `dispatch_overhead_telemetry_ns` | **1000 ns** | 132 ns | the same, with the telemetry hand-off on | +| `telemetry_wakes` | **400** doorbell writes | 0–2 | consumer pacing that has stopped working | + +The time ceilings carry about seven times headroom, so a slow or shared CI +runner does not fail them, while a per-event system call still does. That also +means they cannot catch a small regression; nothing in CI does. + +The wake count is the one check that means the same on every machine, because +it is a count, not a time. A busy, paced consumer is never asleep when a +record lands, so the host rings it for the first record and rarely after. +Pacing that stops working rings once per pump, about 8,000 times in the +budget's run. The ceiling leaves room for a consumer descheduled past its idle +threshold on a busy runner. + +The observed values are notes, not checks. The 134 ns was measured when the +benchmark still lived in aimee, on a machine the record does not name; the +132 ns is from the Threadripper above, pinned. Changing a ceiling is a reviewed +change to `c/bench/baseline.json`, so "within budget" always names a number +someone agreed to. diff --git a/docs/versions-and-releases.md b/docs/versions-and-releases.md index 9925760..b0da417 100644 --- a/docs/versions-and-releases.md +++ b/docs/versions-and-releases.md @@ -7,7 +7,10 @@ reasons and are checked in different places. ## Release versions `VERSION` holds the repository's release in semver. Within 0.x a minor bump may -break consumers; from 1.0 only a major bump may. +break consumers; from 1.0 only a major bump may. Within 0.x a change to the C +ABI, such as a field added to a public struct, takes a minor bump even when no +contract version moves: 0.4.0 is one, because `ouro_telemetry_reader_t` grew. +What each release changed is in the [changelog](../CHANGELOG.md). ```mermaid flowchart LR @@ -62,7 +65,10 @@ Some changes need none of these: (D15) is one more bit in that word and one reserved `client_heartbeat` value, `OURO_HEARTBEAT_DETACHED`, which no clock reading takes. Telemetry (D16) is a third bit, `OURO_ATTACH_CAP_TELEMETRY`, and a region of its own that only a - client granted it receives, so no existing layout changes. + client granted it receives, so no existing layout changes. Its pacing values + (0.4.0) took two words of that region's reserved space, which a 0.3.0 host + leaves zero, and zero means a consumer that sleeps on the doorbell after + every drain: the 0.3.0 behaviour. A host and client agree the wire version at attach ([attach and admission](attach-and-admission.md)). Capture files carry their diff --git a/spec/README.md b/spec/README.md index 4da80c6..4dfe262 100644 --- a/spec/README.md +++ b/spec/README.md @@ -14,8 +14,8 @@ here requires linking, importing or generating from a reference implementation. | Document | What it fixes | |---|---| -| [`wire-and-segment.md`](wire-and-segment.md) | Regions, rings, the 64-byte frame, attach and admission, routing, flow control, ordering, versioning, payloads, capture | -| [`decisions.md`](decisions.md) | Why the layout is what it is (D1 to D12), including the threat model | +| [`wire-and-segment.md`](wire-and-segment.md) | Regions, rings, the 64-byte frame, attach and admission, routing, flow control, doorbells, liveness, telemetry, ordering, versioning, payloads, capture | +| [`decisions.md`](decisions.md) | Why the layout is what it is (D1 to D16), including the threat model | | [`../vectors/`](../vectors/) | The frozen numbers: `wire_vectors.tsv` (frame bytes) and `layout_vectors.tsv` (every offset, size, magic and version a client needs) | Where prose and vectors disagree, the vectors are authoritative and the prose is @@ -27,9 +27,11 @@ of the contract. - the wire frame and version negotiation; - the control, private queue-pair and arena layouts; - single-producer/single-consumer rings and bounded credits; -- client admission (through the host's admission hook) and reaping; +- client admission (through the host's admission hook), liveness and reaping; +- doorbells: sleeping when idle and waking only a sleeper; - publish, subscribe, request/reply, cancellation and typed absence; - the host sequence, observer routing and the full-stream tap hook; +- the telemetry record and its hand-off to one consumer process; - the capture format and observational replay; - local `SOCK_SEQPACKET` attachment and descriptor grant; - the AMOD module message envelope (`module_protocol`), fragmentation of large diff --git a/spec/wire-and-segment.md b/spec/wire-and-segment.md index def9b6b..cec24d7 100644 --- a/spec/wire-and-segment.md +++ b/spec/wire-and-segment.md @@ -9,7 +9,7 @@ reference implementations in this repository are tested against them in both directions. Where this text and the vectors disagree, the vectors win and this text is the bug. -Design rationale and its history are in [`decisions.md`](decisions.md) (D1 to D12). +Design rationale and its history are in [`decisions.md`](decisions.md) (D1 to D16). This specification began as aimee's v0 event-bus spec (2026-07-23, implemented 2026-07-24) and moved here with the implementations on 2026-10-27; amendment notes below are kept as the record of why the layout is what it is. @@ -17,8 +17,8 @@ below are kept as the record of why the layout is what it is. ## Scope This spec defines the intra-service ouroboros ring: the segment layout, the ring buffers, -the event wire encoding, the attach/admission handshake, routing, flow control, ordering, versioning, -the governance/audit tap, and capture/replay format. It is what a ring client in any language +the event wire encoding, the attach/admission handshake, routing, flow control, doorbells, liveness, +ordering, versioning, the governance/audit tap, the telemetry hand-off, and capture/replay format. It is what a ring client in any language implements to interoperate with the single in-source C ring host. Out of scope (owned by whoever embeds the ring): the descriptor and **event-contract schema**, which @@ -66,28 +66,38 @@ descriptors only for what it is allowed to map, so isolation is enforced by the by convention. ``` - Control region — one memfd, mapped PROT_READ by clients + Control region: one memfd, mapped PROT_READ by clients +===========================================================+ | magic | spec_version | layout_version | flags | | slot_size | inline_budget | arena_size | | host_epoch | host_heartbeat (monotonic) | +| host_waiting (D13) | lease view (D12) | +===========================================================+ - Queue-pair region — one memfd PER ADMITTED SLOT, + Queue-pair region: one memfd PER ADMITTED SLOT, mapped read/write by that client and no other +===========================================================+ | inbound ring (host -> client) | | outbound ring (client -> host) | | credit counters | reserved control-class credits | | client_heartbeat | control_lost flag | +| client_waiting (D13) | +===========================================================+ - Arena region — one memfd, mapped read/write by all + Arena region: one memfd, mapped read/write by all +===========================================================+ | payload regions referenced by (offset, len) | +===========================================================+ - Queue directory — HOST-PRIVATE ordinary memory, not shared + Telemetry region (D16): one memfd, only if enabled, + mapped read/write by the one granted consumer ++===========================================================+ +| magic | version | record_size | flags | host_epoch | +| dropped | drain_interval_ns | idle_after_ns | +| consumer_waiting | ring of 128-byte records | ++===========================================================+ + + Queue directory: HOST-PRIVATE ordinary memory, not shared +===========================================================+ | per slot: handle_id | state | principal_ref | geometry | +===========================================================+ @@ -110,16 +120,21 @@ spec's existing note that a hostile native client in the trusted tier is outside threat model. Untrusted code does not run as a native admitted client; it runs sandboxed under `module-loader`, whose tier will need per-lease arena sub-regions or a copy-on-deliver mode. -Attach carries three descriptors (control, arena, and that client's queue pair) in a single -`sendmsg` over the `SOCK_SEQPACKET` attach socket, via `SCM_RIGHTS`, only after admission succeeds. -An unadmitted process receives no descriptors and, because the regions are anonymous `memfd`s with -no filesystem name, has nothing to open. The host's descriptor table grows by one per admitted slot -plus the two shared regions. +Attach carries the descriptors in a single `sendmsg` over the `SOCK_SEQPACKET` attach socket, via +`SCM_RIGHTS`, only after admission succeeds. There are **three** (control, arena, and that client's +queue pair), **five** with a doorbell grant (then the host doorbell and the client's own), and +**seven** with a telemetry grant (then the telemetry region and its doorbell). The order is fixed, +and which grant applies is in the reply's `capabilities` +([attach](#attach-and-admission-handshake)). An unadmitted process receives no descriptors and, +because the regions are anonymous `memfd`s with no filesystem name, has nothing to open. The host's +descriptor table grows by one queue pair and one client doorbell per admitted slot, plus the shared +regions and the host doorbell. The control region is versioned and read-mostly. `host_epoch` changes on host restart and invalidates -every prior handle and mapping (clients must re-attach). Heartbeats give liveness both ways: a client -whose heartbeat stalls is reaped by the host; a stalled `host_heartbeat`/`host_epoch` change tells a -client the host is gone. +every prior handle and mapping (clients must re-attach). Liveness runs both ways +([liveness](#liveness)). The host releases a client's slot when the client's process exits, when +the client announces a detach, or when its heartbeat stalls. A client learns the host is gone from +the host's process handle, a `host_epoch` change, or a stalled `host_heartbeat`. `slot_size` and `inline_budget` are region *parameters*, read by a client at attach and used to choose inline-versus-arena placement. They are not frame fields and they do not participate in @@ -186,8 +201,23 @@ its embedding's admission hook (`ouro_admit_fn`: peer identity, attestation, ins whatever the embedding requires; not this spec), and only on success allocates the client a queue-directory slot, maps **only** that slot's queue pair and the arena into the client, and returns the `handle_id` and negotiated version. -An unadmitted process gets no slot, no handle, and no mapping. Detach (graceful or by reaped -heartbeat) frees the slot; `host_epoch` bumps invalidate all handles at once. +An unadmitted process gets no slot, no handle, and no mapping. Detach (announced, by process exit, +or by reaped heartbeat) frees the slot; `host_epoch` bumps invalidate all handles at once. + +**Capabilities.** A client asks for optional grants in a `capabilities` word after the 16-byte v0 +request, making the request 20 bytes. The host answers with the bits it granted in the reply's +`capabilities` word, which was reserved and zero in v0. + +| Bit | Name | Granted when | Adds | +|---|---|---|---| +| 0 | `OURO_ATTACH_CAP_DOORBELL` | the host supports doorbells | two descriptors; [doorbells](#doorbells) | +| 1 | `OURO_ATTACH_CAP_PROCESS_LIVENESS` | the host holds a handle on the client's process | no heartbeat needed; [liveness](#liveness) | +| 2 | `OURO_ATTACH_CAP_TELEMETRY` | telemetry is enabled, the embedding granted this slot, bit 0 was granted, and no other live slot holds it | two descriptors; [telemetry](#telemetry) | + +Either side may be older. A host that predates capabilities reads the first 16 bytes of a 20-byte +request, which is a valid v0 request, and grants nothing. A host accepts a 16-byte request and grants +that client nothing. A client treats a reply whose `capabilities` and descriptor count disagree as a +protocol error. ## Routing and the tap @@ -237,13 +267,94 @@ co-located publishers. Module processes instead use the wire-v3 ordered fragment requests and replies, with a 16 MiB assembled-message limit and endpoint reassembly. Direct producer→consumer arena allocation across that process boundary remains outside this contract. +## Doorbells + +An idle end of a queue pair sleeps in the kernel, and the other end signals it only when it is +asleep ([D13](decisions.md#d13-doorbells-idle-ends-sleep-in-the-kernel)). Each doorbell is a +non-blocking, close-on-exec `eventfd`: one **host doorbell** that every client writes, and one +**client doorbell** per slot that only the host writes. Each sleeper owns a `u32` waiting flag its +signaller can read: `host_waiting` in the control region (`OURO_CONTROL_F_DOORBELL` says the host +maintains it) and `client_waiting` in the queue pair. + +- **Sleeper.** Store the flag as 1 with sequentially consistent ordering, then re-check every ring it + consumes. If any is non-empty, store 0 and consume. Otherwise wait for the doorbell to become + readable, with a timeout no longer than its next due maintenance; then read the doorbell to reset + it and store 0. +- **Signaller.** After a commit into a ring the other side consumes, issue a sequentially consistent + fence and load the other side's flag. Write the doorbell only if the flag is 1. +- **Both directions of room.** The host also signals a client after consuming from that client's + outbound ring, and a client signals the host after consuming from its inbound ring, so a producer + held by backpressure is woken instead of polling. A producer the host holds is not work: the host + never stays awake for one. + +Either the sleeper's re-check sees the commit or the signaller's load sees the flag, so no wakeup is +lost. A flag never grants anything; a wrong one costs only its owner a spurious or late wakeup, +bounded by the timeout. + +## Liveness + +A slot is released, freeing its rings and arena references exactly as a reap does, by the first of +these ([D15](decisions.md#d15-liveness-is-the-process-not-a-timer)): + +- **Process exit.** A host that holds an OS handle on the client's process (on Linux a pidfd of the + attach socket's `SO_PEERCRED` pid, never anything the client sends) releases the slot when the + handle becomes readable. Such a slot is **process-bound** and is granted + `OURO_ATTACH_CAP_PROCESS_LIVENESS`. A client attached in the host's own process is process-bound + by definition. +- **Announced detach.** A detaching client stores `OURO_HEARTBEAT_DETACHED` (all ones) in + `client_heartbeat` before unmapping and signals the host doorbell. The host drains what the client + queued and releases the slot. +- **Stale heartbeat.** A client not granted process liveness advances `client_heartbeat`; the host + reaps a slot whose heartbeat stops advancing. Process-bound slots are never stale-reaped. + +On the client side, a client holds a handle on the host's process (the peer of the same socket) and +adds it to its doorbell wait. The host's exit ends the wait and reads as an epoch change. A client +watching both ends may wait with no timeout while idle. + +## Telemetry + +A host may hand the description of every stamped event to one consumer process +([D16](decisions.md#d16-tap-telemetry-leaves-the-host-the-moment-an-event-is-stamped)). The region, +the record and their offsets are frozen in `vectors/layout_vectors.tsv` (`telemetry.*`, +`telemetry_record.*`). + +- **The record.** 128 bytes per stamped event, in `seq` order: a type (event or gap), a + `CLOCK_REALTIME` timestamp read once per pump, a lost count for a gap, and the stamped 64-byte + frame header encoded exactly as on the wire. **A record never carries a payload byte.** A reader + rejects a record with an unknown flag bit. +- **The ring.** An SPSC ring of records in the telemetry region: `head` written only by the host, + `tail` only by the consumer, with the same index rules as every other [ring](#rings). The host + writes the record before the tap is called and before routing. +- **Never blocking.** If the ring is full, the host counts the record in `dropped` and in a pending + gap count, and continues. The next record that fits is preceded by a gap record carrying the count. + Telemetry loss never sheds, delays or reorders an event. +- **Waking the consumer.** The consumer owns `consumer_waiting` and sleeps on the telemetry doorbell + under the [doorbell](#doorbells) protocol. The host signals it at most once per pump, and at once + for an event stamped outside a pump. +- **Pacing.** The host publishes `drain_interval_ns` and `idle_after_ns` before it publishes the + region's magic. A consumer that found records within `idle_after_ns` keeps `consumer_waiting` at 0, + sleeps `drain_interval_ns` (still woken by its doorbell or the host's exit), and looks again. Past + `idle_after_ns` without records it sleeps on the doorbell. A `drain_interval_ns` of 0 means sleep on + the doorbell after every drain, which is what a host that predates pacing leaves there. +- **The grant.** Only a slot the embedding granted, that asked for bit 2 with bit 0, and while no + other live slot holds it. The region outlives every consumer, so the next granted consumer continues + from the same `tail`. + ## Security - The regions are anonymous `memfd`s with no filesystem name, so there is nothing for an unadmitted process to open; descriptors are passed only after admission succeeds. Each client receives - descriptors for the control region (read-only), the arena, and its own queue pair, and for - nothing else, so "never another client's rings" is enforced by the descriptor it was not given - rather than by permission bits on a shared object. + descriptors for the control region (read-only), the arena, its own queue pair, and, when granted, + the shared host doorbell and its own doorbell, and for nothing else, so "never another client's + rings" is enforced by the descriptor it was not given rather than by permission bits on a shared + object. +- A client can write the host doorbell and so wake the host spuriously. That costs no more than + publishing frames, which it may already do at any rate. It never receives another client's + doorbell. +- The telemetry region is metadata about every principal on the ring, so it goes only to the slot + the embedding grants, never by admission alone. Its consumer can scribble only on `tail` and + `consumer_waiting`, which can make the host count records lost or skip a wakeup, and cannot move + where the host writes. It reaches no payload, queue or arena through that grant. - The host is the only multi-queue reader/writer; a client cannot read another client's traffic, matching observer routing at the memory level, not only the API level. - Arena access is bounded to leased regions; a client cannot read arbitrary arena bytes outside its @@ -259,12 +370,14 @@ The spec is validated, not defined, by its implementations. All of the following - **Wire vectors**: shared encode/decode fixtures for headers, each message pattern, version negotiation, and error frames; the C, Go and Rust reference clients all produce and accept the exact bytes. Committed in `vectors/wire_vectors.tsv`, generated independently of every - codec by `vectors/gen_wire_vectors.py` (10 positive + 13 negative rows). + codec by `vectors/gen_wire_vectors.py` (14 positive and 16 negative rows). - **Interop**: the single C host (`c/conformance/host.c`) driven with an internal C client and a real Go or Rust client across a process boundary, exchanging notifications and request/replies in both directions, including `capability_absent` and arena payloads in all three patterns. Backpressure/credit exhaustion is a language-independent host and client-ring property, proven - in-process (`c/tests/test_flow.c`, and the clients' `would_block` paths). + in-process (`c/tests/test_flow.c`, and the clients' `would_block` paths). The same runs prove + doorbells in both directions and process liveness: the external client is woken while asleep, + wakes the host after an idle second, must be granted process liveness, and announces its detach. - **No-second-host**: exactly one host implementation; `scripts/check_single_host.sh` fails a second `ouro_host_create` and confirms the Go and Rust sides are client-only. - **Third-language proof**: the Rust client ([D11](decisions.md#d11-the-rust-reference-client-is-a-third-independent-client)), @@ -292,14 +405,16 @@ Answered in v0 (settled by the decisions in - ~~Exact slot size and inline-payload budget.~~ **Control-region parameters** read at attach, not wire fields (D4); provisional 256/192/1024 set in slice 3, the dispatch-overhead ceiling committed in `c/bench/baseline.json`. +- ~~Arena-payload routing: the host publishing a lease to the resolved observer set before + forwarding the reference.~~ **Routed by reference** (D12): the host publishes the lease to the + observer set at first sight, and a consumer in any process reads it through the lease view and + returns it with a release message. Still open for a later version (out of v0 scope): -- **Huge and streamed payloads** (chunking over the ring vs a dedicated arena stream). -- **Arena-payload routing**: the host publishing a lease to the resolved observer set before - forwarding the reference. The allocator exists (slice 4) and inline routing works; the composition - is a focused slice-4/6 follow-up. Arena-flagged frames are currently dropped-with-count, not - delivered to a consumer that could not read them. +- **Huge and streamed payloads** beyond module calls. Wire v3 fragments a module request or reply + up to 16 MiB; a notification above the inline budget still needs an arena lease, which only a + producer in the host's process can allocate. - **NUMA/placement** of the regions on multi-socket hosts. - **`shm_open` portability fallback**: v0 is Linux-only (`memfd_create`) by D1; a fallback carries its own threat-model note.