shoney.arickathil
57b4b56eae
- done/ (11): 1, 2, 3, 4, 6, 7, 7b, 9, 9b, 15, 16 — landed iterations (9/9b remainders live in the post-12 drain list, not in the files) - refine/ (8): 9c, 9d, 9e, 9f, 9g, 11, 13, 14 — everything marked "no spec yet / brainstorm before planning" - root keeps: 00-story (index), 05 (partial, plan 8 open), 8/10/12 (specs or plans exist), 17 (parked, spec+plan approved), 18 (next) - every cross-reference re-pathed and VERIFIED resolving: board, specs, plans, employee-list README, story table, intra-story links (moved files' relative links deepened one level; done/7b's 9e pointer now crosses to refine/) - pre-existing dead link noted, not touched: refine/11-fibers.md points at docs/plan/exploration/fibers/00-fibers.md which does not exist (predates the move) Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
78 lines
3.7 KiB
Markdown
78 lines
3.7 KiB
Markdown
# Iteration 11 — fibers (green threads on the shard scheduler)
|
|
|
|
> Format: fiberloom `product/story-iteration-template`. Part of
|
|
> [Story — one language, one runtime, one database, one binary](../00-story.md).
|
|
|
|
## Goals
|
|
|
|
- Concurrency **inside** a shard the doctrine way: cooperative fibers
|
|
scheduled by the VM — a fiber is the interpreter state wovm already
|
|
isolates (register windows + frame stack + pc), made per-fiber. One
|
|
kernel task per core stays the rule; thousands of fibers run above it
|
|
where the kernel tops out at hundreds of threads (CFS O(log N),
|
|
~8 MiB + ~20 µs per thread vs an arena-allocated fiber context).
|
|
- **Preemption by reduction budget**, the Erlang shape: the dispatch loop
|
|
counts down and parks the fiber at zero — no signals, no safepoints, no
|
|
stack copying, deterministic replay.
|
|
- **Blocking builtins park instead of block** on server shards: the same
|
|
`net`/`time`/`fs` calls that block the thread in program mode hand their
|
|
fd to the shard's epoll/io_uring loop and resume on completion. One API,
|
|
same source text, no async/await, no function coloring — ever.
|
|
- Cross-fiber sends follow the iteration 8 rule — ownership moves — on the
|
|
cheaper same-heap path.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- What to achieve?
|
|
- **Given** a shard running thousands of spawned fibers with one hot
|
|
compute loop among them,
|
|
- **when** the reduction budget expires,
|
|
- **then** the hot fiber parks, every other fiber makes progress
|
|
(starvation-free corpus fixture), and output is identical across
|
|
runs (deterministic scheduling).
|
|
- What to achieve?
|
|
- **Given** a fiber blocked in a stdlib builtin on a server shard,
|
|
- **when** the completion arrives on the shard's event loop,
|
|
- **then** the fiber resumes with the result while the shard served
|
|
other fibers in the interim — one OS thread, verified by TID.
|
|
- What to achieve?
|
|
- **Given** a parked fiber at shard shutdown,
|
|
- **when** the shard unwinds it,
|
|
- **then** every drop map runs (ASan zero leaks) — parked fibers die
|
|
as cleanly as trapped ones. (Iteration 12's blue-green drain reuses
|
|
exactly this unwind path.)
|
|
- What to achieve?
|
|
- **Given** `@gc` objects referenced only from a parked fiber's frames,
|
|
- **when** the per-shard cycle collector scans,
|
|
- **then** fiber stacks are roots — nothing live is collected, nothing
|
|
dead survives.
|
|
|
|
## Out Of Scope
|
|
|
|
- Fiber migration across shards (ownership doctrine forbids it; cross-shard
|
|
is a message send, iteration 8).
|
|
- Priorities, timers, structured-concurrency policy — recipe-box
|
|
capabilities for a later `.wo` library, not runtime policy.
|
|
- Program mode: stays single-fiber in v1 (blocking legal, log-watcher
|
|
needs nothing more).
|
|
- async/await keyword — permanently rejected surface, not deferred.
|
|
|
|
## Info
|
|
|
|
- Research note: [`docs/plan/exploration/fibers/00-fibers.md`](../../../plan/exploration/fibers/00-fibers.md)
|
|
— kernel's-eye evidence (task_struct costs, CFS collapse at high task
|
|
counts) and the precedent survey (BEAM reductions adopted; Go stack
|
|
copying and Tokio coloring rejected; Loom's park-under-blocking-API
|
|
matches the stdlib posture).
|
|
- Vision origin: [blue-green vision §3](../../../plan/exploration/blue-green-vm/00-vision.md);
|
|
iteration 8's scheduler is the substrate this extends.
|
|
- Open questions to settle in the spec: spawn surface (handle vs actor
|
|
address), budget size and check granularity, parked-fiber drop
|
|
semantics, run-queue fairness (FIFO v1).
|
|
|
|
## Proposed Solution
|
|
|
|
- No implementation plan exists yet — this iteration starts with the
|
|
brainstorming → spec → writing-plans chain (the superpowers path every
|
|
prior iteration followed), then executes that plan. The research note
|
|
above is the brainstorm's entry material.
|