50 lines
2.1 KiB
Markdown
50 lines
2.1 KiB
Markdown
# Box Patterns (dev guide; docs-only)
|
||
|
||
Status: design notes to standardize reusable Box idioms. No runtime/spec change during the feature‑pause.
|
||
|
||
## OwnershipBox / LeaseBox
|
||
- Intent: make ownership vs borrowing explicit for resource Boxes.
|
||
- Rules
|
||
- OwnershipBox owns the underlying handle; calls `fini()` on drop.
|
||
- LeaseBox references an owned Box without taking responsibility to `fini()`.
|
||
- Upgrading a lease to ownership must be explicit (and validated).
|
||
- Smells avoided: double-close, leaked handles, implicit transfer.
|
||
|
||
## CancelTokenBox / DeadlineBox
|
||
- Intent: structured cancellation and time limits across waiting APIs.
|
||
- Rules
|
||
- Token can be passed to blocking APIs (Channel/Select/Waiter) to abort waits.
|
||
- DeadlineBox wraps an absolute time; APIs accept either `token` or `deadline`.
|
||
- Cancellation is idempotent; multiple cancel calls are safe.
|
||
- Effects
|
||
- Waiting ops return promptly with a well-typed cancel/timeout indicator.
|
||
|
||
## CapabilityBox
|
||
- Intent: define minimal authority (I/O, net, thread, fs) explicitly.
|
||
- Rules
|
||
- Boxes that access external capabilities must declare the capability dependency.
|
||
- Tests can substitute Noop/Mock capability Boxes.
|
||
- Effects
|
||
- Principle of least privilege; easier sandboxing and auditing.
|
||
|
||
## AffinityBox
|
||
- Intent: encode thread/runtime affinity constraints.
|
||
- Rules
|
||
- Annotate Boxes that must be used on their creator thread or via Actor mailbox.
|
||
- Violations produce early, explicit errors (not UB).
|
||
- Effects
|
||
- Predictable behavior across concurrency boundaries.
|
||
|
||
## ObservableBox
|
||
- Intent: unify tracing/metrics hooks.
|
||
- Rules
|
||
- Emit JSONL events with `ts`, `box_id`, `op`, `ok`, and domain-specific fields.
|
||
- Allow opt-in (`NYASH_*_TRACE=1`) and keep logs stable for tooling.
|
||
- Effects
|
||
- Cross-cutting visibility with one schema; simpler troubleshooting.
|
||
|
||
## Composition Tips
|
||
- Separate hot/cold paths: ThinBox (hot) vs RichBox (full) to avoid overhead on the critical path.
|
||
- Prefer immutable handles + message passing across threads (Actor) to avoid races.
|
||
- Keep `birth/fini` idempotent; document post-fini behavior (no-op vs error).
|