shoney/writeonce
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
writeonce/docs/stories/language-runtime-database/08-shard-actor-runtime.md
shoney.arickathil 71d3985e81 docs: performance arc as story iterations (9e measure, 9f io_uring) 
- 9e durability/throughput/scale: the measurement backbone -- run the
  employee program, restart to prove persistence, benchmark read/write
  through compiled .wo, ~1M-row mixed load with throughput floor + p99
  ceiling + flat RSS; the gate every optimization signs (before/after
  delta required, no measured delta = not accepted)
- 9f io_uring group-commit: replace fsync-per-commit with batched
  io_uring durability overlapped on shard threads; same ack-after-
  durable contract, crash battery unchanged, automatic fsync fallback
  on kernels without it; deliberately LAST (needs 8's threads to
  overlap and 9e's baseline to beat)
- wired the existing levers into the arc: iteration 8 (thread-per-core)
  = "optimize multithreading", 7b (mark-sweep) = "implement GC" --
  each now gated by re-running 9e and recording the delta
- explicit sequence recorded in 9e: 9b lands -> 9e baseline -> 7b
  re-bench -> 8 re-bench -> 9f re-bench
- roadmap + board rows for 9e/9f; four forks each for the specs
  (load generator, absolute vs relative budgets, what "1M" means,
  durable vs RAM headline; ring model, liburing vs raw, batch
  boundary, fallback testing)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-15 22:12:48 +02:00

2.4 KiB
Raw Blame History

Iteration 8 — shard-actor runtime

Format: product/story-iteration-template. Part of Story — one language, one runtime, one database, one binary.

Goals

  • The runtime scales past one core the doctrine way: pinned thread-per-core shards, each owning its own heap and event loop; cross-shard communication is a message send that moves ownership — shared mutable state never exists.
  • The language grows spawn and message send; garbage collection stays per-shard, so no global pause appears at any core count.

Acceptance Criteria

  • What to achieve?
    • Given a program spawning actors across shards,
    • when an owned object is sent to another shard,
    • then the sender can no longer touch it (compile-time move), the receiver owns it, and its eventual free routes back to its allocation-home arena.
  • What to achieve?
    • Given debug builds with shard-ownership asserts,
    • when the deterministic actor corpus runs under ASan and TSan,
    • then zero races, zero leaks, and identical output across runs.
  • What to achieve?
    • Given a @gc reference,
    • when code attempts to send it cross-shard,
    • then the compiler rejects it — aliased references cannot cross heap boundaries.

Out Of Scope

  • Fibers/green threads (recorded in the blue-green vision §3; extends this scheduler later).
  • Cross-shard transactions (the database iteration's 2PC concern, later).

Info

  • The C reference (runtime/wo-rt.c, phases A–F) is the substrate: epoll loops, eventfd mail, the machinery this iteration lifts into wovm.
  • The VM's object header has carried a shard id since iteration 2 — no relayout.
  • Gated by the benchmark (2026-08-15): this is the "optimize multithreading" lever of the performance arc — thread-per-core is a throughput/scale claim, so landing it means re-running iteration 9e at the connection/concurrency scale it unlocks and recording the before/after delta. It is also where the io_uring write path (9f) gets a thread to overlap durability against.

Proposed Solution

  • Execute the existing plan: docs/superpowers/plans/2026-08-01-shard-actor-vm-runtime.md (pinned-worker scheduler, shard-stamped heaps, MPSC mailbox rings + mail eventfds, send-as-move with home-routed frees, gc pacing per tick, spawn/send surface, actor corpus).