test: green up after Phase 2 merge for #26\n\n- Fix AST tests (is_override)\n- Align MIR builder test with current If AST\n- Adjust ResultBox API usage in tests\n- Add len() helpers to ArrayBox/BufferBox for tests

2025-08-13 11:53:34 +09:00
parent c6f76505b5
commit 2eba31143a
107 changed files with 6435 additions and 13 deletions
--- a/docs/reference/finalization-system.md
+++ b/docs/reference/finalization-system.md
@ -0,0 +1,252 @@
+# 🔥 Nyash finiシステム - 論理的解放フック
+
+**最終更新: 2025年8月13日 - ChatGPT5協議による革命的設計完了**
+
+## 🎯 概要
+
+Nyashの`fini()`システムは、物理的メモリ破棄ではなく**論理的使用終了**を宣言する革新的なリソース管理システムです。Everything is Box哲学と完全に統合され、予測可能で安全なリソース管理を実現します。
+
+## 🌟 核心コンセプト
+
+### 📝 論理的解放フック
+```nyash
+box MyResource {
+    init { name, file }
+    
+    fini() {
+        print("Resource " + me.name + " is being finalized")
+        // ファイルクローズなどのクリーンアップ処理
+        // 物理的メモリは共有参照が残っていても論理的には「終了」
+    }
+}
+```
+
+**重要**: `fini()`は「このオブジェクトをもう使わない」という宣言であり、物理的な即時破棄ではありません。
+
+## 🔄 実行順序（最終仕様）
+
+### 自動カスケード解放
+```nyash
+box Pipeline {
+    init { r1, r2, r3, weak monitor }
+    
+    fini() {
+        // 1) ユーザー定義処理（柔軟な順序制御可能）
+        me.r3.fini()  // 依存関係でr3→r2の順
+        me.r2.fini()
+        
+        // 2) 自動カスケード: 残りのr1がinit宣言順で自動解放
+        // 3) weakフィールドは対象外（lazy nil化）
+    }
+}
+```
+
+### 決定的な解放順序
+1. **finalized チェック** - 既に解放済みなら何もしない（idempotent）
+2. **再入防止** - `in_finalization`フラグで再帰呼び出し防止
+3. **ユーザー定義fini()実行** - カスタムクリーンアップ処理
+4. **自動カスケード** - `init`宣言順で未処理フィールドを解放
+5. **フィールドクリア** - 全フィールドを無効化
+6. **finalized設定** - 以後の使用を禁止
+
+## ⚠️ 厳格な禁止事項
+
+### weak フィールドへのfini呼び出し禁止
+```nyash
+box Parent {
+    init { weak child }
+    
+    fini() {
+        // ❌ 絶対にダメ！ビルドエラーまたは実行時エラー
+        // me.child.fini()  
+        
+        // ✅ 正しい方法
+        me.child = null    // 参照解除
+        // または自動nil化に任せる
+    }
+}
+```
+
+**理由**: weak参照は所有権を持たない非所有参照のため、fini()を呼ぶ権利がありません。
+
+### finalized後の使用禁止
+```nyash
+box Example { }
+
+local x = new Example()
+x.fini()
+
+// ❌ 以下は全てエラー
+x.someMethod()      // → "Instance was finalized; further use is prohibited"
+x.field = value     // → 同上
+local val = x.field // → 同上
+```
+
+## 🏗️ 実装アーキテクチャ
+
+### InstanceBox拡張
+```rust
+pub struct InstanceBox {
+    // 既存フィールド...
+    
+    init_field_order: Vec<String>,                    // 決定的カスケード順序
+    weak_fields_union: HashSet<String>,               // weak判定高速化
+    in_finalization: bool,                            // 再入防止
+    finalized: bool,                                  // 使用禁止フラグ
+}
+```
+
+### 実行時ガード
+- **メソッド呼び出し**: `finalized`チェック → エラー
+- **フィールドアクセス**: `finalized`チェック → エラー  
+- **フィールド代入**: `finalized`チェック → エラー
+
+## 💡 使用例とパターン
+
+### 基本的な使用例
+```nyash
+box FileHandler {
+    init { filename, handle }
+    
+    pack(name) {
+        me.filename = name
+        me.handle = openFile(name)
+    }
+    
+    fini() {
+        if (me.handle != null) {
+            closeFile(me.handle)
+            print("File " + me.filename + " closed")
+        }
+    }
+}
+
+// 使用
+local handler = new FileHandler("data.txt")
+// ... ファイル操作 ...
+handler.fini()  // 明示的クリーンアップ
+```
+
+### 再代入時の自動解放
+```nyash
+box Holder { init { resource } }
+box Resource { fini() { print("Resource cleaned up") } }
+
+local h = new Holder()
+h.resource = new Resource()     // 新しいリソース設定
+h.resource = new Resource()     // → 前のリソースが自動的にfini()される
+```
+
+### カスタム解放順序
+```nyash
+box DatabaseConnection {
+    init { transaction, connection, logger }
+    
+    fini() {
+        // 依存関係に基づく手動順序制御
+        if (me.transaction != null) {
+            me.transaction.rollback()
+            me.transaction.fini()
+        }
+        
+        if (me.connection != null) {
+            me.connection.close()
+            me.connection.fini()
+        }
+        
+        // loggerは自動カスケードに任せる
+    }
+}
+```
+
+### 循環参照の安全な解決
+```nyash
+box Node {
+    init { data, weak parent, children }
+    
+    pack(value) {
+        me.data = value
+        me.children = new ArrayBox()
+    }
+    
+    addChild(child) {
+        me.children.push(child)
+        child.setParent(me)  // 子→親はweak参照
+    }
+    
+    fini() {
+        // 子ノードを先に解放
+        loop (me.children.length() > 0) {
+            local child = me.children.pop()
+            child.fini()
+        }
+        // 親への参照は自動的にnil化される
+    }
+}
+```
+
+## 🧪 テストパターン
+
+### 基本動作テスト
+```nyash
+box Counter {
+    init { value }
+    pack() { me.value = 0 }
+    increment() { me.value = me.value + 1 }
+    fini() { print("Counter finalized with value: " + me.value.toString()) }
+}
+
+local c = new Counter()
+c.increment()
+c.increment()
+c.fini()
+// c.increment()  // → エラー: finalized後の使用禁止
+```
+
+### 循環参照テスト
+```nyash
+box Parent {
+    init { child }
+    pack() {
+        me.child = new Child()
+        me.child.setParent(me)
+    }
+    fini() { print("Parent finalized") }
+}
+
+box Child {
+    init { weak parent }
+    setParent(p) { me.parent = p }
+    fini() { print("Child finalized") }
+}
+
+local p = new Parent()
+p.fini()  // Parent → Child の順で解放、リークなし
+```
+
+## 🎯 期待される効果
+
+### メモリ安全性
+- **循環参照リーク完全防止**: weak参照とfiniの組み合わせ
+- **二重解放防止**: idempotentな設計
+- **使用禁止ガード**: finalized後の誤用防止
+
+### 予測可能性
+- **決定的順序**: init宣言順による自動カスケード
+- **明示的制御**: ユーザー定義fini()での柔軟な順序指定
+- **エラーメッセージ**: 明確で修正提案付きのエラー
+
+### 開発体験
+- **直感的**: リソースの「終了宣言」として理解しやすい
+- **デバッグ容易**: 解放タイミングが明確
+- **保守性**: 依存関係の変更に強い設計
+
+## 📚 関連ドキュメント
+
+- [weak参照設計](weak-reference-design.md) - 循環参照解決との統合
+- [Everything is Box](design-philosophy.md) - 基本設計思想
+- [言語リファレンス](language-reference.md) - 構文詳細
+
+---
+
+**Everything is Box, Everything is Finalized!** 🔥