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（生成）

MIRの NewBox { box_type, args }
VM: runtime.box_registry に box_type を問い合わせ
PluginBoxの場合、Loader v2が birth(method_id=0) を TLV で呼び出し
Pluginは type_id と新規 instance_id を返却 → Loader は PluginBoxV2 を構築
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）

Nyash: r = cli.get(url)
MIR: BoxCall（returns_result=true）
VM→Loader: TLV（url = tag=6）
Loader→Plugin: invoke(type_id=HttpClient, method_id=get)
Plugin:
- 接続成功: Handle(HttpResponse) を返す → Loaderは Result.Ok(PluginBoxV2)
- 接続失敗: String("connect failed …") を返す → Loaderは Result.Err(ErrorBox)
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最優先）

5.6 KiB Raw Blame History Unescape Escape

Dynamic Plugin Flow (VM × Registry × PluginLoader v2)

ハイレベル流れ（シーケンス）

主要構成要素

NewBox（生成）

BoxCall（メソッド呼び出し）

TLV（Type-Length-Value）

戻り値のマッピング（重要）

Handle（BoxRef）のライフサイクル

具体例（HttpClientBox.get）

nyash.toml 連携

デバッグTips

将来の整合・改善

5.6 KiB

Raw Blame History