50 lines
2.6 KiB
Markdown
50 lines
2.6 KiB
Markdown
|
# Using Resolution and Runtime Dispatch — Design Overview (SSOT + AST, Phase‑15)
|
|||
|
|
|
|||
|
|
Purpose
|
|||
|
|
- Make name/module resolution deterministic at build time while keeping runtime dispatch only for plugin/extern paths.
|
|||
|
|
- Preserve the language surface (`obj.method()`) and guarantee it executes in prod without runtime fallbacks.
|
|||
|
|
|
|||
|
|
Key Principles
|
|||
|
|
- Single Source of Truth (SSOT): `nyash.toml` governs using packages/aliases.
|
|||
|
|
- Profiles: dev|ci|prod
|
|||
|
|
- prod: file‑using is rejected; only toml packages/aliases are allowed; AST prelude merge is required when using is present.
|
|||
|
|
- dev/ci: file‑using can be enabled via env; AST prelude merge on by default.
|
|||
|
|
- Static resolution at using time:
|
|||
|
|
- Strip `using` lines, collect prelude source paths, parse each to AST, and merge before macro expansion.
|
|||
|
|
- Materialize user box methods as standalone functions: `Box.method/Arity`.
|
|||
|
|
- Builder rewrites instance calls: `obj.m(a)` → call `Box.m/Arity(obj,a)`.
|
|||
|
|
- Runtime resolution:
|
|||
|
|
- Plugin/extern dispatch remains dynamic.
|
|||
|
|
- User instance BoxCall fallback (VM) is disallowed in prod to catch builder misses; dev/ci may allow with WARN.
|
|||
|
|
|
|||
|
|
Environment Knobs (Summary)
|
|||
|
|
- Using system
|
|||
|
|
- `NYASH_ENABLE_USING` (default ON)
|
|||
|
|
- `NYASH_USING_PROFILE={dev|ci|prod}` (default dev)
|
|||
|
|
- `NYASH_USING_AST=1|0` (dev/ci default ON; prod default OFF)
|
|||
|
|
- `NYASH_ALLOW_USING_FILE=1|0` (default OFF; dev only when needed)
|
|||
|
|
- Builder
|
|||
|
|
- `NYASH_BUILDER_REWRITE_INSTANCE=1|0` (default ON across profiles)
|
|||
|
|
- VM
|
|||
|
|
- `NYASH_VM_USER_INSTANCE_BOXCALL=1|0` (default: prod=0, dev/ci=1)
|
|||
|
|
|
|||
|
|
Code Responsibilities
|
|||
|
|
- Using resolution (static)
|
|||
|
|
- Entry: `src/runner/modes/common_util/resolve/resolve_prelude_paths_profiled`
|
|||
|
|
- Core: `collect_using_and_strip` (SSOT enforcement, path/alias/package resolution, profile gates)
|
|||
|
|
- Consumers: all runners (VM, LLVM/harness, PyVM, selfhost) call the same helper to avoid drift.
|
|||
|
|
- Builder (lowering)
|
|||
|
|
- Instance→Function rewrite and method materialization live in `src/mir/builder/*`.
|
|||
|
|
- VM (runtime)
|
|||
|
|
- User Instance BoxCall fallback gate in `src/backend/mir_interpreter/handlers/boxes.rs`.
|
|||
|
|
|
|||
|
|
Testing Strategy
|
|||
|
|
- Prod safety: obj.method() works under prod with runtime fallback disabled (rewrite required).
|
|||
|
|
- Smoke: `tools/smokes/v2/profiles/quick/core/oop_instance_call_vm.sh` (prod + forbid VM fallback)
|
|||
|
|
- Using/AST parity: quick/integration call `resolve_prelude_paths_profiled` from all runner modes.
|
|||
|
|
|
|||
|
|
Future Small Refactors (non‑behavioral)
|
|||
|
|
- Factor a helper to parse prelude paths into ASTs (single place), and use it from all runners.
|
|||
|
|
- Add dev‑only WARN when a candidate `Box.method/Arity` is missing from `module.functions` during rewrite.
|
|||
|
|
|