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).
|
|||
|
|
|