54 lines
2.8 KiB
Markdown
54 lines
2.8 KiB
Markdown
|
# Phase 10.5a – Python 統合 ABI 設計（Draft）
|
|||
|
|
|
|||
|
|
目的: Everything is Plugin/AOT の既存基盤上に Python を最小リスクで統合するための ABI と型・メソッド定義を固定する。
|
|||
|
|
|
|||
|
|
## スコープ（10.5a）
|
|||
|
|
- v2 プラグイン ABI 準拠（`nyash_plugin_abi/init/invoke`）の Python プラグイン雛形を作成
|
|||
|
|
- 2 Box を定義: `PyRuntimeBox(type_id=40)`, `PyObjectBox(type_id=41)`
|
|||
|
|
- メソッド ID の割り当てと TLV 方針を文書化（実装は 10.5b 以降）
|
|||
|
|
|
|||
|
|
## TLV マッピング（現行運用）
|
|||
|
|
- 1 = Bool (1 byte)
|
|||
|
|
- 2 = I32 (4 bytes, LE)
|
|||
|
|
- 3 = I64 (8 bytes, LE)
|
|||
|
|
- 4 = F32 (4 bytes, LE)
|
|||
|
|
- 5 = F64 (8 bytes, LE)
|
|||
|
|
- 6 = String (UTF-8, n bytes)
|
|||
|
|
- 7 = Bytes (opaque, n bytes)
|
|||
|
|
- 8 = Handle/BoxRef (`u32 type_id || u32 instance_id`)
|
|||
|
|
|
|||
|
|
備考: 既存ドキュメントには古い表記の混在があるため、VM_README 準拠で統一。
|
|||
|
|
|
|||
|
|
## Box とメソッド設計
|
|||
|
|
|
|||
|
|
### PyRuntimeBox (type_id=40)
|
|||
|
|
- birth(0): ランタイムの生成（後続で GIL 初期化などを担当）。戻り値: `instance_id`（非 TLV, u32 LE）
|
|||
|
|
- eval(1, code: String): Python コードを評価して `PyObjectBox` を返す。戻り値: `Handle(tag=8)`
|
|||
|
|
- import(2, name: String): `__import__(name)` または `importlib.import_module`。戻り値: `Handle(tag=8)`
|
|||
|
|
- fini(MAX): ランタイム破棄（GIL 終了・クリーンアップ）
|
|||
|
|
|
|||
|
|
### PyObjectBox (type_id=41)
|
|||
|
|
- birth(0): 予約（通常は runtime 側から生まれる）
|
|||
|
|
- getattr(1, name: String): 属性取得 → `Handle(tag=8)`
|
|||
|
|
- call(2, args: TLV...): 可変長引数。初期段は I64/String/Bool/Bytes/Handle のサブセットに限定。戻り値: `Handle(tag=8)`
|
|||
|
|
- str(3): Python 側で `PyObject_Str` → String へ。戻り値: `String(tag=6)`
|
|||
|
|
- fini(MAX): 参照カウント `Py_DECREF` に対応（後続）
|
|||
|
|
|
|||
|
|
## 参照管理・GIL（概要）
|
|||
|
|
- GIL: birth/invoke/fini の入口で確保し、出口で解放（再入を許容）。
|
|||
|
|
- 参照: `PyObjectBox` は生成時に `INCREF`、`fini` で `DECREF`。ランタイム終了時に孤立検知の簡易テストを導入。
|
|||
|
|
|
|||
|
|
## 設定ファイル（nyash.toml）
|
|||
|
|
- `libnyash_python_plugin.so` を 2 Box 含む形で登録（path/type_id/method_id を固定）
|
|||
|
|
- JIT/VM 側は既存の `plugin_invoke` 経由で呼び出し（AOT は 10.5d で `libnyrt.a` にシム追加）
|
|||
|
|
|
|||
|
|
## 次フェーズ（10.5b 以降）
|
|||
|
|
- 10.5b: `PyRuntimeBox`/`PyObjectBox` 実装（CPython 埋め込み、最小 RO 経路）
|
|||
|
|
- 10.5c: Python→Nyash 方向（CPython 拡張 `nyashrt`）
|
|||
|
|
- 10.5d: JIT/AOT 連携（`emit_plugin_invoke` 対応・静的リンクシム）
|
|||
|
|
- 10.5e: サンプル・テスト・ドキュメント
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
補足: 本ドキュメントは「設計の固定」を目的とし、実装は段階的に進める。タグ/ID は既存と衝突しない値を選定した（40/41）。
|