selfhost(pyvm): MiniVmPrints – prefer JSON route early-return (ok==1) to avoid fallback loops; keep default behavior unchanged elsewhere
This commit is contained in:
Selfhosting Dev
@ -1,109 +0,0 @@
|
||||
# Nyash VM 実行基盤ガイド
|
||||
|
||||
最終更新: 2025-08-21（Phase 9.78 系対応）
|
||||
|
||||
本書は Nyash の VM バックエンド（MIR 実行機構）と、その周辺の実装・拡張ポイントをまとめた開発者向けドキュメントです。
|
||||
|
||||
## 全体像
|
||||
- 入力: `MirModule`（`mir::MirCompiler` が AST から生成）
|
||||
- 実行: `backend::vm::VM`
|
||||
- `execute_module` → `execute_function` → 命令列を逐次 `execute_instruction`
|
||||
- ランタイム DI: `NyashRuntime`
|
||||
- `box_registry`（統一 BoxFactory 経由の生成）
|
||||
- `box_declarations`（ユーザー定義 Box の宣言）
|
||||
- ライフサイクル: `ScopeTracker` により関数入退出で `fini()` を呼ぶ
|
||||
|
||||
## 主要ファイル
|
||||
- `src/backend/vm.rs` … VM 本体（命令ディスパッチ、Call/BoxCall、NewBox ほか）
|
||||
- `src/mir/*` … MIR 命令定義・Builder・Function/Module 管理
|
||||
- `src/runtime/nyash_runtime.rs` … ランタイムコンテナ（DI 受け皿）
|
||||
- `src/box_factory/*` … Builtin/User/Plugin の各 Factory 実装
|
||||
- `src/runtime/plugin_loader_v2.rs` … BID-FFI v2 ローダ（ExternCall/Plugin 呼び出し）
|
||||
|
||||
関連ドキュメント
|
||||
- 動的プラグインの流れ: [dynamic-plugin-flow.md](./dynamic-plugin-flow.md)
|
||||
- 命令セットダイエット: [mir-26-instruction-diet.md](./mir-26-instruction-diet.md)
|
||||
- MIR→VMマッピング: [mir-to-vm-mapping.md](./mir-to-vm-mapping.md)
|
||||
|
||||
## 実行フロー（概略）
|
||||
1) Nyash コード → Parser → AST → `MirCompiler` で `MirModule` を生成
|
||||
2) `VM::with_runtime(runtime)` で実行（`execute_module`）
|
||||
3) 命令ごとに処理:
|
||||
- `Const/Load/Store/BinOp/...` など基本命令
|
||||
- `NewBox`: 統一レジストリ経由で Box 生成
|
||||
- `Call`: `"{Box}.{method}/{N}"` の関数名で MIR 関数呼び出し
|
||||
- `BoxCall`: Box の種類で分岐（ユーザー定義/ビルトイン/プラグイン）
|
||||
- `ExternCall`: `env.console`/`env.canvas` 等をローダへ委譲
|
||||
|
||||
## Box 生成と種別
|
||||
- 生成パス（`NewBox`）は `NyashRuntime::box_registry` が担当
|
||||
- Builtin: `BuiltinBoxFactory` が直接生成
|
||||
- User-defined: `UserDefinedBoxFactory` → `InstanceBox`
|
||||
- Plugin: プラグイン設定（`nyash.toml`）に従い BID-FFI で `PluginBoxV2`
|
||||
- **動的解決の詳細**: [dynamic-plugin-flow.md](./dynamic-plugin-flow.md) を参照
|
||||
|
||||
## birth/メソッドの関数化（MIR）
|
||||
- Lowering ポリシー: AST の `new` は `NewBox` に続けて `BoxCall("birth")` を自動挿入
|
||||
- Box 宣言の `birth/N` と通常メソッド `method/N` は `"{Box}.{name}/{N}"` の MIR 関数に関数化
|
||||
- 命名例: `Person.birth/1`, `Person.greet/0`
|
||||
- 引数: `me` が `%0`、ユーザー引数が `%1..N`（`me` は `MirType::Box(BoxName)`）
|
||||
- 戻り値型: 明示の `return <expr>` があれば `Unknown`、なければ `Void`（軽量推定）
|
||||
- `VM` の呼び出し
|
||||
- `Call` 命令: 関数名（`Const(String)`）を解決 → `call_function_by_name`
|
||||
- `BoxCall` 命令: 下記の種類分岐に委譲
|
||||
|
||||
## BoxCall の種類分岐
|
||||
- ユーザー定義 Box（`InstanceBox`）
|
||||
- `BoxCall("birth")`: `"{Box}.birth/{argc}"` を `Call` 等価で実行
|
||||
- 通常メソッド: `"{Box}.{method}/{argc}"` を `Call` 等価で実行
|
||||
- プラグイン Box（`PluginBoxV2`）
|
||||
- `PluginLoaderV2::invoke_instance_method(box_type, method, instance_id, args)` を呼び出し
|
||||
- 引数/戻り値は最小 TLV でやり取り（タグ: 1=Int64, 2=String, 3=Bool）
|
||||
- 戻り値なしは `void` 扱い
|
||||
- ビルトイン Box
|
||||
- 現状は VM 内の簡易ディスパッチ（`String/Integer/Array/Math` を中心にサポート）
|
||||
- 将来はビルトインも MIR 関数へ寄せる計画
|
||||
|
||||
## ExternCall（ホスト機能）
|
||||
- `env.console.log`, `env.canvas.*` などを `PluginLoaderV2::extern_call` に委譲
|
||||
- いまは最小実装（ログ出力・スタブ）。将来は BID-FFI 由来の外部機能にも接続予定
|
||||
|
||||
## ライフサイクル管理（ScopeTracker）
|
||||
- `VM` は関数入退出で `push_scope()/pop_scope()` を実行
|
||||
- 退出時に登録 Box を `fini()`（`InstanceBox`/`PluginBoxV2`）
|
||||
- Interpreter でも同思想で `restore_local_vars()` にて `fini()` 呼び出し
|
||||
|
||||
## ランタイム DI（依存注入）
|
||||
- `NyashRuntime`
|
||||
- `box_declarations`: AST から収集（Box 宣言）
|
||||
- `box_registry`: Builtin/User/Plugin の順で探索・生成
|
||||
- Runner（CLI 実行）
|
||||
- AST パース後、Box 宣言を `runtime.box_declarations` へ登録
|
||||
- `UserDefinedBoxFactory` をレジストリに注入 → VM を `with_runtime(runtime)` で起動
|
||||
|
||||
## 最適化
|
||||
- 置換: `new X(...).m(...)` → 直接 `Call("X.m/N", me+args)` に最適化
|
||||
- 拡張余地: 変数へ束縛してからの `.m()` も静的に決まる範囲で `Call` 化可能
|
||||
- 戻り値型: 軽量推定。将来は `MirType` 推論/注釈の強化
|
||||
|
||||
## 制約と今後
|
||||
- ビルトインのメソッドはまだ簡易ディスパッチ（MIR 関数化は未）
|
||||
- プラグインの TLV は最小型（Int/String/Bool）のみ。拡張予定
|
||||
- 例外（throw/catch）は簡易扱い（将来の unwind/handler 連携は別設計）
|
||||
|
||||
## テスト
|
||||
- 単体/E2E（抜粋）: `src/backend/vm.rs` の `#[cfg(test)]`
|
||||
- `test_vm_user_box_birth_and_method` … `new Person("Alice").greet()` → "Hello, Alice"
|
||||
- `test_vm_user_box_var_then_method` … 変数に束縛→メソッド→戻り値（11）
|
||||
- `test_vm_extern_console_log` … ExternCall の void 確認
|
||||
- 実行例
|
||||
- `cargo test -j32`（plugins 機能や環境依存に注意）
|
||||
|
||||
## 実行（参考）
|
||||
- VMルート実行（Runner 経由）
|
||||
- `nyash --backend vm your_file.nyash`
|
||||
- WASM（ブラウザ）
|
||||
- plugins は無効。ExternCall はスタブ。MIR 関数はそのまま再利用される設計
|
||||
|
||||
---
|
||||
開発ポリシー: 小さく安全に最適化 → MIR/VM の共有ロジックを増やす → Extern/Plugin を段階統合 → WASM/LLVM/JIT へ横展開。
|
||||
@ -1,108 +0,0 @@
|
||||
# Nyash 設計図（アーキテクチャ概要）
|
||||
|
||||
最終更新: 2025-08-21（Phase 9.78b〜3 反映）
|
||||
|
||||
本書はNyashの実装設計を、バックエンド共通で理解できる単一ドキュメントとしてまとめたもの。言語コア、MIR、インタープリター/VM統合、ランタイム/プラグイン、ビルドと配布の観点を俯瞰する。
|
||||
|
||||
## レイヤー構成
|
||||
|
||||
- 構文/AST: `tokenizer`, `parser`, `ast`
|
||||
- モデル層: `core::model`（BoxDeclaration等の純粋データ）
|
||||
- ランタイム層: `runtime`（UnifiedBoxRegistry, PluginLoader, NyashRuntime）
|
||||
- 実行戦略層: `interpreter`（AST実行）/ `mir`+`backend::vm`（MIR実行）/ 将来 `wasm`/`llvm`
|
||||
- 付帯基盤: `box_factory`, `instance_v2`, `scope_tracker`, `boxes/*`, `stdlib`
|
||||
|
||||
## コア概念
|
||||
|
||||
- Everything is Box: すべての値はBox（ビルトイン、ユーザー定義、プラグイン）
|
||||
- 統一コンストラクタ: `birth(args)`（packはビルトイン継承内部用に透過化）
|
||||
- 明示デリゲーション: `box Child from Parent` と `from Parent.method()`
|
||||
- 厳密変数宣言/スコープ安全: `local`, `outbox`、スコープ退出時の`fini`一元化
|
||||
|
||||
## モデル層（core::model）
|
||||
|
||||
- `BoxDeclaration` を `interpreter` から分離し `core::model` に移動
|
||||
- name, fields, methods, constructors(birth/N), extends, implements, type_parameters
|
||||
- 実行戦略非依存の純粋データ
|
||||
|
||||
## ランタイム層（runtime）
|
||||
|
||||
- `NyashRuntime`
|
||||
- `box_registry: UnifiedBoxRegistry`（ビルトイン/ユーザー定義/プラグインを順序付き検索）
|
||||
- `box_declarations: RwLock<HashMap<String, BoxDeclaration>>`
|
||||
- BuilderでDI（`with_factory`）可能。Interpreter/VMから共有・注入できる
|
||||
- `UnifiedBoxRegistry`
|
||||
- `Arc<dyn BoxFactory>` の列で優先解決（builtin > user > plugin）
|
||||
- `create_box(name, args)` の統一エントリ
|
||||
- `BoxFactory`
|
||||
- builtin: 全ビルトインBoxの生成
|
||||
- user_defined: `BoxDeclaration`に基づき`InstanceBox`生成（birthは実行戦略側で）
|
||||
- plugin: BID-FFI準拠のプラグインBox（将来のExternCall/MIR接続）
|
||||
|
||||
## 実行戦略（Interpreter / VM）
|
||||
|
||||
- Interpreter（AST実行）
|
||||
- `SharedState` は段階的に分解し、宣言等を `NyashRuntime` に寄せ替え
|
||||
- 生成は統一レジストリへ委譲、コンストラクタ実行は`birth/N`のASTを実行
|
||||
|
||||
- VM (MIR実行)
|
||||
- `VM::with_runtime(runtime)` でDI、`NewBox`は`runtime.box_registry.create_box`へ
|
||||
- `ScopeTracker`でスコープ退出時に`fini`（InstanceBox/PluginBox）
|
||||
- birth/メソッドのMIR関数化（Phase 2/3）：
|
||||
- Builderが `new` を `NewBox` + `BoxCall("birth")` に展開
|
||||
- Box宣言の `birth/N` と通常メソッド(`method/N`)を `"{Box}.{name}/{N}"` のMIR関数へ関数化
|
||||
- VMの`BoxCall`は `InstanceBox` なら該当MIR関数へディスパッチ（me + 引数）
|
||||
|
||||
## MIR（中間表現）
|
||||
|
||||
- 目的: バックエンド共通の最適化/実行基盤（VM/LLVM/WASM/JIT）
|
||||
- Builder
|
||||
- AST→MIR lowering。`ASTNode::New`→`NewBox`(+ `BoxCall("birth")`)
|
||||
- `ASTNode::BoxDeclaration` の `constructors` / `methods` をMIR関数化
|
||||
- if/loop/try-catch/phi等の基本構造を提供
|
||||
- VM
|
||||
- Stackベースの簡易実装→順次強化中
|
||||
- `call_function_by_name` による関数呼び出しフレームの最小実装
|
||||
|
||||
## インスタンス表現（InstanceBox）
|
||||
|
||||
- 統一フィールド`fields_ng: HashMap<String, NyashValue>`
|
||||
- メソッドASTを保持（ユーザー定義時）
|
||||
- `fini()`による簡易解放（将来、リソースBoxは明示やRAII連携）
|
||||
|
||||
## ライフサイクル統一（fini）
|
||||
|
||||
- Interpreter: スコープ復帰時に`InstanceBox.fini()`等を呼ぶ
|
||||
- VM: `ScopeTracker`で関数入退出時に登録Boxを`fini`
|
||||
|
||||
## プラグイン（BID-FFI）
|
||||
|
||||
- v2ローダ（`runtime::plugin_loader_v2`）とテスター完備
|
||||
- 目標: MIRの`ExternCall`→ローダに接続し、VM/LLVM/WASMで共通パス
|
||||
|
||||
## Runner/ビルド
|
||||
|
||||
- VMモード:
|
||||
1) ASTパース
|
||||
2) ランタイムにBox宣言収集 + UserDefinedBoxFactory登録
|
||||
3) MIRコンパイル
|
||||
4) VMを`with_runtime`で起動し実行
|
||||
|
||||
## 進行中フェーズと方針
|
||||
|
||||
- Phase 9.78b: Interpreter/VMのモデル・ランタイム共有（完了）
|
||||
- Phase 2/3（実質）: birth/メソッドのMIR関数化とVMディスパッチ（実装済・基本動作）
|
||||
- 次:
|
||||
- BoxCall→Callへの段階的置換（型決定済みのとき）
|
||||
- ExternCallの実装（VM→プラグイン）
|
||||
- WASM/LLVMバックエンドへMIR関数の共有
|
||||
|
||||
## 参考ファイル
|
||||
|
||||
- `src/core/model.rs`（BoxDeclaration）
|
||||
- `src/runtime/nyash_runtime.rs`（NyashRuntime）
|
||||
- `src/box_factory/*`（builtin/user_defined/plugin）
|
||||
- `src/mir/*`（builder/instruction/function/etc.）
|
||||
- `src/backend/vm.rs`（VM実行）
|
||||
- `src/interpreter/*`（AST実行）
|
||||
|
||||
@ -1,118 +0,0 @@
|
||||
# Dynamic Plugin Flow (VM × Registry × PluginLoader v2)
|
||||
|
||||
最終更新: 2025-08-23
|
||||
|
||||
目的
|
||||
- Nyash 実行時に、MIR→VM→Registry→Plugin の呼び出しがどう流れるかを図解・手順で把握する。
|
||||
- TLVエンコード、ResultBoxの扱い、Handleのライフサイクル、nyash.tomlとの連携を1枚で理解する。
|
||||
|
||||
## ハイレベル流れ（シーケンス）
|
||||
|
||||
```
|
||||
Nyash Source ──▶ MIR (Builder)
|
||||
│ (BoxCall/NewBox/…)
|
||||
▼
|
||||
VM Executor
|
||||
│ (BoxCall dispatch)
|
||||
├─ InstanceBox → Lowered MIR 関数呼び出し
|
||||
├─ BuiltinBox → VM内ディスパッチ
|
||||
└─ PluginBoxV2 → PluginLoader v2
|
||||
│ (nyash.toml を参照)
|
||||
▼
|
||||
Invoke (TLV)
|
||||
│
|
||||
▼
|
||||
Plugin (lib*.so)
|
||||
│ (戻り値をTLVで返却)
|
||||
▼
|
||||
Loader でデコード
|
||||
│ (returns_result/Handle/型)
|
||||
▼
|
||||
NyashBox (ResultBox/PluginBoxV2/基本型)
|
||||
│
|
||||
▼
|
||||
VM に復帰
|
||||
```
|
||||
|
||||
## 主要構成要素
|
||||
- MIR: `MirInstruction::{BoxCall, NewBox, …}` で外部呼び出し箇所を明示。
|
||||
- VM: `src/backend/vm.rs`
|
||||
- InstanceBoxは `{Class}.{method}/{argc}` のLowered関数へ呼び出し
|
||||
- BuiltinはVM内の簡易ディスパッチ
|
||||
- PluginBoxV2は Loader v2 へ委譲
|
||||
- Registry/Runtime: `NyashRuntime` + `box_registry` + `plugin_loader_v2`
|
||||
- `nyash.toml` の `libraries.*` を読み込み、Box名→ライブラリ名、type_id、method_id等を集約
|
||||
|
||||
## NewBox（生成）
|
||||
1) MIRの `NewBox { box_type, args }`
|
||||
2) VM: `runtime.box_registry` に `box_type` を問い合わせ
|
||||
3) PluginBoxの場合、Loader v2が `birth(method_id=0)` を TLV で呼び出し
|
||||
4) Pluginは `type_id` と新規 `instance_id` を返却 → Loader は `PluginBoxV2` を構築
|
||||
5) VMは `ScopeTracker` に登録（スコープ終了で `fini` を呼ぶ）
|
||||
|
||||
## BoxCall（メソッド呼び出し）
|
||||
- InstanceBox: Lowered関数 `{Class}.{method}/{argc}` を MIR/VM内で実行
|
||||
- Builtin: VM内の `call_box_method` で対応（StringBox.length 等）
|
||||
- PluginBoxV2: Loader v2 の `invoke_instance_method` で TLV を組み立てて呼び出し
|
||||
|
||||
## TLV（Type-Length-Value）
|
||||
- ヘッダ: `u16 ver=1`, `u16 argc`
|
||||
- 各引数: `u8 tag`, `u8 reserved`, `u16 size`, `payload`
|
||||
- 主な tag:
|
||||
- 2 = i32 (size=4)
|
||||
- 6 = string, 7 = bytes
|
||||
- 8 = Handle(BoxRef) → payload = `u32 type_id || u32 instance_id`
|
||||
- 9 = void (size=0)
|
||||
|
||||
## 戻り値のマッピング（重要）
|
||||
- `returns_result=false`
|
||||
- tag=8 → PluginBoxV2（Handle）
|
||||
- tag=2 → IntegerBox、tag=6/7 → StringBox、tag=9 → void
|
||||
- `returns_result=true`（ResultBoxで包む）
|
||||
- tag=8/2 → `Result.Ok(value)`
|
||||
- tag=6/7 → `Result.Err(ErrorBox(message))`（Netプラグインなどがエラー文字列を返却）
|
||||
- tag=9 → `Result.Ok(void)`
|
||||
|
||||
補足
|
||||
- VM内で ResultBox の `isOk/getValue/getError` をディスパッチ済み
|
||||
- `toString()` フォールバックにより任意の Box を安全に文字列化可能
|
||||
|
||||
## Handle（BoxRef）のライフサイクル
|
||||
- Loaderは `(type_id, instance_id)` を `PluginBoxV2` としてラップ
|
||||
- `share_box()` は同一インスタンス共有、`clone_box()` はプラグインの birth を呼ぶ（設計意図による）
|
||||
- `fini` は `ScopeTracker` または Drop で保証（プラグインの `fini_method_id` を参照）
|
||||
|
||||
## 具体例（HttpClientBox.get）
|
||||
1) Nyash: `r = cli.get(url)`
|
||||
2) MIR: `BoxCall`（returns_result=true）
|
||||
3) VM→Loader: TLV（url = tag=6）
|
||||
4) Loader→Plugin: `invoke(type_id=HttpClient, method_id=get)`
|
||||
5) Plugin:
|
||||
- 接続成功: `Handle(HttpResponse)` を返す → Loaderは `Result.Ok(PluginBoxV2)`
|
||||
- 接続失敗: `String("connect failed …")` を返す → Loaderは `Result.Err(ErrorBox)`
|
||||
6) Nyash: `if r.isOk() { resp = r.getValue() … } else { print(r.getError().toString()) }`
|
||||
|
||||
## nyash.toml 連携
|
||||
- 例: `libraries."libnyash_net_plugin.so".HttpClientBox.methods.get = { method_id = 1, args=["url"], returns_result = true }`
|
||||
- Loaderは `method_id` と `returns_result` を参照し、TLVと戻り値のラップ方針を決定
|
||||
- 型宣言（args/kind）により、引数のTLVタグ検証を実施（不一致は InvalidArgs）
|
||||
|
||||
## デバッグTips
|
||||
- `NYASH_DEBUG_PLUGIN=1`: VM→Plugin の TLV ヘッダと先頭64バイトをプレビュー
|
||||
- `NYASH_NET_LOG=1 NYASH_NET_LOG_FILE=net_plugin.log`: Netプラグイン内部ログ
|
||||
- `--dump-mir --mir-verbose`: if/phi/return などのMIRを確認
|
||||
- `--vm-stats --vm-stats-json`: 命令使用のJSONを取得（hot pathの裏取りに）
|
||||
|
||||
## 将来の整合・改善
|
||||
- nyash.toml に ok側の戻り型（例: `ok_returns = "HttpResponseBox"`）を追加 → Loader判定の厳密化
|
||||
- Verifier強化: use-before-def across merge の検出（phi誤用を早期に発見）
|
||||
- BoxCall fast-path の最適化（hot path最優先）
|
||||
|
||||
関連
|
||||
- `docs/reference/plugin-system/net-plugin.md`
|
||||
- `docs/reference/architecture/mir-to-vm-mapping.md`
|
||||
- `docs/reference/architecture/mir-26-instruction-diet.md`
|
||||
|
||||
See also
|
||||
- `docs/examples/http_result_patterns.md` - HTTPのResult挙動（unreachable/404/500）のE2E例
|
||||
- `docs/VM_README.md` - VM統計とプラグイン周りの既知制約
|
||||
@ -1,527 +0,0 @@
|
||||
# Nyash実行バックエンド完全ガイド（推奨4経路 + 任意 JIT）
|
||||
|
||||
Nyashプログラミング言語は、**Everything is Box**哲学を維持しながら、推奨4経路（Interpreter / VM / Cranelift AOT / LLVM AOT）を中心に運用します。任意で Cranelift JIT ランタイムを有効化できます。
|
||||
|
||||
## 🚀 実行方式一覧
|
||||
|
||||
| 実行方式 | 用途 | 特徴 | パフォーマンス |
|
||||
|---------|------|------|---------------|
|
||||
| **インタープリター** | 開発・デバッグ | 直接AST実行、詳細ログ | 低速・高機能 |
|
||||
| **VM** | 本番・高速実行 | MIR→VM実行 | 中速・最適化 |
|
||||
| **WASM** | Web・サンドボックス | MIR→WASM変換 | 高速・移植性 |
|
||||
| **Cranelift AOT** | ネイティブEXE | CLIF→オブジェクト→リンク | 高速・軽量 |
|
||||
| **LLVM AOT** | ネイティブEXE | LLVM18/inkwell | 高速・高最適化 |
|
||||
|
||||
## 📋 CLIオプション
|
||||
|
||||
### 基本実行（インタープリター）
|
||||
```bash
|
||||
# デフォルト：インタープリター実行
|
||||
nyash program.nyash
|
||||
|
||||
# デバッグ燃料制限付き
|
||||
nyash --debug-fuel 50000 program.nyash
|
||||
|
||||
# 無制限デバッグ燃料
|
||||
nyash --debug-fuel unlimited program.nyash
|
||||
```
|
||||
|
||||
### VM実行
|
||||
```bash
|
||||
# VM実行（高速）
|
||||
nyash --backend vm program.nyash
|
||||
```
|
||||
|
||||
### MIR操作
|
||||
```bash
|
||||
# MIR表示（中間表現確認）
|
||||
nyash --dump-mir program.nyash
|
||||
|
||||
# MIR検証
|
||||
nyash --verify program.nyash
|
||||
|
||||
# 詳細MIR情報
|
||||
nyash --mir-verbose --dump-mir program.nyash
|
||||
```
|
||||
|
||||
### WASM生成・実行
|
||||
```bash
|
||||
# WASMコンパイル（WAT出力）
|
||||
nyash --compile-wasm program.nyash
|
||||
|
||||
# ファイル出力
|
||||
nyash --compile-wasm program.nyash -o output.wat
|
||||
|
||||
# ブラウザで実行可能なWASMを生成
|
||||
nyash --compile-wasm program.nyash -o public/app.wat
|
||||
```
|
||||
|
||||
### Cranelift AOT（ネイティブEXE）
|
||||
Cranelift ベースの AOT パイプライン。Egui Hello の EXE 化は `docs/guides/cranelift_aot_egui_hello.md` を参照。
|
||||
|
||||
### LLVM AOT（ネイティブEXE）
|
||||
```bash
|
||||
# ビルド時に wasm-backend feature が必要
|
||||
cargo build --release --features wasm-backend
|
||||
|
||||
# AOTコンパイル（.cwasm生成）
|
||||
nyash --compile-native program.nyash -o program
|
||||
# または
|
||||
nyash --aot program.nyash -o program
|
||||
|
||||
# 注意: 現在は完全なスタンドアロン実行ファイルではなく、
|
||||
# wasmtime用のプリコンパイル済みWASM（.cwasm）が生成されます
|
||||
```
|
||||
|
||||
### ⚡ ベンチマーク（パフォーマンス測定）
|
||||
```bash
|
||||
# 全バックエンド性能比較（デフォルト5回実行）
|
||||
nyash --benchmark
|
||||
|
||||
# 実行回数指定（統計精度向上）
|
||||
nyash --benchmark --iterations 100
|
||||
|
||||
# 結果をファイル保存
|
||||
nyash --benchmark --iterations 50 > benchmark_results.txt
|
||||
```
|
||||
|
||||
## 🎯 インタープリター（デフォルト）
|
||||
|
||||
### 特徴
|
||||
- **用途**: 開発・デバッグ・学習
|
||||
- **実行**: AST直接実行
|
||||
- **速度**: 最も低速
|
||||
- **機能**: 最も詳細なデバッグ情報
|
||||
|
||||
### 利点
|
||||
- 詳細な実行ログ
|
||||
- エラー位置の正確な特定
|
||||
- リアルタイム変数監視
|
||||
- メモリ使用量詳細表示
|
||||
|
||||
### デバッグ燃料システム
|
||||
```bash
|
||||
# パーサー無限ループ対策
|
||||
nyash --debug-fuel 10000 problem.nyash
|
||||
|
||||
# エラー例:
|
||||
🚨 PARSER INFINITE LOOP DETECTED at method call argument parsing
|
||||
🔍 Current token: IDENTIFIER("from") at line 17
|
||||
```
|
||||
|
||||
## 🏎️ VM実行（高速）
|
||||
|
||||
### 特徴
|
||||
- **用途**: 本番実行・性能重視
|
||||
- **実行**: AST→MIR→VM実行
|
||||
- **速度**: 中〜高速
|
||||
- **機能**: 最適化済み
|
||||
|
||||
### 実行パイプライン
|
||||
```
|
||||
Nyashソース → AST → MIR → VM → 結果
|
||||
```
|
||||
|
||||
### MIR（中間表現）
|
||||
```bash
|
||||
# MIR確認
|
||||
nyash --dump-mir simple.nyash
|
||||
|
||||
# 出力例:
|
||||
; MIR Module: main
|
||||
define void @main() {
|
||||
bb0:
|
||||
0: safepoint
|
||||
1: %0 = const 42
|
||||
2: %1 = const 8
|
||||
3: %2 = %0 Add %1
|
||||
4: print %2
|
||||
5: ret %2
|
||||
}
|
||||
```
|
||||
|
||||
### VMの特徴
|
||||
- **SSA形式**: 静的単一代入
|
||||
- **基本ブロック**: 制御フロー最適化
|
||||
- **効果追跡**: 副作用の管理
|
||||
- **型安全**: 実行時型チェック
|
||||
- **対応状況**: 命令ごとの実装は「MIR → VM Mapping」を参照（欠落・暫定箇所の把握に）
|
||||
- docs/reference/architecture/mir-to-vm-mapping.md
|
||||
|
||||
### 🧮 VM実行統計（命令カウント・時間計測）
|
||||
VMバックエンドは命令ごとの実行回数と総実行時間(ms)を出力できます。
|
||||
|
||||
有効化方法（CLI推奨）:
|
||||
```bash
|
||||
# 人間向け表示
|
||||
nyash --backend vm --vm-stats program.nyash
|
||||
|
||||
# JSON出力（機械可読）
|
||||
nyash --backend vm --vm-stats --vm-stats-json program.nyash
|
||||
```
|
||||
|
||||
環境変数でも制御可能:
|
||||
```bash
|
||||
NYASH_VM_STATS=1 ./target/release/nyash --backend vm program.nyash
|
||||
NYASH_VM_STATS=1 NYASH_VM_STATS_JSON=1 ./target/release/nyash --backend vm program.nyash
|
||||
# もしくは NYASH_VM_STATS_FORMAT=json でも可
|
||||
```
|
||||
|
||||
JSON出力例:
|
||||
```json
|
||||
{
|
||||
"total": 1234,
|
||||
"elapsed_ms": 5.123,
|
||||
"counts": { "Const": 200, "BinOp": 300, "Return": 100 },
|
||||
"top20": [ { "op": "BinOp", "count": 300 } ],
|
||||
"timestamp_ms": 1724371200000
|
||||
}
|
||||
```
|
||||
|
||||
ベンチマークと併用して、ホット命令の抽出・命令セット最適化に活用できます。
|
||||
|
||||
### ⏱️ 協調スケジューラ（Phase 10.6b）
|
||||
- VMはMIRの`safepoint`命令到達時にランタイムのスケジューラ`poll()`を呼びます。
|
||||
- シングルスレ実装（既定）では、`spawn`/`spawn_after`で投入されたタスクを safepoint ごとに最大N件実行します。
|
||||
- 制御: `NYASH_SCHED_POLL_BUDGET`（既定: 1）でNを指定。
|
||||
|
||||
デモ実行:
|
||||
```bash
|
||||
cargo build --release -j32
|
||||
NYASH_SCHED_DEMO=1 NYASH_SCHED_POLL_BUDGET=2 \
|
||||
./target/release/nyash --backend vm examples/scheduler_demo.nyash
|
||||
```
|
||||
|
||||
### 🧹 GCトレーシング（Phase 10.4）
|
||||
- カウンタ有効化: `NYASH_GC_COUNTING=1`（CountingGcを注入）
|
||||
- 出力レベル: `NYASH_GC_TRACE=1/2/3`
|
||||
- 1: safepoint/barrierログ＋カウンタ
|
||||
- 2: + ルート内訳
|
||||
- 3: + depth=2 リーチャビリティ概要
|
||||
- 厳格検証: `NYASH_GC_BARRIER_STRICT=1`（Write-Barrier未増分ならpanic）
|
||||
|
||||
```bash
|
||||
NYASH_GC_COUNTING=1 NYASH_GC_TRACE=2 \
|
||||
./target/release/nyash --backend vm examples/scheduler_demo.nyash
|
||||
```
|
||||
|
||||
#### Boxからの切替（GcConfigBox）
|
||||
環境変数ではなくNyashスクリプトから切り替える場合は `GcConfigBox` を使います。`apply()` で環境に反映され、その後の実行に適用されます。
|
||||
|
||||
```nyash
|
||||
// 最小例: CountingGc + trace をオン
|
||||
static box Main {
|
||||
main() {
|
||||
local G
|
||||
G = new GcConfigBox()
|
||||
G = G.setFlag("counting", true)
|
||||
G = G.setFlag("trace", true) // 1/2/3 は環境。Box では on/off を切替
|
||||
G.apply() // ← ここで反映
|
||||
return "ok"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
代表デモ（書き込みバリア/カウンタの可視化）:
|
||||
```bash
|
||||
./target/release/nyash --backend vm examples/gc_counting_demo.nyash
|
||||
```
|
||||
|
||||
## 🌐 WASM実行（Web対応）
|
||||
|
||||
### 特徴
|
||||
- **用途**: Webブラウザ・サンドボックス実行
|
||||
- **実行**: AST→MIR→WASM→ブラウザ
|
||||
- **速度**: 最高速（ネイティブ並み）
|
||||
- **移植性**: 全プラットフォーム対応
|
||||
|
||||
### 実行パイプライン
|
||||
```
|
||||
Nyashソース → AST → MIR → WAT → WASM → ブラウザ
|
||||
```
|
||||
|
||||
### 生成例
|
||||
```nyash
|
||||
// Nyashコード
|
||||
static box Main {
|
||||
main() {
|
||||
return 42
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```wat
|
||||
; 生成されるWAT
|
||||
(module
|
||||
(import "env" "print" (func $print (param i32) ))
|
||||
(memory (export "memory") 1)
|
||||
(global $heap_ptr (mut i32) (i32.const 2048))
|
||||
(func $main (local $0 i32)
|
||||
nop ; safepoint
|
||||
i32.const 42 ; const 42
|
||||
local.set $0 ; store to local
|
||||
local.get $0 ; load from local
|
||||
return ; return 42
|
||||
)
|
||||
(export "main" (func $main))
|
||||
)
|
||||
```
|
||||
|
||||
### Web実行
|
||||
```html
|
||||
<!-- HTMLで読み込み -->
|
||||
<script>
|
||||
async function loadNyashWasm() {
|
||||
const response = await fetch('output.wat');
|
||||
const watText = await response.text();
|
||||
|
||||
const wabt = await WabtModule();
|
||||
const module = wabt.parseWat('output.wat', watText);
|
||||
const binary = module.toBinary({});
|
||||
|
||||
const importObject = {
|
||||
env: { print: console.log }
|
||||
};
|
||||
|
||||
const wasmModule = await WebAssembly.instantiate(binary.buffer, importObject);
|
||||
const result = wasmModule.instance.exports.main(); // 42
|
||||
}
|
||||
</script>
|
||||
```
|
||||
|
||||
## 🚀 AOT/ネイティブコンパイル（実験的）
|
||||
|
||||
### 特徴
|
||||
- **用途**: 高速起動・配布用実行ファイル
|
||||
- **実行**: AST→MIR→WASM→プリコンパイル済みネイティブ
|
||||
- **速度**: 最高速（JIT起動オーバーヘッドなし）
|
||||
- **制約**: wasmtimeランタイムが必要
|
||||
|
||||
### コンパイルパイプライン
|
||||
```
|
||||
Nyashソース → AST → MIR → WASM → .cwasm（プリコンパイル済み）
|
||||
```
|
||||
|
||||
### ビルド方法
|
||||
```bash
|
||||
# 1. wasm-backend feature付きでNyashをビルド
|
||||
cargo build --release --features wasm-backend
|
||||
|
||||
# 2. AOTコンパイル実行
|
||||
./target/release/nyash --compile-native hello.nyash -o hello
|
||||
# または短縮形
|
||||
./target/release/nyash --aot hello.nyash -o hello
|
||||
|
||||
# 3. 生成されたファイル
|
||||
# hello.cwasm が生成される（wasmtimeプリコンパイル形式）
|
||||
```
|
||||
|
||||
### 現在の実装状況
|
||||
- ✅ MIR→WASM変換
|
||||
- ✅ WASM→.cwasm（wasmtimeプリコンパイル）
|
||||
- ❌ 完全なスタンドアロン実行ファイル生成（TODO）
|
||||
- ❌ ランタイム埋め込み（将来実装予定）
|
||||
|
||||
### 使用例
|
||||
```bash
|
||||
# コンパイル
|
||||
./target/release/nyash --aot examples/hello_world.nyash -o hello_aot
|
||||
|
||||
# 実行（将来的な目標）
|
||||
# ./hello_aot # 現在は未実装
|
||||
|
||||
# 現在は wasmtime で実行
|
||||
# wasmtime --precompiled hello_aot.cwasm
|
||||
```
|
||||
|
||||
### 技術的詳細
|
||||
AOTバックエンドは内部的に以下の処理を行います：
|
||||
1. **MirCompiler**: NyashコードをMIRに変換
|
||||
2. **WasmBackend**: MIRをWASMバイトコードに変換
|
||||
3. **wasmtime::Engine::precompile**: WASMをネイティブコードにプリコンパイル
|
||||
4. **出力**: .cwasm形式で保存（wasmtime独自形式）
|
||||
|
||||
## 📊 パフォーマンス比較
|
||||
|
||||
### 🚀 実際のベンチマーク結果（2025-08-14測定・修正）
|
||||
|
||||
#### ⚠️ **重要**: 性能測定の正確な説明
|
||||
|
||||
**真の実行性能比較**（wasmtime統合・100回実行平均）:
|
||||
| Backend | 実行時間 | 速度比 | 測定内容 | 最適用途 |
|
||||
|---------|---------|---------|----------|----------|
|
||||
| **🌐 WASM** | **8.12ms** | **13.5x faster** | 真の実行性能 | Web配布・高速実行 |
|
||||
| **📝 Interpreter** | **110.10ms** | **1x (baseline)** | AST直接実行 | 開発・デバッグ |
|
||||
| **🏎️ VM** | **119.80ms** | **0.9x slower** | MIR→VM実行 | 🚨要改善 |
|
||||
|
||||
**コンパイル性能参考**（従来のベンチマーク）:
|
||||
| Backend | コンパイル時間 | 速度比 | 測定内容 |
|
||||
|---------|-------------|---------|----------|
|
||||
| **🌐 WASM** | **0.17ms** | **280x faster** | MIR→WASM変換 |
|
||||
| **🏎️ VM** | **16.97ms** | **2.9x faster** | MIR→VM変換 |
|
||||
| **📝 Interpreter** | **48.59ms** | **1x (baseline)** | AST→実行 |
|
||||
|
||||
### 📈 ベンチマーク詳細
|
||||
|
||||
#### 🚨 **VM性能問題の発見**
|
||||
**異常事象**: VMがインタープリターより遅い結果が判明
|
||||
- **推定原因**: MIR変換オーバーヘッド、VM実行エンジン未最適化
|
||||
- **対策**: Phase 9でのJIT化、VM最適化が急務
|
||||
|
||||
#### 実行性能詳細（wasmtime統合測定）
|
||||
```
|
||||
🌐 WASM (wasmtime): 8.12 ms (13.5x faster - 真の実行性能)
|
||||
📝 Interpreter: 110.10 ms (1x baseline)
|
||||
🏎️ VM: 119.80 ms (0.9x slower - 要改善)
|
||||
```
|
||||
|
||||
#### コンパイル性能詳細（従来測定）
|
||||
```
|
||||
🌐 WASM変換: 0.15-0.21 ms (280x faster - コンパイル速度)
|
||||
🏎️ VM変換: 4.44-25.08 ms (3-120x faster - コンパイル速度)
|
||||
📝 実行のみ: 14.85-84.88 ms (1x baseline)
|
||||
```
|
||||
|
||||
### 💡 ベンチマーク実行方法
|
||||
```bash
|
||||
# 現在のマシンで性能測定
|
||||
nyash --benchmark --iterations 100
|
||||
|
||||
# 軽量テスト（開発中）
|
||||
nyash --benchmark --iterations 10
|
||||
```
|
||||
|
||||
### メモリ使用量
|
||||
```
|
||||
インタープリター ████████████████████ 高い（AST+実行情報）
|
||||
VM ████████████ 中程度（MIR+実行時）
|
||||
WASM ████ 低い（最適化済み）
|
||||
```
|
||||
|
||||
## 🎁 Everything is Box の維持
|
||||
|
||||
全ての実行方式で、Nyashの核心哲学「Everything is Box」が維持されます：
|
||||
|
||||
### インタープリター
|
||||
```rust
|
||||
// RustのArc<Mutex<dyn NyashBox>>として実装
|
||||
StringBox::new("Hello") → Arc<Mutex<StringBox>>
|
||||
```
|
||||
|
||||
### VM
|
||||
```
|
||||
// MIRのValueIdとして管理
|
||||
%0 = const "Hello" ; StringBox相当
|
||||
%1 = %0.length() ; メソッド呼び出し
|
||||
```
|
||||
|
||||
### WASM
|
||||
```wat
|
||||
;; WASMの線形メモリでBox表現
|
||||
;; [type_id:4][field_count:4][field0:4][field1:4]...
|
||||
i32.const 1001 ;; StringBox type ID
|
||||
i32.store offset=0 ;; メモリにBox情報格納
|
||||
```
|
||||
|
||||
## 🚀 用途別推奨
|
||||
|
||||
### 開発・デバッグ時
|
||||
```bash
|
||||
# 詳細ログでエラー特定
|
||||
nyash --debug-fuel unlimited debug_me.nyash
|
||||
```
|
||||
|
||||
### 本番実行時
|
||||
```bash
|
||||
# 高速・安定実行
|
||||
nyash --backend vm production.nyash
|
||||
```
|
||||
|
||||
### Web配布時
|
||||
```bash
|
||||
# ブラウザ対応WASM生成
|
||||
nyash --compile-wasm app.nyash -o public/app.wat
|
||||
```
|
||||
|
||||
## 🔧 トラブルシューティング
|
||||
|
||||
### パーサーエラー
|
||||
```bash
|
||||
# 無限ループ検出時
|
||||
🚨 PARSER INFINITE LOOP DETECTED
|
||||
→ nyash --debug-fuel 1000 problem.nyash
|
||||
```
|
||||
|
||||
### MIRエラー
|
||||
```bash
|
||||
# 未対応AST構文
|
||||
❌ MIR compilation error: Unsupported AST node type: BoxDeclaration
|
||||
→ 現在はstatic box Mainのみ対応
|
||||
```
|
||||
|
||||
### WASMエラー
|
||||
```bash
|
||||
# 未対応MIR命令
|
||||
❌ WASM compilation error: Instruction not yet supported: ComplexInstruction
|
||||
→ Phase 8.3で順次対応予定
|
||||
```
|
||||
|
||||
## 📈 今後の拡張予定
|
||||
|
||||
### Phase 8.3: Box操作のWASM対応
|
||||
- RefNew/RefGet/RefSet
|
||||
- オブジェクト指向プログラミング
|
||||
- メモリ管理の高度化
|
||||
|
||||
### Phase 8.4: 非同期処理のWASM対応
|
||||
- nowait/await構文
|
||||
- Future操作
|
||||
- 並列処理
|
||||
|
||||
### Phase 8.5: 最適化
|
||||
- デッドコード除去
|
||||
- インライン展開
|
||||
- ループ最適化
|
||||
|
||||
---
|
||||
|
||||
**💡 Tip**: 開発中は**インタープリター**、テスト時は**VM**、配布時は**WASM**という使い分けが効果的です！
|
||||
|
||||
最終更新: 2025-08-14
|
||||
作成者: Nyash Development Team
|
||||
### 🔥 JIT実行（Phase 10_c 最小経路）
|
||||
- 有効化: `NYASH_JIT_EXEC=1` とし、`NYASH_JIT_THRESHOLD=1` でホット判定しきい値を下げる
|
||||
- 追加情報: `NYASH_JIT_STATS=1` でJITコンパイル/実行時間、サイト集計を出力
|
||||
- ダンプ: `NYASH_JIT_DUMP=1` でLowerカバレッジ/emit統計を表示
|
||||
- HostCall（配列/Map最小）: `NYASH_JIT_HOSTCALL=1`
|
||||
|
||||
例:
|
||||
```bash
|
||||
NYASH_JIT_EXEC=1 NYASH_JIT_THRESHOLD=1 NYASH_JIT_HOSTCALL=1 NYASH_JIT_STATS=1 \
|
||||
./target/release/nyash --backend vm examples/scheduler_demo.nyash
|
||||
```
|
||||
|
||||
現状のカバレッジ（Core-1）
|
||||
- Const(i64/bool), BinOp(Add/Sub/Mul/Div/Mod), Compare(Eq/Ne/Lt/Le/Gt/Ge), Return
|
||||
- Paramのi64経路（複数引数対応）
|
||||
- Array/Mapの最小HostCall（len/get/set/push/size）
|
||||
- Branch/JumpはPhase 10.7でCranelift配線を導入（feature: `cranelift-jit`）。
|
||||
- 分岐条件はb1化（i64の場合は !=0 で正規化）
|
||||
- 直線＋if/elseでのreturnをJITで実行（副作用は未対応のためVMへ）
|
||||
- PHIは将来の`NYASH_JIT_PHI_MIN=1`で最小導入予定
|
||||
|
||||
#### 予約シンボル（Runtime/GC 橋渡し）
|
||||
- `nyash.rt.checkpoint`（セーフポイント）
|
||||
- JIT: no-op スタブを登録済み（将来のスケジューラ/GC連携用）
|
||||
- AOT: `nyrt` が同名シンボルをエクスポート（`#[export_name]`）。リンク済み
|
||||
- トレース: `NYASH_RUNTIME_CHECKPOINT_TRACE=1` でstderrに到達ログ
|
||||
- `nyash.gc.barrier_write`（書き込みバリア）
|
||||
- JIT: no-op スタブを登録済み（将来のインクリメンタルGC向けフック）
|
||||
- AOT: `nyrt` が同名シンボルをエクスポート（`#[export_name]`）
|
||||
- トレース: `NYASH_GC_BARRIER_TRACE=1` でstderrに到達ログ
|
||||
|
||||
メモ: 現時点では両シンボルとも副作用なし（no-op）。MIR側では `Safepoint` → `ExternCall(env.runtime.checkpoint)` へ段階移行中です。
|
||||
## ⚙️ 任意: Cranelift JIT ランタイム
|
||||
- デフォルト封印。必要時のみ `--features "cranelift-jit,jit-runtime"` で有効化
|
||||
- ランナーの `--backend cranelift` が利用可能に
|
||||
- 目的: デバッグ用途・将来の最適化検証。日常運用ではAOTを優先
|
||||
@ -1,98 +0,0 @@
|
||||
# MIR 26-Instruction Diet (Agreed Final Set)
|
||||
|
||||
Goal
|
||||
- Converge on a lean, proven instruction set guided by vm-stats and E2E.
|
||||
- Preserve hot paths, demote meta, fold type ops, reserve room for growth.
|
||||
|
||||
Agreed Final Set (26)
|
||||
1) Const
|
||||
2) Copy
|
||||
3) Load
|
||||
4) Store
|
||||
5) BinOp
|
||||
6) UnaryOp
|
||||
7) Compare
|
||||
8) Jump
|
||||
9) Branch
|
||||
10) Phi
|
||||
11) Return
|
||||
12) Call
|
||||
13) BoxCall
|
||||
14) NewBox
|
||||
15) ArrayGet
|
||||
16) ArraySet
|
||||
17) RefNew
|
||||
18) RefGet
|
||||
19) RefSet
|
||||
20) Await
|
||||
21) Print
|
||||
22) ExternCall (keep minimal; prefer BoxCall)
|
||||
23) TypeOp (unify TypeCheck/Cast)
|
||||
24) WeakRef (unify WeakNew/WeakLoad)
|
||||
25) Barrier (unify BarrierRead/BarrierWrite)
|
||||
26) Reserve (future async/error instr)
|
||||
|
||||
Hot/Core (keep)
|
||||
- Data: Const, Copy, Load, Store
|
||||
- ALU: BinOp, UnaryOp, Compare
|
||||
- Control: Jump, Branch, Phi, Return
|
||||
- Calls: Call, BoxCall
|
||||
- Objects: NewBox
|
||||
- Arrays: ArrayGet, ArraySet
|
||||
|
||||
Likely Keep (usage-dependent)
|
||||
- Refs: RefNew, RefGet, RefSet (seen in language features; keep unless stats prove cold)
|
||||
- Async: Await (FutureNew/Set can be Box/APIs)
|
||||
|
||||
Meta (demote to build-mode)
|
||||
- Debug, Nop, Safepoint
|
||||
|
||||
Type Ops (fold)
|
||||
- TypeCheck, Cast → fold/verify-time or unify as a single TypeOp (optional).
|
||||
|
||||
External (unify)
|
||||
- ExternCall → prefer BoxCall; keep ExternCall only where required.
|
||||
|
||||
Extended/Reserve
|
||||
- Weak*: WeakNew, WeakLoad
|
||||
- Barriers: BarrierRead, BarrierWrite
|
||||
- 2 Reserve IDs for future async/error instrumentation
|
||||
|
||||
Mapping Notes
|
||||
- HTTP E2E shows BoxCall/NewBox dominate (33–42%), then Const/NewBox, with Branch/Jump/Phi only in error flows.
|
||||
- FileBox path similarly heavy on BoxCall/NewBox/Const.
|
||||
- Implication: invest into BoxCall fast path and const/alloc optimization.
|
||||
|
||||
Migration Strategy
|
||||
1) Introduce an experimental feature gate that switches TypeCheck/Cast to TypeOp or folds them.
|
||||
2) Demote Debug/Nop/Safepoint under non-release builds.
|
||||
3) Keep ExternCall available, route new external APIs via BoxCall when possible.
|
||||
4) Track Weak*/Barrier usage; unify under WeakRef/Barrier. Graduate dedicated ops only if vm-stats shows recurring use.
|
||||
|
||||
Mapping from Current → Final
|
||||
- TypeCheck, Cast → TypeOp
|
||||
- WeakNew, WeakLoad → WeakRef
|
||||
- BarrierRead, BarrierWrite → Barrier
|
||||
- (Keep) ExternCall, but prefer BoxCall where possible（ExternCall は最小限に）
|
||||
- (Keep) Debug/Nop/Safepoint as meta under non-release builds（命令セット外のビルドモード制御に降格）
|
||||
|
||||
Verification
|
||||
- Add MIR verifier rule: use-before-def across merges is rejected (guards phi misuse).
|
||||
- Add snapshot tests for classic if-merge returning phi.
|
||||
|
||||
Appendix: Rationale
|
||||
- Smaller ISA simplifies VM fast paths and aids JIT/AOT later.
|
||||
- Data shows hot paths concentrated on calls, const, alloc; control sparse and localized.
|
||||
- Folding type ops reduces interpreter/VM dispatch; verification handles safety.
|
||||
---
|
||||
|
||||
Feature Flags (Cargo)
|
||||
- Deprecated flags (unified by default):
|
||||
- `mir_typeop_poc`: no-op now. Builder always emits `TypeOp(Check/Cast)` instead of legacy `TypeCheck/Cast`。
|
||||
- `mir_refbarrier_unify_poc`: no-op now. Builder always emits `WeakRef/Barrier` instead of legacy `WeakNew/WeakLoad/BarrierRead/Write`。
|
||||
- Optimizer has a Pass 0 that normalizes any残存の旧命令 → 統合命令（安全ネット）。
|
||||
|
||||
Status (2025-08-23)
|
||||
- Flags declared in `Cargo.toml` (off by default)
|
||||
- PoC design doc: `docs/development/proposals/mir-typeop-weakref-barrier-poc.md`
|
||||
- Next: land builder/VM mapping behind flags, add snapshot tests; no behavior change with flags off
|
||||
@ -1,218 +0,0 @@
|
||||
# MIR → VM Mapping (Draft)
|
||||
|
||||
最終更新: 2025-08-23
|
||||
|
||||
目的: 生成されたMIR命令がVMでどう実行されるかを1枚で把握し、欠落や暫定実装を洗い出す。26命令ダイエット検討の足場にする。
|
||||
|
||||
記法: 状態 = Implemented / Partial / No-op / TODO。
|
||||
|
||||
## コア命令
|
||||
- Const: Implemented
|
||||
- 定数を `VMValue` に格納。
|
||||
- BinOp: Partial
|
||||
- Integer: Add/Sub/Mul/Div 実装（Divは0割チェック）。他の算術/論理/ビット演算は TODO。
|
||||
- String: `+` 連結のみ対応。その他は TypeError。
|
||||
- UnaryOp: Partial
|
||||
- `Neg`(int), `Not`(bool) のみ。`BitNot` は TODO。
|
||||
- Compare: Partial
|
||||
- Integer/ String の Eq/Ne/Lt/Le/Gt/Ge 対応。Bool は Eq/Ne のみ。
|
||||
- Void は値を持たないため、比較は Eq/Ne のみ定義。
|
||||
- `Void == Void` は true、`Void != Void` は false
|
||||
- `Void == X` は false、`Void != X` は true（順序比較は TypeError）
|
||||
- Load / Store: Implemented
|
||||
- 現状はVM内の値スロット操作（簡易）。
|
||||
- Copy: Implemented
|
||||
- 値コピー＋クラス名/内部参照印の伝播。
|
||||
|
||||
## 制御フロー
|
||||
- Branch / Jump / Return: Implemented
|
||||
- Branchの条件は `Bool` を期待。以下の動的変換を許容：
|
||||
- `Integer` → 非ゼロは true
|
||||
- `BoxRef(BoolBox)` → 中身のbool
|
||||
- `BoxRef(VoidBox)` → false（nullish false）
|
||||
- Phi: Implemented
|
||||
- `LoopExecutor` による選択実装（前BB情報を利用）。
|
||||
|
||||
## 呼び出し/Box関連
|
||||
- Call: Implemented
|
||||
- 関数名を `Const String` として解決しVM内ディスパッチ。
|
||||
- BoxCall: Partial
|
||||
- InstanceBox: `{Class}.{method}/{argc}` へ降格呼び出し（MIR関数）。
|
||||
- PluginBoxV2: cfg(feature="plugins")下でLoader経由invoke（引数: NyashBox配列）。
|
||||
- Builtinの簡易ディスパッチ: `StringBox.length/substr/concat`, `IntegerBox.toString/abs` 等の最小対応。
|
||||
- birth 特例: user-definedの `birth` はMIR関数へ直呼。
|
||||
- NewBox: Implemented
|
||||
- `runtime.box_registry` から生成。`scope_tracker` に登録。クラス名マップ更新。
|
||||
- TypeCheck: No-op (常にtrue)
|
||||
- TODO: 正式な型チェックに置換。
|
||||
- Cast: No-op (コピー)
|
||||
- TODO: 正式な型変換に置換。
|
||||
|
||||
## 配列
|
||||
- ArrayGet: ArrayBox.get(index) を呼び出し、戻り値を格納（VM対応済み）
|
||||
- ArraySet: ArrayBox.set(index, value) を呼び出し（VM対応済み）
|
||||
|
||||
## デバッグ/出力
|
||||
- Debug: No-op（性能優先）
|
||||
- Print: Implemented（`to_string()`して標準出力）
|
||||
- Nop: No-op
|
||||
|
||||
## 例外/安全ポイント
|
||||
- Throw: Partial
|
||||
- 例外値を表示してVMErrorで中断。ハンドラ探索なし。
|
||||
- Catch: No-op
|
||||
- 例外値スロットを `Void` セットのみ。制御遷移の実装は未対応。
|
||||
- Safepoint: No-op
|
||||
|
||||
## 参照/弱参照/バリア
|
||||
- RefNew / RefGet / RefSet: Partial
|
||||
- `object_fields` に簡易格納。`object_class` と `box_declarations` を用いた可視性（public/private）簡易検査あり。
|
||||
- WeakNew / WeakLoad: No-op相当（通常コピー/取得と同値）
|
||||
- TODO: 実際の弱参照生存判定を導入。
|
||||
- BarrierRead / BarrierWrite: No-op
|
||||
- 効果注釈のみ（将来の最適化/並行実行基盤に備えた形）。
|
||||
|
||||
## 非同期
|
||||
- FutureNew / FutureSet / Await: Implemented
|
||||
- `boxes::future::FutureBox` を利用し、同期ブロッキングで結果取得。
|
||||
|
||||
## 外部呼び出し
|
||||
- ExternCall: Implemented
|
||||
- `runtime::get_global_loader_v2().extern_call(iface, method, args)` にルーティング。Some/Noneで戻り値void扱いも考慮。
|
||||
|
||||
---
|
||||
|
||||
## Result / Err / Handle（BoxRef） 取り扱い（重要）
|
||||
|
||||
目的: プラグイン呼び出し（BoxCall→PluginLoaderV2）およびVM内の戻り値で、ResultとBoxRef（Handle）を正しく扱うための合意事項。
|
||||
|
||||
- HTTP系（Netプラグイン）の約束
|
||||
- unreachable（接続不可/タイムアウト等）: `Result.Err(ErrorBox)` にマップする。
|
||||
- HTTP 404/500 等のステータス異常: `Result.Ok(Response)` として返す（アプリ層で扱う）。
|
||||
- FileBox等のVoid戻り
|
||||
- `close()` のような副作用のみのメソッドは `Ok(Void)` を返す。VMではVoidの実体は持たない。
|
||||
- Handle（BoxRef）戻り値
|
||||
- プラグインは TLV tag=8（Handle）で `type_id:u32, instance_id:u32` を返す。
|
||||
- Loader は返り値の `type_id` に対応する正しい `fini_method_id` を設定し、`PluginBoxV2` を生成してVMへ返す。
|
||||
- 注意: 生成元のBoxと返り値のBoxの型が異なるケースがあるため、「呼び出し元のfini値を流用しない」。必ず返り値 `type_id` を基に解決する。
|
||||
- Resultの整合
|
||||
- VMは `Result<T, ErrorBox>` をネイティブ表現し、`match` 等で分岐可能。
|
||||
- `Ok(Void)` は `match Ok(_)` と等価に扱える（Voidは値を持たない）。
|
||||
|
||||
参考: TLV/Loader仕様は `docs/reference/plugin-system/ffi-abi-specification.md` と `plugin-tester.md` を参照。
|
||||
|
||||
---
|
||||
|
||||
## 既知の課題（抜粋）
|
||||
- BinOp/UnaryOp/Compare の型拡張（浮動小数・Bool/Box等）。
|
||||
- ArrayGet/ArraySet の実装。
|
||||
- TypeCheck/Cast の正規化（型表現と整合）。
|
||||
- 例外ハンドリング（Throw/Catchの制御フロー接続）。
|
||||
- WeakRef/Barrier の実体化（必要性評価の上、命令ダイエット候補）。
|
||||
- PluginBoxV2 のVM側統合強化（引数/戻り値のTLV全型対応、Handle戻り値→BoxRef化）。
|
||||
|
||||
Verifier（検証）に関する追加事項（方針）
|
||||
- use-before-def across merge の強化: merge後にphiが未使用/未定義を選択するパスを禁止。
|
||||
- if-merge の戻り: retはphiのdstを返す（実装済み）。
|
||||
- TypeOp（TypeCheck/Cast）と命令の整合: Verifierで型注釈に基づく不一致を検出。
|
||||
|
||||
## VM統計（計測）
|
||||
- `--vm-stats` / `--vm-stats-json` で命令ごとの使用回数と時間(ms)を出力。
|
||||
- ホット命令抽出によりダイエット候補を定量化。
|
||||
|
||||
---
|
||||
|
||||
## 実測結果サマリー（初回プローブ）
|
||||
出所: `local_tests/vm_stats_hello.json`, `local_tests/vm_stats_loop.json`, `simple_math.nyash`
|
||||
|
||||
- ループ系（139命令 / 0.158ms）トップ:
|
||||
- Const: 25, BoxCall: 23, NewBox: 23, BinOp: 11, Branch: 11, Compare: 11, Jump: 11, Phi: 11, Safepoint: 11
|
||||
- 所見: ループloweringで Branch/Jump/Phi/Safepoint が並び、Box初期化とBoxCallが多い。
|
||||
- Hello系（6命令）: 期待どおりの最小構成（Const/Print/Return中心）。
|
||||
- simple_math（18命令）: BinOpの使用を確認（整数加減乗除）。
|
||||
|
||||
補足:
|
||||
- Safepoint はMIR上で挿入されるが、VMではNo-op（計測には現れる）。
|
||||
- NewBox/BoxCall が上位に入るため、命令セットから外すのは不可（コア扱い）。
|
||||
- Compare/Branch/Jump/Phi は制御フローのコア。26命令の中核として維持が妥当。
|
||||
|
||||
## 実測統計（2025-08-23）
|
||||
出所: vm-stats（正常系HTTP／異常系HTTP／FileBox）
|
||||
|
||||
- 正常系HTTP（40命令）
|
||||
- BoxCall: 17（42.5%）/ Const: 12（30%）/ NewBox: 9（22.5%）/ Return: 1 / Safepoint: 1
|
||||
- 異常系HTTP（21命令 = 正常の52.5%）
|
||||
- BoxCall: 7（33.3%）/ Const: 6（28.6%）/ NewBox: 3（14.3%）
|
||||
- Branch: 1 / Jump: 1 / Phi: 1（エラーハンドリング特有）/ Return: 1 / Safepoint: 1
|
||||
- FileBox（44命令）
|
||||
- BoxCall: 17（38.6%）/ Const: 13（29.5%）/ NewBox: 12（27.3%）/ Return: 1 / Safepoint: 1
|
||||
|
||||
設計含意:
|
||||
- BoxCallが常に最頻出（33〜42%）。呼び出しコスト最適化が最優先。
|
||||
- Const/NewBoxが次点。定数・生成の最適化（定数畳み込み／軽量生成・シェアリング）が効果的。
|
||||
- 異常系は早期収束で命令半減。if/phi修正は実戦で有効（Branch/Jump/Phiが顕在化）。
|
||||
|
||||
補足（HTTP 404/500の比較）
|
||||
- 404（"Not Found"）、500（"Internal Server Error"）ともに同一プロファイル（合計55命令）
|
||||
- 内訳例: BoxCall: 23 / Const: 16 / NewBox: 12 / BinOp: 2 / Return: 1 / Safepoint: 1
|
||||
- ステータス差はアプリ層で完結し、VM命令の分布には有意差なし（設計の意図どおり）
|
||||
|
||||
## 26命令ダイエット（検討のたたき台）
|
||||
方針: 「命令の意味は保ちつつ集約」。代表案：
|
||||
- 維持: Const / Copy / Load / Store / BinOp / UnaryOp / Compare / Jump / Branch / Phi / Return / Call / BoxCall / NewBox / ArrayGet / ArraySet
|
||||
- 参照: RefNew / RefGet / RefSet（Weak/Barrierは拡張枠へ）
|
||||
- 非同期: Await（FutureNew/SetはBox APIへ寄せる案も可）
|
||||
- I/O: Print は開発モード限定 or ExternCall統合（ExternCall自体はBoxCallへ統合方針）
|
||||
- 調整: TypeCheck/Cast はVerifier/型系に寄せる（命令から外す or 1命令に集約）
|
||||
- Debug/Nop/Safepoint: メタ扱い（命令数からは外す）
|
||||
|
||||
次ステップ:
|
||||
- サンプル/テストをVMで実行し、`vm-stats`結果から実使用命令セットを抽出。
|
||||
- 上記案に対し互換影響を洗い出し、段階移行（エイリアス→削除）を設計。
|
||||
|
||||
---
|
||||
|
||||
## 26命令ダイエットの指針（実測反映）
|
||||
- 維持（ホット・コア）: BoxCall / NewBox / Const / BinOp / Compare / Branch / Jump / Phi / Return / Copy / Load / Store / Call
|
||||
- 実装方針: ExternCallは原則BoxCallへ集約（必要なら限定的に残す）。
|
||||
- メタ降格: Debug/Nop/Safepoint（ビルドモードで制御）。
|
||||
- 型系: TypeCheck/Castは折りたたみ or 検証時に処理（1命令に集約も可）。
|
||||
- 参照/弱参照/バリア: 需要ベースで拡張枠へ（vm-statsに登場しない限りコア外）。
|
||||
|
||||
提案（ドラフト）:
|
||||
- コア候補（例）: Const, Copy, Load, Store, BinOp, UnaryOp, Compare, Jump, Branch, Phi, Return, Call, BoxCall, NewBox, ArrayGet, ArraySet, RefNew, RefGet, RefSet, Await, Print, ExternCall(集約可), TypeOp(=TypeCheck/Cast), 予備2（将来枠）
|
||||
- 予備はWeak*/Barrierや将来の非同期拡張等に割当（実測で常用化したら昇格）。
|
||||
|
||||
---
|
||||
|
||||
## E2E更新（VM経由の実働確認）
|
||||
|
||||
成功ケース（VM）:
|
||||
- FileBox.open/write/read: 引数2個のTLVエンコード（String, String）で成功（HELLO往復）
|
||||
- FileBox.copyFrom(handle): Handle引数（tag=8, size=8, type_id+instance_id）で成功
|
||||
- HttpClientBox.get + HttpServerBox: 基本GETの往復（ResultBox経由でResponse取得）
|
||||
- HttpClientBox.post + headers: Status/ヘッダー/ボディをVMで往復確認
|
||||
- HttpClientBox.get unreachable: 接続失敗時はResult.Err(ErrorBox)（ローダーがstring/bytesをErrにマップ）
|
||||
- HTTP 404/500: Result.Ok(Response)（ステータスはResponse上に保持）
|
||||
|
||||
デバッグ小技:
|
||||
- `NYASH_DEBUG_PLUGIN=1` で VM→Plugin 呼び出しTLVの ver/argc/先頭バイトをダンプ
|
||||
- Netプラグインの内部ログ: `NYASH_NET_LOG=1 NYASH_NET_LOG_FILE=net_plugin.log`
|
||||
## 型・Null/Void・比較の扱い（更新）
|
||||
|
||||
- NullはVM内部でVoidに折りたたみ（`Const Null → VMValue::Void`）。
|
||||
- VoidとNullは同一視されない（等価比較は `Void == Void` のみtrue）。
|
||||
- Compareの対応：
|
||||
- 整数/文字列: Eq/Ne/Lt/Le/Gt/Ge（実装済）
|
||||
- 真偽値: Eq/Ne のみ
|
||||
- Void: Eq/Ne のみ（Void==Voidはtrue、それ以外はfalse）
|
||||
- 浮動小数点: Eq/Ne/Lt/Le/Gt/Ge（新規）
|
||||
- 整数と浮動小数点の混在: 双方をf64比較で対応（新規）
|
||||
|
||||
## TypeOp（PoC）
|
||||
- 目的: TypeCheck/Castの統合。
|
||||
- Check: 最小意味論を実装（Integer/Float/Bool/String/Void/Box名に対し一致判定）。
|
||||
- Cast: 当面コピー等価（将来の変換方針に備える）。
|
||||
- me 参照
|
||||
- メソッド/コンストラクタlowering時は `%0` にマップ（パラメータ）。
|
||||
- それ以外の文脈ではフォールバックとして `Const "__me__"` を一度だけ発行して変数マップに保持し、以降の `me` は同一ValueIdを参照（RefGet/RefSetの整合性を保証）。
|
||||
@ -1,235 +0,0 @@
|
||||
# 🤖 Nyash MIR (Mid-level Intermediate Representation) - 統合リファレンス
|
||||
|
||||
*26命令削減実装中・ChatGPT5仕様準拠 - 2025年8月17日版*
|
||||
|
||||
## 🚨 **重要: MIR命令削減プロジェクト進行中**
|
||||
|
||||
**現状**: 35命令実装（175%膨張）→ **目標**: 26命令（ChatGPT5仕様）
|
||||
**Gemini評価**: 削減戦略「極めて健全」「断行推奨」
|
||||
|
||||
## 🎯 **MIR概要**
|
||||
|
||||
Nyash MIRは、Everything is Box哲学を基盤とした中間表現です。現在35命令が実装され、インタープリター・VM・WASM・AOTの全バックエンドで統一された実行を実現します。
|
||||
|
||||
### **🌟 主要特徴**
|
||||
- **Everything is Box**: 全データがBoxオブジェクトとして統一表現
|
||||
- **Effect System**: pure/mut/io/control効果による最適化基盤
|
||||
- **所有権管理**: 強参照森（ownership forest）+ weak参照システム
|
||||
- **非同期対応**: Future/Bus操作の言語レベル統合
|
||||
- **FFI/ABI統合**: ExternCall命令による外部API統一呼び出し
|
||||
|
||||
## 🏗️ **命令分類 - 35命令全体系**
|
||||
|
||||
### **Tier-0: コア演算 (8命令)**
|
||||
基本的な計算・制御フロー命令
|
||||
|
||||
| 命令 | 形式 | 効果 | 説明 |
|
||||
|------|------|------|------|
|
||||
| `Const` | `%dst = const value` | pure | 定数値生成 |
|
||||
| `BinOp` | `%dst = %lhs op %rhs` | pure | 二項演算（+,-,*,/等） |
|
||||
| `UnaryOp` | `%dst = op %operand` | pure | 単項演算（not, neg等） |
|
||||
| `Compare` | `%dst = %lhs cmp %rhs` | pure | 比較演算（==, !=, <等） |
|
||||
| `Branch` | `br %cond -> %then, %else` | control | 条件分岐 |
|
||||
| `Jump` | `jmp %target` | control | 無条件ジャンプ |
|
||||
| `Return` | `ret %value?` | control | 関数戻り |
|
||||
| `Phi` | `%dst = phi [%val1:%bb1, %val2:%bb2]` | pure | SSA φ関数 |
|
||||
|
||||
### **Tier-1: メモリ・関数操作 (8命令)**
|
||||
メモリアクセス・関数呼び出し・型操作
|
||||
|
||||
| 命令 | 形式 | 効果 | 説明 |
|
||||
|------|------|------|------|
|
||||
| `Load` | `%dst = load %ptr` | pure | メモリ読み取り |
|
||||
| `Store` | `store %value -> %ptr` | mut | メモリ書き込み |
|
||||
| `Call` | `%dst = call %func(%args...)` | context | 関数呼び出し |
|
||||
| `BoxCall` | `%dst = %box.method(%args...)` | context | Boxメソッド呼び出し |
|
||||
| `NewBox` | `%dst = new_box "Type"(%args...)` | mut | Box生成 |
|
||||
| `TypeCheck` | `%dst = type_check %box "Type"` | pure | 型チェック |
|
||||
| `Cast` | `%dst = cast %value as Type` | pure | 型変換 |
|
||||
| `Copy` | `%dst = copy %src` | pure | 値コピー |
|
||||
|
||||
### **Tier-2: 配列・デバッグ・制御 (7命令)**
|
||||
配列操作・デバッグ・例外処理
|
||||
|
||||
| 命令 | 形式 | 効果 | 説明 |
|
||||
|------|------|------|------|
|
||||
| `ArrayGet` | `%dst = %array[%index]` | pure | 配列要素取得 |
|
||||
| `ArraySet` | `%array[%index] = %value` | mut | 配列要素設定 |
|
||||
| `Debug` | `debug %value "message"` | io | デバッグ出力 |
|
||||
| `Print` | `print %value` | io | コンソール出力 |
|
||||
| `Nop` | `nop` | pure | 無操作 |
|
||||
| `Throw` | `throw %exception` | control | 例外発生 |
|
||||
| `Catch` | `catch %type -> %handler` | control | 例外捕捉 |
|
||||
|
||||
### **Tier-3: 参照・非同期・外部API (12命令)**
|
||||
所有権管理・非同期処理・外部連携
|
||||
|
||||
| 命令 | 形式 | 効果 | 説明 |
|
||||
|------|------|------|------|
|
||||
| `Safepoint` | `safepoint` | io | セーフポイント |
|
||||
| `RefNew` | `%dst = ref_new %box` | pure | 参照生成 |
|
||||
| `RefGet` | `%dst = ref_get %ref.field` | pure | 参照経由読み取り |
|
||||
| `RefSet` | `ref_set %ref.field = %value` | mut | 参照経由書き込み |
|
||||
| `WeakNew` | `%dst = weak_new %box` | pure | weak参照生成 |
|
||||
| `WeakLoad` | `%dst = weak_load %weak_ref` | pure | weak参照読み取り |
|
||||
| `BarrierRead` | `barrier_read %ptr` | io | メモリバリア読み |
|
||||
| `BarrierWrite` | `barrier_write %ptr` | io | メモリバリア書き |
|
||||
| `FutureNew` | `%dst = future_new %value` | mut | Future生成 |
|
||||
| `FutureSet` | `future_set %future = %value` | mut | Future値設定 |
|
||||
| `Await` | `%dst = await %future` | io | Future待機 |
|
||||
| `ExternCall` | `%dst = extern_call iface.method(%args...)` | context | 外部API呼び出し |
|
||||
|
||||
## 🎭 **Effect System - 4種類の効果**
|
||||
|
||||
### **効果分類と最適化ルール**
|
||||
|
||||
```rust
|
||||
pub enum Effect {
|
||||
Pure, // 再順序化可能、共通部分式除去可能
|
||||
Mut, // 同一リソースで順序保持必要
|
||||
Io, // 全順序保持必要（副作用あり）
|
||||
Control, // 制御フロー変更
|
||||
}
|
||||
```
|
||||
|
||||
### **効果別命令分類**
|
||||
|
||||
#### **Pure命令 (15命令)**
|
||||
```
|
||||
Const, BinOp, UnaryOp, Compare, Phi, Load, TypeCheck, Cast, Copy,
|
||||
ArrayGet, Nop, RefNew, RefGet, WeakNew, WeakLoad
|
||||
```
|
||||
|
||||
#### **Mut命令 (7命令)**
|
||||
```
|
||||
Store, NewBox, ArraySet, RefSet, FutureNew, FutureSet
|
||||
```
|
||||
|
||||
#### **Io命令 (6命令)**
|
||||
```
|
||||
Debug, Print, Safepoint, BarrierRead, BarrierWrite, Await
|
||||
```
|
||||
|
||||
#### **Control命令 (4命令)**
|
||||
```
|
||||
Branch, Jump, Return, Throw, Catch
|
||||
```
|
||||
|
||||
#### **Context依存命令 (3命令)**
|
||||
```
|
||||
Call, BoxCall, ExternCall
|
||||
```
|
||||
*効果は呼び出し先に依存*
|
||||
|
||||
## 🔧 **重要なMIR実装詳細**
|
||||
|
||||
### **ExternCall命令 - FFI/ABI統合**
|
||||
|
||||
```rust
|
||||
ExternCall {
|
||||
dst: Option<ValueId>,
|
||||
iface_name: String, // "env.console", "nyash.math"等
|
||||
method_name: String, // "log", "sqrt"等
|
||||
args: Vec<ValueId>,
|
||||
effects: EffectMask, // BID仕様から決定
|
||||
}
|
||||
```
|
||||
|
||||
**用途**: ブラウザーAPI・ネイティブライブラリ・プラグインの統一呼び出し
|
||||
|
||||
### **所有権管理システム**
|
||||
|
||||
#### **強参照森（Ownership Forest）**
|
||||
- 各Boxは最大1つの強参照を持つ（in-degree ≤ 1）
|
||||
- 強参照による循環は禁止（DAG構造保証）
|
||||
- `NewBox`, `RefSet`で所有権移転
|
||||
|
||||
#### **weak参照システム**
|
||||
- 所有権を持たない軽量参照
|
||||
- `WeakNew`で生成、`WeakLoad`で安全アクセス
|
||||
- 参照先削除時は自動的にnull化
|
||||
|
||||
### **非同期処理 - Future操作**
|
||||
|
||||
```mir
|
||||
%future = FutureNew %initial_value // Future生成
|
||||
FutureSet %future = %result // 結果設定
|
||||
%value = Await %future // 結果取得（ブロッキング）
|
||||
```
|
||||
|
||||
## 🚀 **バックエンド別対応状況**
|
||||
|
||||
### **実装済みバックエンド**
|
||||
|
||||
| バックエンド | 対応命令数 | 主要用途 | 特徴 |
|
||||
|-------------|-----------|----------|------|
|
||||
| **Interpreter** | 35/35 | デバッグ・開発 | 全命令完全対応 |
|
||||
| **VM** | 35/35 | 高速実行 | レジスタベース |
|
||||
| **WASM** | 30/35 | Web配布 | ExternCall→import対応 |
|
||||
| **AOT準備** | 計画中 | ネイティブ | LLVM IR生成予定 |
|
||||
|
||||
### **バックエンド固有の最適化**
|
||||
|
||||
#### **VM バックエンド**
|
||||
- レジスタベース実行
|
||||
- 局所最適化（ローカルBus elision）
|
||||
- 直接スレッド化
|
||||
|
||||
#### **WASM バックエンド**
|
||||
- メモリ線形化（文字列は (ptr,len)）
|
||||
- ExternCall → import宣言自動生成
|
||||
- ホスト側JavaScript連携
|
||||
|
||||
## 📊 **MIR最適化パス**
|
||||
|
||||
### **Pure命令最適化**
|
||||
- **共通部分式除去 (CSE)**: 同一pure計算の除去
|
||||
- **不変コード移動 (LICM)**: ループ外移動
|
||||
- **定数畳み込み**: コンパイル時計算
|
||||
|
||||
### **Effect-aware最適化**
|
||||
- **Mut順序保持**: 同一リソースアクセス順序維持
|
||||
- **Io順序保持**: 全Io命令の順序保証
|
||||
- **Bus elision**: ローカル通信の直接アクセス化
|
||||
|
||||
## 🧪 **テスト・検証**
|
||||
|
||||
### **MIR検証項目**
|
||||
- [ ] **所有権森検証**: strong in-degree ≤ 1
|
||||
- [ ] **強循環禁止**: 強参照のDAG構造保証
|
||||
- [ ] **weak参照安全性**: 失効時null化
|
||||
- [ ] **効果注釈正確性**: 各命令の効果分類
|
||||
- [ ] **型安全性**: Box型システム整合性
|
||||
|
||||
### **バックエンド互換性テスト**
|
||||
```bash
|
||||
# 全バックエンドMIR一致テスト
|
||||
./target/release/nyash --dump-mir program.nyash > interpreter.mir
|
||||
./target/release/nyash --backend vm --dump-mir program.nyash > vm.mir
|
||||
./target/release/nyash --backend wasm --dump-mir program.nyash > wasm.mir
|
||||
diff interpreter.mir vm.mir && diff vm.mir wasm.mir
|
||||
```
|
||||
|
||||
## 🔮 **将来計画**
|
||||
|
||||
### **Phase 10: AOT/JIT対応**
|
||||
- LLVM IR生成バックエンド
|
||||
- ExternCall → ネイティブ関数呼び出し
|
||||
- 高度な最適化パス統合
|
||||
|
||||
### **Phase 11: MIR v2設計**
|
||||
- 命令数最適化（35 → 25命令目標）
|
||||
- BID統合（Box Interface Definition）
|
||||
- リソース所有権拡張（own<T>, borrow<T>）
|
||||
|
||||
## 📚 **関連ドキュメント**
|
||||
|
||||
- **FFI/ABI仕様**: `docs/説明書/reference/box-design/ffi-abi-specification.md`
|
||||
- **実装詳細**: `src/mir/instruction.rs`
|
||||
- **Phase計画**: `docs/予定/native-plan/copilot_issues.txt`
|
||||
|
||||
---
|
||||
|
||||
**最終更新**: 2025年8月17日
|
||||
**実装ベース**: 35命令完全対応
|
||||
**次期計画**: BID統合プラグインシステム（Phase 9.75f-BID）
|
||||
@ -1,45 +0,0 @@
|
||||
# Plugin Migration Guide v2 Enhancement Summary
|
||||
|
||||
## What was accomplished
|
||||
|
||||
This task involved enhancing the existing `docs/plugin-migration-request.md` with comprehensive implementation guidance based on the issue requirements.
|
||||
|
||||
## Key improvements made:
|
||||
|
||||
### 1. **Comprehensive nyash.toml explanation**
|
||||
- Added detailed explanation of the `from`/`to` type conversion system
|
||||
- Explained TLV (Type-Length-Value) encoding with specific tag mappings
|
||||
- Provided clear examples using FileBox as reference
|
||||
|
||||
### 2. **Detailed implementation examples**
|
||||
- Added complete Rust code examples for TLV parsing
|
||||
- Showed real HttpClientBox plugin implementation patterns
|
||||
- Included proper error handling and memory management examples
|
||||
|
||||
### 3. **Structured migration priorities**
|
||||
- **Phase 1**: Network boxes (HttpClientBox, SocketBox) - highest priority
|
||||
- **Phase 2**: GUI boxes (EguiBox, Canvas) - platform dependent
|
||||
- **Phase 3**: Special purpose boxes (TimerBox, QRBox) - independent
|
||||
|
||||
### 4. **Testing and validation guidelines**
|
||||
- Complete testing workflow with plugin-tester
|
||||
- Real Nyash code examples for validation
|
||||
- Troubleshooting guidance for common mistakes
|
||||
|
||||
### 5. **Reference implementation guidance**
|
||||
- FileBox plugin as the gold standard example
|
||||
- Specific file paths for all reference materials
|
||||
- Success tips and common pitfalls
|
||||
|
||||
## Document statistics:
|
||||
- **Length**: 368 lines (vs ~200 lines originally)
|
||||
- **Code examples**: 16 code blocks with real implementation patterns
|
||||
- **Comprehensive coverage**: TLV, nyash.toml, FFI, testing, and reference materials
|
||||
|
||||
## Validation:
|
||||
- All key sections verified to be present
|
||||
- Code examples cover the full implementation pipeline
|
||||
- References to FileBox plugin success story maintained
|
||||
- HttpClientBox positioned as Phase 1 priority target
|
||||
|
||||
The guide now serves as a complete reference for migrating any builtin Box to a plugin, with FileBox as the proven template and HttpClientBox as the next target.
|
||||
@ -1,369 +0,0 @@
|
||||
# 📦 Nyash ビルトインBox → プラグイン化移行ガイド v2
|
||||
|
||||
## 🎯 概要
|
||||
NyashのビルトインBoxをプラグイン化し、コアを軽量化します。
|
||||
FileBoxプラグインの成功例を詳しく解説しながら、移行方法を説明します。
|
||||
|
||||
## 🔑 重要な概念：nyash.tomlの型定義システム
|
||||
|
||||
### 型変換の仕組み
|
||||
nyash.tomlでは、Nyash側とプラグイン側の型変換を明示的に定義します：
|
||||
|
||||
```toml
|
||||
# FileBoxの例
|
||||
[plugins.FileBox.methods]
|
||||
# writeメソッド：Nyashのstringをプラグインではbytesとして扱う
|
||||
write = { args = [{ from = "string", to = "bytes" }] }
|
||||
|
||||
# openメソッド：2つのstring引数（型変換なし）
|
||||
open = { args = [
|
||||
{ name = "path", from = "string", to = "string" },
|
||||
{ name = "mode", from = "string", to = "string" }
|
||||
] }
|
||||
```
|
||||
|
||||
### from/toの意味
|
||||
- **from**: Nyash側の型（ユーザーが渡す型）
|
||||
- **to**: プラグイン側で受け取る型（TLVエンコーディング）
|
||||
|
||||
### TLVタグとの対応
|
||||
プラグインはTLV（Type-Length-Value）形式でデータを受け取ります：
|
||||
- `to = "i32"` → TLV tag=2（32ビット整数）
|
||||
- `to = "string"` → TLV tag=6（UTF-8文字列）
|
||||
- `to = "bytes"` → TLV tag=7（バイト配列）
|
||||
|
||||
## 📋 移行対象Box一覧（優先順位順）
|
||||
|
||||
### 🌐 Phase 1: ネットワーク系（最優先・最も簡単）
|
||||
既にスタブ実装があり、reqwest依存を追加するだけで完成します。
|
||||
|
||||
#### HttpClientBox
|
||||
```toml
|
||||
[plugins.HttpClientBox.methods]
|
||||
# シンプルなGETリクエスト
|
||||
get = {
|
||||
args = [{ from = "string", to = "string" }], # URL
|
||||
returns = "string" # レスポンスボディ
|
||||
}
|
||||
|
||||
# POSTリクエスト（ボディ付き）
|
||||
post = {
|
||||
args = [
|
||||
{ from = "string", to = "string" }, # URL
|
||||
{ from = "string", to = "bytes" } # ボディ（バイナリ対応）
|
||||
],
|
||||
returns = "string"
|
||||
}
|
||||
|
||||
# 詳細なリクエスト（ヘッダー等を含む）
|
||||
request = {
|
||||
args = [
|
||||
{ from = "string", to = "string" }, # メソッド（GET/POST等）
|
||||
{ from = "string", to = "string" }, # URL
|
||||
{ from = "map", to = "map" } # オプション（headers, timeout等）
|
||||
],
|
||||
returns = "map" # { status: i32, body: string, headers: map }
|
||||
}
|
||||
```
|
||||
|
||||
### 🖼️ Phase 2: GUI系（プラットフォーム依存）
|
||||
EguiBoxは既にfeature分離されているので参考になります。
|
||||
|
||||
### 🎵 Phase 3: 特殊用途系（独立性高い）
|
||||
TimerBox、QRBox等は単機能で実装しやすいです。
|
||||
|
||||
## 🔧 実装ガイドライン
|
||||
|
||||
### 1. 参考にするファイル
|
||||
- **成功例**: `plugins/nyash-filebox-plugin/` - 動作確認済みのFileBoxプラグイン
|
||||
- **設定例**: `nyash.toml` - 型情報定義の書き方
|
||||
- **テスト**: `tools/plugin-tester/` - プラグイン診断ツール
|
||||
|
||||
### 2. 各プラグインの構成
|
||||
```
|
||||
plugins/nyash-xxx-plugin/
|
||||
├── Cargo.toml # 依存関係（例: reqwest for HTTP）
|
||||
├── src/
|
||||
│ └── lib.rs # FFI実装
|
||||
├── nyash.toml # 型情報定義
|
||||
└── README.md # 使用方法
|
||||
```
|
||||
|
||||
### 3. nyash.toml記述例（HttpClientBoxの場合）
|
||||
```toml
|
||||
[plugins.HttpClientBox.methods]
|
||||
# GETリクエスト
|
||||
get = {
|
||||
args = [{ name = "url", from = "string", to = "string" }],
|
||||
returns = "string"
|
||||
}
|
||||
|
||||
# POSTリクエスト
|
||||
post = {
|
||||
args = [
|
||||
{ name = "url", from = "string", to = "string" },
|
||||
{ name = "body", from = "string", to = "string" }
|
||||
],
|
||||
returns = "string"
|
||||
}
|
||||
|
||||
# ヘッダー付きリクエスト
|
||||
request = {
|
||||
args = [
|
||||
{ name = "method", from = "string", to = "string" },
|
||||
{ name = "url", from = "string", to = "string" },
|
||||
{ name = "options", from = "map", to = "map" }
|
||||
],
|
||||
returns = "map" # { status, body, headers }
|
||||
}
|
||||
|
||||
# DELETE リクエスト
|
||||
delete = {
|
||||
args = [{ name = "url", from = "string", to = "string" }],
|
||||
returns = "string"
|
||||
}
|
||||
|
||||
# PUT リクエスト
|
||||
put = {
|
||||
args = [
|
||||
{ name = "url", from = "string", to = "string" },
|
||||
{ name = "body", from = "string", to = "string" }
|
||||
],
|
||||
returns = "string"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. テスト方法
|
||||
```bash
|
||||
# ビルド
|
||||
cd plugins/nyash-xxx-plugin
|
||||
cargo build --release
|
||||
|
||||
# plugin-testerで診断
|
||||
cd ../../tools/plugin-tester
|
||||
./target/release/plugin-tester ../../plugins/nyash-xxx-plugin/target/release/libnyash_xxx_plugin.so
|
||||
|
||||
# Nyashで実行テスト
|
||||
./target/release/nyash test_xxx.nyash
|
||||
```
|
||||
|
||||
## 📝 特記事項
|
||||
|
||||
### HttpBox系
|
||||
- 現在スタブ実装なので移行しやすい
|
||||
- reqwest依存を復活させる
|
||||
- 非同期処理の考慮が必要
|
||||
|
||||
### EguiBox
|
||||
- 既にfeature分離されているので参考になる
|
||||
- メインスレッド制約に注意
|
||||
|
||||
### AudioBox/SoundBox
|
||||
- プラットフォーム依存性が高い
|
||||
- Web/Desktop両対応を検討
|
||||
|
||||
### 依存関係の管理
|
||||
- 各プラグインは独立したCargo.tomlを持つ
|
||||
- ビルド時間短縮のため最小限の依存にする
|
||||
|
||||
## 💡 実装の重要ポイント
|
||||
|
||||
### FFI境界での注意事項
|
||||
1. **メモリ管理**:
|
||||
- Rustの所有権とCのメモリ管理の違いに注意
|
||||
- 文字列は必ずCString/CStr経由で変換
|
||||
|
||||
2. **エラーハンドリング**:
|
||||
- パニックをFFI境界で止める（catch_unwind使用）
|
||||
- エラーコードで通信（0=成功, 負値=エラー）
|
||||
|
||||
3. **型変換パターン** (FileBoxプラグインより):
|
||||
```rust
|
||||
// Nyash文字列 → Rust文字列
|
||||
let path = get_string_arg(&args[0], 0)?;
|
||||
|
||||
// Rust文字列 → Nyash文字列
|
||||
encode_string_result(&contents, result, result_len)
|
||||
```
|
||||
|
||||
### 参考ファイルの具体的パス
|
||||
- **FileBoxプラグイン実装**: `plugins/nyash-filebox-plugin/src/lib.rs`
|
||||
- **FFI仕様書**: `docs/説明書/reference/plugin-system/ffi-abi-specification.md`
|
||||
- **プラグインシステム説明**: `docs/説明書/reference/plugin-system/plugin-system.md`
|
||||
- **BID-FFI型変換** (参考): `src/bid-converter-copilot/tlv.rs`
|
||||
|
||||
## 🔧 実装ガイド：FileBoxを例に
|
||||
|
||||
### 1. プラグイン側での型受け取り例
|
||||
|
||||
```rust
|
||||
// nyash.toml: write = { args = [{ from = "string", to = "bytes" }] }
|
||||
METHOD_WRITE => {
|
||||
// TLVでbytesとして受け取る
|
||||
let data = tlv_parse_bytes(args)?; // Vec<u8>として取得
|
||||
|
||||
// ファイルに書き込み
|
||||
match file.write(&data) {
|
||||
Ok(n) => {
|
||||
file.flush()?; // 重要：フラッシュを忘れずに！
|
||||
// 書き込んだバイト数を返す（TLV i32）
|
||||
write_tlv_i32(n as i32, result, result_len)
|
||||
}
|
||||
Err(_) => NYB_E_PLUGIN_ERROR
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 複数引数の解析例
|
||||
|
||||
```rust
|
||||
// nyash.toml: open = { args = [{ from = "string", to = "string" }, { from = "string", to = "string" }] }
|
||||
METHOD_OPEN => {
|
||||
// 2つのstring引数を解析
|
||||
let (path, mode) = tlv_parse_two_strings(args)?;
|
||||
|
||||
// ファイルを開く
|
||||
let file = match mode.as_str() {
|
||||
"r" => File::open(&path)?,
|
||||
"w" => File::create(&path)?,
|
||||
"a" => OpenOptions::new().append(true).open(&path)?,
|
||||
_ => return NYB_E_INVALID_ARGS
|
||||
};
|
||||
|
||||
// 成功時はVoid（空）を返す
|
||||
write_tlv_void(result, result_len)
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 引数なしメソッドの例
|
||||
|
||||
```rust
|
||||
// nyash.toml: read = { args = [] }
|
||||
METHOD_READ => {
|
||||
// 引数なし - ファイル全体を読む
|
||||
file.seek(SeekFrom::Start(0))?;
|
||||
let mut buf = Vec::new();
|
||||
file.read_to_end(&mut buf)?;
|
||||
|
||||
// bytesとして返す
|
||||
write_tlv_bytes(&buf, result, result_len)
|
||||
}
|
||||
```
|
||||
|
||||
## 📝 HttpClientBox実装の具体例
|
||||
|
||||
```rust
|
||||
// HttpClientBoxプラグインの実装イメージ
|
||||
use reqwest::blocking::Client;
|
||||
|
||||
METHOD_GET => {
|
||||
// URLを解析
|
||||
let url = tlv_parse_string(args)?;
|
||||
|
||||
// HTTPリクエスト実行
|
||||
let client = Client::new();
|
||||
let response = client.get(&url).send()?;
|
||||
let body = response.text()?;
|
||||
|
||||
// 文字列として返す
|
||||
write_tlv_string(&body, result, result_len)
|
||||
}
|
||||
|
||||
METHOD_POST => {
|
||||
// URL と ボディを解析
|
||||
let (url, body_bytes) = tlv_parse_string_and_bytes(args)?;
|
||||
|
||||
// POSTリクエスト
|
||||
let client = Client::new();
|
||||
let response = client.post(&url)
|
||||
.body(body_bytes)
|
||||
.send()?;
|
||||
let body = response.text()?;
|
||||
|
||||
write_tlv_string(&body, result, result_len)
|
||||
}
|
||||
```
|
||||
|
||||
## 💡 実装のコツとよくある間違い
|
||||
|
||||
### ✅ 正しいnyash.toml
|
||||
```toml
|
||||
# 引数の型変換を明示
|
||||
write = { args = [{ from = "string", to = "bytes" }] }
|
||||
|
||||
# 戻り値の型も指定可能
|
||||
exists = { args = [], returns = "bool" }
|
||||
```
|
||||
|
||||
### ❌ よくある間違い
|
||||
```toml
|
||||
# 間違い：型情報がない
|
||||
write = { args = ["string"] } # ❌ from/toが必要
|
||||
|
||||
# 間違い：不要なフィールド
|
||||
get = { args = [{ type = "string" }] } # ❌ typeではなくfrom/to
|
||||
```
|
||||
|
||||
### メモリ管理の注意点
|
||||
1. 文字列は必ずCString/CStr経由で変換
|
||||
2. プラグイン側でallocしたメモリはプラグイン側でfree
|
||||
3. ホスト側のVtableを使ってログ出力
|
||||
|
||||
### エラーハンドリング
|
||||
```rust
|
||||
// パニックをFFI境界で止める
|
||||
let result = std::panic::catch_unwind(|| {
|
||||
// 実際の処理
|
||||
});
|
||||
|
||||
match result {
|
||||
Ok(val) => val,
|
||||
Err(_) => NYB_E_PLUGIN_ERROR
|
||||
}
|
||||
```
|
||||
|
||||
## 🧪 テスト方法
|
||||
|
||||
### 1. プラグインビルド
|
||||
```bash
|
||||
cd plugins/nyash-http-plugin
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
### 2. plugin-testerで診断
|
||||
```bash
|
||||
cd ../../tools/plugin-tester
|
||||
./target/release/plugin-tester ../../plugins/nyash-http-plugin/target/release/libnyash_http_plugin.so
|
||||
|
||||
# 期待される出力：
|
||||
# Plugin Information:
|
||||
# Box Type: HttpClientBox (ID: 20)
|
||||
# Methods: 5
|
||||
# - birth [ID: 0] (constructor)
|
||||
# - get, post, put, delete
|
||||
# - fini [ID: 4294967295] (destructor)
|
||||
```
|
||||
|
||||
### 3. Nyashで実行
|
||||
```nyash
|
||||
// test_http.nyash
|
||||
local http = new HttpClientBox()
|
||||
local response = http.get("https://api.example.com/data")
|
||||
print(response)
|
||||
```
|
||||
|
||||
## 📚 参考資料
|
||||
- **FileBoxプラグイン完全実装**: `plugins/nyash-filebox-plugin/src/lib.rs`
|
||||
- **TLVエンコーディング仕様**: `docs/説明書/reference/plugin-system/ffi-abi-specification.md`
|
||||
- **nyash.toml設定例**: プロジェクトルートの`nyash.toml`
|
||||
|
||||
## 🎯 成功の秘訣
|
||||
1. **FileBoxを完全に理解してから始める** - コピペベースで改造
|
||||
2. **nyash.tomlの型定義を正確に** - from/toを明示
|
||||
3. **TLVの理解** - tag=6(string), tag=7(bytes)の違い
|
||||
4. **plugin-testerで早期検証** - 問題を早期発見
|
||||
|
||||
---
|
||||
|
||||
質問があれば、FileBoxの実装を参考にしてください。
|
||||
すべての答えがそこにあります！
|
||||
Reference in New Issue
Block a user