Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ jobs:
cache-dependency-path: go/go.sum
- name: Format
working-directory: go
run: test -z "$(gofmt -l ring)"
run: test -z "$(gofmt -l .)"
- name: Vet and test without cgo
working-directory: go
env:
Expand All @@ -94,7 +94,7 @@ jobs:
env:
CGO_ENABLED: "0"
OURO_CONFORMANCE_HOST: ${{ github.workspace }}/build/ouroboros-ring-conformance-host
run: go test -count=1 -run Conformance -v ./ring
run: go test -count=1 -run 'Conformance|CHost' -v ./ring ./otlpexport
- name: C module caller against the Go module process
run: |
cmake --build build --target ouroboros-ring-module-runtime-harness
Expand Down
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,16 @@ and pins a release of it like any other.
implementation would be. None links, imports or generates from another.
- **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, conformance, and
versions.
flow control, module calls, arena payloads, capture, telemetry, conformance,
and versions.

## Implementations

| Path | Language | What it is | Proven by |
|---|---|---|---|
| [`c/`](c/) | C11, POSIX/Linux | The host and a client, the module runtime, and the conformance host harness. `libouroboros-ring` (all of it) and `libouroboros-ring-client` (attach, wire, region, ring, module protocol: what a module process links) | `c/tests/` and the module runtime harness (17 tests, also under ASan/UBSan; the arena under TSan); dispatch overhead within the budget in `c/bench/baseline.json` |
| [`c/`](c/) | C11, POSIX/Linux | The host and a client, the module runtime, and the conformance host harness. `libouroboros-ring` (all of it) and `libouroboros-ring-client` (attach, wire, region, ring, module protocol: what a module process links) | `c/tests/` and the module runtime harness (19 tests, also under ASan/UBSan; the arena under TSan); dispatch overhead, with and without telemetry, within the budget in `c/bench/baseline.json` |
| [`go/`](go/) | Go, no cgo | Client, module caller and module runtime: `github.com/RakuenSoftware/ouroboros-ring/go/ring` | `go test ./...` with `CGO_ENABLED=0`; `scripts/check_go_no_cgo.sh` |
| [`go/cmd/ouroboros-ring-otlp/`](go/cmd/ouroboros-ring-otlp/) | Go | The reference telemetry exporter (D16): the one process a host grants its telemetry ring, sending every record to an OTLP collector. In the Go module, so a consumer builds it at the ring release it already pins; the `ring` package imports none of its OpenTelemetry dependencies | `go test -race`; `TestExportFromCHost` against the C host; `scripts/check_go_no_cgo.sh` keeps OpenTelemetry out of `go/ring` |
| [`rust/`](rust/) | Rust 2024 | Client, module caller and module runtime: crate `ouroboros-ring`, depending only on `libc` | `cargo test`; `rust/tests/c_host_conformance.rs` against the C host |

The host exists only in C. The Go and Rust implementations are clients
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.2.0
0.3.0
9 changes: 6 additions & 3 deletions c/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ set(OURO_CLIENT_SOURCES
src/module_runtime.c
src/region.c
src/ring.c
src/telemetry.c
src/wire.c)
set(OURO_HOST_SOURCES
src/arena.c
Expand All @@ -47,7 +48,8 @@ set(OURO_HOST_SOURCES
src/local_attach.c
src/region_host.c
src/route.c
src/runtime.c)
src/runtime.c
src/telemetry_host.c)

foreach(lib ouroboros-ring-client ouroboros-ring)
if(lib STREQUAL "ouroboros-ring")
Expand Down Expand Up @@ -95,11 +97,12 @@ if(BUILD_TESTING)
set(OURO_TEST_region src/region.c src/region_host.c src/ring.c)
set(OURO_TEST_arena src/arena.c src/region.c src/ring.c)
foreach(name host route flow client capture local_attach doorbell runtime
module_embedded_runtime module_client_pool)
module_embedded_runtime module_client_pool telemetry)
set(OURO_TEST_${name} ${OURO_ALL_SOURCES})
endforeach()
foreach(name ring wire endpoint module_protocol layout region arena host route flow client
capture local_attach doorbell runtime module_embedded_runtime module_client_pool)
capture local_attach doorbell runtime module_embedded_runtime module_client_pool
telemetry)
add_executable(test_${name} tests/test_${name}.c ${OURO_TEST_${name}})
target_compile_features(test_${name} PRIVATE c_std_11)
target_compile_options(test_${name} PRIVATE ${OURO_WARNINGS})
Expand Down
6 changes: 6 additions & 0 deletions c/bench/baseline.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@
"ceiling_ns": 1000,
"observed_ns": 134,
"observed_note": "measured when the benchmark lived in aimee (reference dev box). The ceiling carries ~7x headroom so CI variance does not flake the check while a per-event syscall still trips it."
},
"dispatch_overhead_telemetry_ns": {
"description": "The same dispatch with D16 telemetry on: the host writes one record per event and a consumer thread drains them as an exporter would (OURO_BENCH_TELEMETRY=1).",
"ceiling_ns": 1000,
"observed_ns": 100,
"observed_note": "measured 2026-10-30 on the reference dev box: 87 ns off, 100 ns on. Same headroom rule as dispatch_overhead_ns."
}
}
}
50 changes: 50 additions & 0 deletions c/bench/dispatch.c
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,43 @@
* It prints the lines scripts/check_perf_budget.sh parses:
* dispatch_overhead_ns=<median per-event nanoseconds>
* dispatch_overhead_p99_ns=<p99>
*
* With OURO_BENCH_TELEMETRY=1 the host also writes a D16 record per event, and
* a consumer thread drains them as an exporter would, so the same number shows
* what the hand-off adds.
*/
#define _GNU_SOURCE
#include <pthread.h>
#include <stdatomic.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <unistd.h>

#include <ouroboros/local_attach.h>
#include <ouroboros/telemetry.h>

static atomic_int telemetry_stop;
static atomic_ullong telemetry_drained;

static void *telemetry_drain(void *p)
{
ouro_telemetry_reader_t *r = p;
while (!atomic_load_explicit(&telemetry_stop, memory_order_relaxed))
{
uint64_t n = ouro_telemetry_available(r);
if (n == 0)
{
(void)ouro_telemetry_wait(r, -1, 10);
continue;
}
ouro_telemetry_release(r, n);
atomic_fetch_add_explicit(&telemetry_drained, n, memory_order_relaxed);
}
return NULL;
}

static uint64_t now_ns(void)
{
Expand Down Expand Up @@ -59,6 +87,19 @@ int main(int argc, char **argv)
attach_client(&h, &sub);
ouro_host_subscribe(&h, sub.reply.handle_id, KIND);

const char *tenv = getenv("OURO_BENCH_TELEMETRY");
int telemetry = tenv && strcmp(tenv, "1") == 0;
ouro_telemetry_reader_t reader;
pthread_t drainer;
if (telemetry)
{
if (ouro_host_telemetry_enable(&h, 0) != OURO_HOST_OK ||
ouro_telemetry_reader_open(dup(h.telemetry_region.fd), dup(h.telemetry_doorbell_fd),
&reader) != OURO_TELEMETRY_OK ||
pthread_create(&drainer, NULL, telemetry_drain, &reader) != 0)
abort();
}

/* One event's dispatch = publish (producer enqueue) + host pump (route) +
* poll (consumer dequeue). Batched to the ring's data capacity so timer
* granularity does not dominate; each batch's time is divided by its events.
Expand Down Expand Up @@ -115,6 +156,15 @@ int main(int argc, char **argv)
fprintf(stderr, "bench: %llu batches of %u events (median %llu ns/event, p99 %llu ns)\n",
(unsigned long long)batches, batch, (unsigned long long)median, (unsigned long long)p99);

if (telemetry)
{
atomic_store(&telemetry_stop, 1);
pthread_join(drainer, NULL);
fprintf(stderr, "bench: telemetry on, %llu records drained, %llu lost\n",
(unsigned long long)atomic_load(&telemetry_drained),
(unsigned long long)ouro_telemetry_dropped(&reader));
ouro_telemetry_reader_close(&reader);
}
free(samples);
ouro_client_detach(&pub);
ouro_client_detach(&sub);
Expand Down
15 changes: 14 additions & 1 deletion c/conformance/host.c
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,9 @@
* process liveness; the client's slot is never stale-reaped, so the next
* client getting the freed slot proves the departing one announced its
* detach.
* - D16: telemetry is on, and an external client attaching as principal_ref
* CONFORMANCE_TELEMETRY_PRINCIPAL is granted the consumer end, so it reads
* the record of every event it caused, its own and the C side's answers.
*
* Usage: ouroboros-ring-conformance-host <socket-path> [timeout-ms]
* It listens, accepts exactly one external client, pumps and services until the
Expand Down Expand Up @@ -166,12 +169,16 @@ static ouro_attach_status_t admit_peer(void *ctx, int fd, const ouro_attach_requ
return OURO_ATTACH_OK;
}

#define CONFORMANCE_TELEMETRY_PRINCIPAL 0x7E1Eu

static ouro_attach_status_t bind_peer(void *ctx, ouro_host_t *h, uint32_t slot,
const ouro_attach_request_t *request)
{
(void)ctx, (void)request;
(void)ctx;
if (g_peer_known)
(void)ouro_host_bind_process(h, slot);
if (request->principal_ref == CONFORMANCE_TELEMETRY_PRINCIPAL)
(void)ouro_host_grant_telemetry(h, slot);
return OURO_ATTACH_OK;
}

Expand Down Expand Up @@ -208,6 +215,12 @@ int main(int argc, char **argv)
return 1;
}

if (ouro_host_telemetry_enable(&h, 256) != OURO_HOST_OK)
{
fprintf(stderr, "telemetry enable failed\n");
return 1;
}

/* Internal C client: subscribes to KIND_NOTIFY and serves KIND_ECHO. */
ouro_client_t cc;
if (attach_internal(&h, &cc) != 0)
Expand Down
9 changes: 8 additions & 1 deletion c/include/ouroboros/attach.h
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +13,25 @@
* so it carries OURO_ATTACH_FDS_DOORBELL. */
#define OURO_ATTACH_FDS 3
#define OURO_ATTACH_FDS_DOORBELL 5
#define OURO_ATTACH_FDS_MAX OURO_ATTACH_FDS_DOORBELL
/* D16: a telemetry grant adds the telemetry region and its doorbell. */
#define OURO_ATTACH_FDS_TELEMETRY 7
#define OURO_ATTACH_FDS_MAX OURO_ATTACH_FDS_TELEMETRY
#define OURO_ATTACH_FD_CONTROL 0
#define OURO_ATTACH_FD_ARENA 1
#define OURO_ATTACH_FD_QPAIR 2
#define OURO_ATTACH_FD_HOST_DOORBELL 3
#define OURO_ATTACH_FD_CLIENT_DOORBELL 4
#define OURO_ATTACH_FD_TELEMETRY 5
#define OURO_ATTACH_FD_TELEMETRY_BELL 6

/* Attach capabilities (D13): requested in the request, granted in the reply. */
#define OURO_ATTACH_CAP_DOORBELL 0x00000001u
/* D15: the host holds an OS handle on the client's process and releases its slot
* when the process exits, so the client need not heartbeat on a timer. */
#define OURO_ATTACH_CAP_PROCESS_LIVENESS 0x00000002u
/* D16: the consumer end of the host's telemetry ring. Granted only with the
* doorbell, to the one slot the embedding granted it. */
#define OURO_ATTACH_CAP_TELEMETRY 0x00000004u

/* The v0 request was the first 16 bytes of ouro_attach_request_t. A host still
* accepts it, and an older host reads only those 16 bytes of a longer one. */
Expand Down
30 changes: 30 additions & 0 deletions c/include/ouroboros/host.h
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
#include <ouroboros/attach.h>
#include <ouroboros/arena.h>
#include <ouroboros/region_host.h>
#include <ouroboros/telemetry.h>
#include <ouroboros/wire.h>

/* A directory slot — host-private. A client never sees this or any other slot. */
Expand Down Expand Up @@ -97,6 +98,9 @@ typedef struct
/* D15: the runtime holds a process handle for this client and releases the
* slot when the process exits, so the heartbeat reap passes it by. */
int process_bound;

/* D16: the embedding granted this slot the telemetry consumer end. */
int telemetry_granted;
} ouro_slot_t;

/* Per-kind overflow policy (D5). Block is the safe default: a full destination
Expand Down Expand Up @@ -207,6 +211,21 @@ typedef struct ouro_host
/* D13: the host doorbell every doorbell client writes; -1 if it could not be
* created, in which case no client is granted one and the caller polls. */
int doorbell_fd;

/* D16: the telemetry ring, written as each event is stamped. telemetry is
* NULL until ouro_host_telemetry_enable. telemetry_slot is the slot holding
* the consumer end, UINT32_MAX for none. */
ouro_region_t telemetry_region;
ouro_telemetry_region_t *telemetry;
ouro_ring_t telemetry_ring;
int telemetry_doorbell_fd;
uint32_t telemetry_slot;
uint64_t telemetry_head; /* the producer index, kept locally */
uint64_t telemetry_tail_cache; /* the consumer index as last read */
uint64_t telemetry_now; /* this pump's realtime, read at its first stamp */
uint64_t telemetry_lost; /* records lost since the last gap record */
int telemetry_unsignalled; /* written since the consumer was last signalled */
int in_pump; /* signal once at the end of the pump, not per event */
} ouro_host_t;

typedef enum
Expand Down Expand Up @@ -298,6 +317,17 @@ const char *ouro_attach_status_name(ouro_attach_status_t s);
/* Set the governance/audit tap. Pass NULL to clear. */
void ouro_host_set_tap(ouro_host_t *h, ouro_tap_fn fn, void *ctx);

/* D16: create the telemetry ring of `capacity` records (0: the default). From
* then on every seq-stamped event writes one record before the tap is called.
* Call before any client may ask for the grant. */
ouro_host_result_t ouro_host_telemetry_enable(ouro_host_t *h, uint32_t capacity);

/* D16: grant `slot` the telemetry consumer end. The embedding calls it from its
* attach hook, for the one principal it trusts with metadata about every event;
* the host then hands that client the region if it asked and no other live slot
* holds it. */
ouro_host_result_t ouro_host_grant_telemetry(ouro_host_t *h, uint32_t slot);

/* Set the rare loss observer. Pass NULL to clear. */
void ouro_host_set_loss_sink(ouro_host_t *h, ouro_loss_fn fn, void *ctx);

Expand Down
1 change: 1 addition & 0 deletions c/include/ouroboros/runtime.h
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ typedef struct
size_t request_count;
const uint32_t *serve;
size_t serve_count;
int telemetry; /* D16: hand this principal the telemetry consumer end */
} ouro_runtime_grant_t;

typedef struct ouro_runtime ouro_runtime_t;
Expand Down
Loading
Loading