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.