42 lines
1.4 KiB
Markdown
42 lines
1.4 KiB
Markdown
# Box Design Checklist (docs-only)
|
||
|
||
Use this checklist when introducing a new Box or evolving an existing one.
|
||
|
||
## Lifecycle
|
||
- Define birth parameters and side effects (allocation, registration).
|
||
- State machine: initial → running → closed → fini; reentrancy rules.
|
||
- `fini()` idempotent; post-fini methods: error vs no-op.
|
||
|
||
## Ownership & Sharing
|
||
- Who owns the resource? Is there a LeaseBox form?
|
||
- Mutation boundaries (single-thread/Actor only?).
|
||
- Cross-thread usage: mailbox-only or direct allowed?
|
||
|
||
## Concurrency
|
||
- Blocking APIs: provide `try_*` and `*_timeout(ms)`.
|
||
- Cancellation: accept CancelToken/Deadline; ensure prompt unblock.
|
||
- Busy-wait forbidden; document waiting strategy (Phase‑0 cooperative / later OS).
|
||
|
||
## Close Semantics
|
||
- What does `close()` mean? Which ops fail after close?
|
||
- Draining behavior and End marker shape.
|
||
- Double close and use-after-close handling.
|
||
|
||
## Observability
|
||
- Events to emit (op, ok, extra fields) and Box ID.
|
||
- Env toggles (e.g., `NYASH_*_TRACE=1`).
|
||
- Expected order/causality in traces.
|
||
|
||
## Capabilities & Affinity
|
||
- External authorities needed (fs/net/io/thread).
|
||
- Thread affinity constraints (creator thread / any / Actor only).
|
||
|
||
## Performance
|
||
- Hot vs cold paths; offer ThinBox where needed.
|
||
- Complexity of operations; backpressure strategy.
|
||
|
||
## Errors & Types
|
||
- Error shape (Bool/Option/Result) and consistency with ecosystem.
|
||
- Type expectations (runtime tags vs future static types).
|
||
|