78 lines
3.6 KiB
Markdown
78 lines
3.6 KiB
Markdown
# Nyash Concurrency — Box Model (Proposal, docs-only)
|
||
|
||
Status: design-only during the feature‑pause. No runtime or spec changes. Implement after Mini‑VM baseline is stable.
|
||
|
||
Intent
|
||
- Bring Go-like CSP (goroutine/channels/select) into Nyash via “Everything is Box”.
|
||
- Keep semantics explicit, lifecycle safe (birth/fini), and observable. Phase-in from userland → runtime.
|
||
|
||
Scope (Phase‑0: userland MVP)
|
||
- RoutineBox: lightweight task wrapper over `nowait` (state, join/cancel, status).
|
||
- ChannelBox: bounded/unbounded queue + blocking/non-blocking ops + close semantics.
|
||
- SelectBox: multi-channel wait (first-ready) with simple fairness.
|
||
- RoutineScopeBox: structured concurrency; children are canceled on scope fini.
|
||
- Observability: JSONL trace toggled by `NYASH_CONC_TRACE=1`.
|
||
|
||
Non‑Goals (Phase‑0)
|
||
- M:N scheduler, OS-level park/unpark, net poller integration (deferred to Phase‑2 runtime work).
|
||
|
||
API Sketch (userland)
|
||
- RoutineBox
|
||
- birth(fn)
|
||
- start(): Void
|
||
- join(timeout_ms?: Int) -> Bool // true if joined; false on timeout
|
||
- cancel(): Void
|
||
- status() -> String // ready|running|done|canceled|error
|
||
- ChannelBox(capacity: Int=0)
|
||
- send(v): Void // blocks if full (Phase‑0: simulated park)
|
||
- try_send(v) -> Bool
|
||
- receive() -> Any // blocks if empty (Phase‑0: simulated park)
|
||
- try_receive() -> (Bool, Any?)
|
||
- receive_timeout(ms: Int) -> (Bool, Any?)
|
||
- close(): Void // further send fails; recv drains until empty then End
|
||
- SelectBox
|
||
- birth()
|
||
- when(ch: ChannelBox, handler: Fn): Void
|
||
- await() -> Bool // returns after one handler runs; false if none ready and no wait policy
|
||
- await_timeout(ms: Int) -> Bool
|
||
- RoutineScopeBox
|
||
- birth()
|
||
- spawn(fn) -> RoutineBox
|
||
- fini() // cancels pending routines and waits boundedly
|
||
|
||
Semantics
|
||
- Capacity:
|
||
- 0: rendezvous channel (send/recv rendezvous).
|
||
- N>0: bounded ring buffer.
|
||
- Close:
|
||
- close() marks channel as closed. send() after close -> error. receive() returns buffered items; when empty -> (false, End) style result; exact return shape defined per API.
|
||
- Blocking:
|
||
- Phase‑0 userland uses cooperative wait queues; no busy loops. try_* and timeout variants provided.
|
||
- Select fairness:
|
||
- If multiple ready, choose random/round‑robin. Starvation avoidance is a design requirement; precise algorithm can evolve.
|
||
- Types:
|
||
- `TypedChannelBox<T>` is a future extension; Phase‑0 uses runtime tags/guards documented in reference.
|
||
- Cancellation:
|
||
- RoutineScopeBox cancels children on fini; Channel waits should return (canceled) promptly.
|
||
|
||
Phases
|
||
- Phase‑0 (userland MVP / PyVM first)
|
||
- Implement the 4 boxes above with minimal queues/waits, plus trace hooks.
|
||
- Smokes: ping‑pong, bounded producer/consumer, two‑way select, close semantics, scope cancel.
|
||
- Phase‑1 (park/unpark abstraction)
|
||
- Introduce `WaiterBox`/`CondBox` that map to efficient OS waits where available. Keep same APIs.
|
||
- Phase‑2 (runtime integration)
|
||
- Scheduler (M:N), GC and net poller integration, fairness and profiling. Keep Box APIs stable.
|
||
|
||
Observability
|
||
- `NYASH_CONC_TRACE=1` → JSONL events: spawn/join/cancel/send/recv/park/unpark/select/close with routine IDs, channel IDs, timestamps.
|
||
|
||
Safety & Diagnostics
|
||
- Deadlock hints: trace dependent waits; optional detector (dev only) can dump wait‑for graph.
|
||
- API contracts explicitly define error return for misuse (send on closed, double close, etc.).
|
||
|
||
Deliverables (docs‑only during the feature‑pause)
|
||
- This proposal (boxes & semantics).
|
||
- Reference page with blocking/close/select rules (see reference/concurrency/semantics.md).
|
||
- Test plan with named smokes and expected outputs.
|