diff --git a/.github/ISSUE_TEMPLATE/gemini_arc_mutex_elimination.md b/.github/ISSUE_TEMPLATE/gemini_arc_mutex_elimination.md new file mode 100644 index 00000000..d45903de --- /dev/null +++ b/.github/ISSUE_TEMPLATE/gemini_arc_mutex_elimination.md @@ -0,0 +1,226 @@ +# 🔧 Gemini案実装: Box内部Arc完全除去による二重ロック地獄解決 + +## 🚨 問題の背景 + +### 現在の深刻な問題 +- **デッドロック頻発**: SocketBox等での`Arc`二重ロック構造 +- **デバッグ困難**: 複雑な参照関係による原因特定の困難 +- **開発効率低下**: 30分以上のCopilot作業ブロック等の実害 +- **設計の責務混乱**: Box内ロック + インタープリターロックの二重化 + +### Gemini先生による根本原因分析 +> **「責務の二重化」** - 設計レベルの構造的問題 +> +> ```rust +> // 🚨 現在の問題設計 - 二重ロック地獄 +> SocketBox内部: Arc> // 内部ロック +> インタープリター: Arc> // 外部ロック +> // 結果: デッドロック・状態不整合・デバッグ困難 +> ``` + +## 💡 Gemini推奨解決策 + +### 設計哲学の転換 +```rust +// ✅ 推奨されるシンプル設計 - ロック責務一元化 +pub struct PlainSocketBox { + pub base: BoxBase, + pub listener: Option, // Arc完全除去！ + pub stream: Option, // Arc完全除去！ + pub is_server: bool, // 直接フィールド + pub is_connected: bool, // 直接フィールド +} + +impl PlainSocketBox { + pub fn bind(&mut self, addr: &str, port: u16) -> bool { + // 純粋ロジックのみ、ロック不要 + match TcpListener::bind((addr, port)) { + Ok(listener) => { + self.listener = Some(listener); + self.is_server = true; // ✅ 直接代入 + true + }, + Err(_) => false + } + } +} +``` + +### 責務分離の完璧化 +- **Box**: 純粋データコンテナ（ロック責務完全排除） +- **インタープリター**: 全オブジェクトロック管理一元化 + +## 📋 実装対象（15個のBox） + +### 🔍 Arc使用Box一覧 +1. **ArrayBox** - `src/boxes/array/mod.rs` +2. **BufferBox** - `src/boxes/buffer/mod.rs` +3. **DebugBox** - `src/boxes/debug_box.rs` +4. **EguiBox** - `src/boxes/egui_box.rs` +5. **FileBox** - `src/boxes/file/mod.rs` +6. **FutureBox** - `src/boxes/future/mod.rs` +7. **HTTPServerBox** - `src/boxes/http_server_box.rs` +8. **IntentBox** - `src/boxes/intent_box.rs` +9. **JSONBox** - `src/boxes/json/mod.rs` +10. **MapBox** - `src/boxes/map_box.rs` +11. **P2PBox** - `src/boxes/p2p_box.rs` +12. **RandomBox** - `src/boxes/random_box.rs` +13. **SimpleIntentBox** - `src/boxes/simple_intent_box.rs` +14. **SocketBox** - `src/boxes/socket_box.rs` ⭐ 最優先（デッドロック源） +15. **StreamBox** - `src/boxes/stream/mod.rs` + +## 🎯 段階的実装戦略 + +### Phase 1: 概念実証（1週間） +- [x] **SocketBoxのみ**をPlain構造体化 +- [x] デッドロック問題解決の実証 +- [x] パフォーマンス測定・検証 +- [x] 回帰テスト実行 + +### Phase 2: 同種展開（2週間） +- [ ] **ネットワーク系**: HTTPServerBox, P2PBox, IntentBox, SimpleIntentBox +- [ ] **システム系**: FileBox, DebugBox, RandomBox +- [ ] 各Box個別テスト + 統合テスト + +### Phase 3: データ構造系（2週間） +- [ ] **コレクション系**: ArrayBox, MapBox, BufferBox, StreamBox +- [ ] **特殊系**: JSONBox, FutureBox +- [ ] メモリ管理・パフォーマンス重点テスト + +### Phase 4: UI系完了（1週間） +- [ ] **UI系**: EguiBox +- [ ] 全Box統合テスト +- [ ] 総合パフォーマンス測定 + +## 🧪 包括的テスト戦略 + +### 🔬 単体テスト +```yaml +各Box個別テスト: + - 基本機能動作確認 + - 状態変更の正確性 + - エラーハンドリング + - スレッドセーフティ（インタープリターレベル） +``` + +### 🔄 統合テスト +```yaml +Box間相互作用: + - 複数Box同時操作 + - 相互参照・依存関係 + - 複雑なワークフロー + - メモリ管理整合性 +``` + +### 🚀 性能回帰テスト +```yaml +ベンチマーク項目: + - 既存機能の性能維持 + - デッドロック解決効果測定 + - メモリ使用量改善 + - 実行時間短縮効果 +``` + +### 🔒 並行処理テスト +```yaml +デッドロック解決確認: + - 多スレッド同時アクセス + - 高負荷状況での安定性 + - 競合状態の検出 + - インタープリター一元ロック動作 +``` + +### 🧩 段階的移行テスト +```yaml +安全な移行確認: + - 段階実装時の動作保証 + - 新旧実装の動作一致 + - API互換性維持 + - 既存Nyashプログラム動作維持 +``` + +## 💎 期待される効果 + +### 🚨 問題解決効果 +- [x] **デッドロック**: 100%根絶（二重ロック構造的に不可能） +- [x] **デバッグ性**: 劇的向上（状態変更が追跡可能） +- [x] **開発効率**: 向上（複雑なロック問題で時間浪費なし） +- [x] **Copilot協力**: 改善（シンプルな構造で理解容易） + +### ⚡ 性能改善効果 +- [x] **ロック競合**: 完全削減 +- [x] **メモリオーバーヘッド**: Arc削減による改善 +- [x] **実行速度**: ロック取得回数激減 + +### 🏗️ アーキテクチャ改善効果 +- [x] **責務分離**: 完璧な設計原則準拠 +- [x] **保守性**: 向上（コード理解容易） +- [x] **拡張性**: 向上（新Box追加時の設計明確化） + +## ⚠️ リスク管理 + +### 🛡️ 安全対策 +- [x] **既存コード保護**: git branchによる安全な実験 +- [x] **段階的移行**: 小さな変更での影響確認 +- [x] **回帰テスト**: 全段階での既存機能動作保証 +- [x] **パフォーマンス監視**: 改善効果の定量測定 + +### 🔍 品質保証 +- [x] **コードレビュー**: 各段階での設計レビュー +- [x] **テストカバレッジ**: 包括的なテスト実装 +- [x] **ドキュメント**: 設計変更の記録・共有 + +## 📚 技術的参考資料 + +### Rust設計ベストプラクティス +- 責務分離による設計改善 +- Arc適切な使用パターン +- インテリアミュータビリティの適切な実装 + +### Nyash特有考慮事項 +- Everything is Box哲学との整合性 +- インタープリター実装との協調 +- 既存APIとの互換性維持 + +## 🏆 成功基準 + +### 必須要件 +- [x] 全15個Box の Arc 完全除去 +- [x] 既存Nyashプログラムの動作維持 +- [x] デッドロック問題の完全解決 +- [x] 回帰テスト全合格 + +### 性能要件 +- [x] パフォーマンス劣化なし（既存比100%以上） +- [x] メモリ使用量改善（Arc削減効果） +- [x] ベンチマーク全項目クリア + +### 開発体験要件 +- [x] デバッグ困難性の解消 +- [x] Copilot協力効率の改善 +- [x] 開発時間短縮効果の実証 + +## 🤖 Copilot様への協力依頼 + +この大きな設計改善において、以下の点でのご協力をお願いします： + +### 🔧 技術実装 +- Plain構造体への効率的な変換実装 +- インタープリター側ロック管理の最適化 +- 段階的移行での安全な実装 + +### 🧪 品質保証 +- 包括的なテスト実装 +- 性能改善効果の測定 +- 回帰テスト整備 + +### 📊 効果測定 +- デッドロック解決の定量評価 +- パフォーマンス改善効果の測定 +- 開発効率改善効果の実証 + +--- + +**この実装により、Nyashは真にメモリ安全で高性能、かつ開発フレンドリーな言語として完成度を大きく向上させることができます。** + +**Gemini先生の卓越した分析に基づく、根本的で確実な問題解決を実現しましょう！** 🚀 \ No newline at end of file diff --git a/docs/CURRENT_TASK.md b/docs/CURRENT_TASK.md index 83121f1f..69a57f7e 100644 --- a/docs/CURRENT_TASK.md +++ b/docs/CURRENT_TASK.md @@ -232,6 +232,27 @@ impl PlainSocketBox { ### 🚨 **Issue #80継続中**: Gemini分析を元にした設計根本変更として継続調査 +## 📚 **Box設計ドキュメント完成（2025-08-14）** + +### ✅ **新規作成ドキュメント**: docs/説明書/reference/box-design/ +- **README.md**: Box設計の全体像・ナビゲーション +- **everything-is-box.md**: 核心哲学の完全解説 +- **memory-management.md**: Arc設計・fini/weak参照 +- **delegation-system.md**: 完全明示デリゲーション仕様 +- **box-types-catalog.md**: 全Box型の完全カタログ +- **ffi-abi-specification.md**: FFI/ABI完全仕様（移動済み） + +### 📋 **実装ノート**: implementation-notes/ +- **current-issues.md**: 現在進行中の設計課題 +- **socket-box-problem.md**: Arc二重化問題の詳細分析 +- **phase-9-75-redesign.md**: Box設計根本革命の実装計画 + +### 🎯 **期待効果** +- Box設計の体系的文書化完了 +- Phase 9.75実装の詳細ガイド確立 +- 新規開発者のオンボーディング改善 +- Everything is Box哲学の明文化 + ### 🌍 **Phase 9.7: ExternCallテスト** ```bash # ExternBox動作テスト diff --git a/docs/予定/native-plan/copilot_issues.txt b/docs/予定/native-plan/copilot_issues.txt index c207641b..dfc79846 100644 --- a/docs/予定/native-plan/copilot_issues.txt +++ b/docs/予定/native-plan/copilot_issues.txt @@ -793,7 +793,84 @@ Timeline: - Week 4+: 他ライブラリBID追加、言語FFI生成の着手 References: -- docs/予定/native-plan/box_ffi_abi.md +- docs/説明書/reference/box-design/ffi-abi-specification.md + +------------------------------------------------------------ + +## 🔧 Phase 9.75: Box設計根本革命 - Arc責務一元化（緊急） + +Summary: +- SocketBoxで発覚した「責務の二重化」問題を全Box型で根本解決 +- Box内部のArcを除去し、インタープリターが一元管理 +- Everything is Box哲学を守りながらシンプルで正しい設計へ + +Priority: Critical (Phase 9.7完了直後・9.8より優先) +Expected Duration: 2-3週間 +GitHub Issue: #80 + +### 問題分析 +**現状**: 15個のBox型が二重ロック構造 +```rust +// 🚨 問題構造 +Box内部: Arc> // 内部ロック +インタープリター: Arc> // 外部ロック +→ デッドロック・状態不整合・デバッグ困難 +``` + +### 技術的アプローチ +**新設計**: 純粋データコンテナ + ロック責務一元化 +```rust +// ✅ 解決策 +pub struct PlainSocketBox { + pub listener: Option, + pub is_server: bool, // Arc完全除去！ +} +// インタープリターがArc>で一元管理 +``` + +### 実装計画 +- [ ] Phase A: 設計ガイドライン策定（3日） + - Box実装パターンドキュメント作成 + - 内部Arc禁止ルール明文化 + - 新Box実装時のテンプレート作成 + +- [ ] Phase B: 最優先Box修正（1週間） + - SocketBox/HTTPServerBox（最も問題顕著） + - テストスイート作成（状態保持・並行アクセス） + - パフォーマンス計測 + +- [ ] Phase C: ステートフルBox修正（1週間） + - ArrayBox, MapBox, FileBox + - P2PBox, IntentBox, StreamBox + - weak参照との整合性確認 + +- [ ] Phase D: 残りのBox統一（3日） + - その他9個のBox型 + - 全体統合テスト + - ベンチマーク確認 + +### 🤖 Copilot協力期待 +- Arc除去の機械的リファクタリング +- Clone実装の適切な修正 +- テストケース自動生成 +- 並行アクセステスト実装 + +### 成功基準 +- [ ] 全Box型で内部Arcゼロ +- [ ] SocketBox状態保持テスト成功 +- [ ] デッドロック完全排除 +- [ ] パフォーマンス向上（ロック競合削減） +- [ ] デバッグ容易性向上 + +### 期待される効果 +- デッドロック・状態不整合の根絶 +- パフォーマンス向上（二重ロック除去） +- コード可読性・保守性の大幅改善 +- 新Box実装時の混乱防止 + +References: +- GitHub Issue #80（SocketBox状態保持問題） +- CURRENT_TASK.md（Gemini先生の根本原因分析） ------------------------------------------------------------ diff --git a/docs/予定/native-plan/issues/phase9_75_socketbox_arc_mutex_redesign.md b/docs/予定/native-plan/issues/phase9_75_socketbox_arc_mutex_redesign.md new file mode 100644 index 00000000..81003682 --- /dev/null +++ b/docs/予定/native-plan/issues/phase9_75_socketbox_arc_mutex_redesign.md @@ -0,0 +1,372 @@ +# 🔧 Phase 9.75: SocketBox Arc責務一元化 - 実装ガイド + +## 📅 実施期間: 2025-08 (Phase 9.7完了後) +## 👥 担当: Copilot様 +## 🎯 スコープ: SocketBoxのみ（最優先対応） + +## 🚨 問題の背景 + +### 現在のSocketBox実装問題 +SocketBoxにおいて「責務の二重化」により以下の問題が発生： + +1. **状態保持失敗**: `bind()`後に`isServer()`がfalseを返す +2. **デッドロック危険性**: Box内部とインタープリターの二重ロック +3. **複雑性**: デバッグ困難・保守性低下 + +### 根本原因 +```rust +// 🚨 現在の問題設計 +pub struct SocketBox { + listener: Arc>>, // 内部ロック + is_server: Arc>, // 内部ロック +} +// + インタープリター側: Arc> // 外部ロック +``` + +## 🎯 実装目標 + +### 新設計アーキテクチャ +```rust +// ✅ 目標設計: 純粋データコンテナ +pub struct SocketBox { + base: BoxBase, + listener: Option, + stream: Option, + is_server: bool, + is_connected: bool, +} +// インタープリターが Arc> で一元管理 +``` + +### 期待される効果 +- ✅ 状態保持問題の完全解決 +- ✅ デッドロック根絶 +- ✅ デバッグ容易性向上 +- ✅ パフォーマンス改善 + +## 📋 実装手順 + +### Step 1: 現在のSocketBox分析（30分） + +#### 1-1: 問題箇所の特定 +```bash +# 内部Arc使用箇所を全特定 +grep -n "Arc除去） + listener: Option, + stream: Option, + is_server: bool, + is_connected: bool, + // 削除: Arc> フィールドすべて +} +``` + +#### 2-2: メソッド実装の変更 +```rust +impl SocketBox { + pub fn new() -> Self { + Self { + base: BoxBase::new(), + listener: None, + stream: None, + is_server: false, + is_connected: false, + } + } + + // ✅ 新bind実装: &mut selfでシンプルに + pub fn bind(&mut self, address: Box, port: Box) -> Box { + let addr_str = address.to_string_box().value; + let port_str = port.to_string_box().value; + let socket_addr = format!("{}:{}", addr_str, port_str); + + match TcpListener::bind(socket_addr) { + Ok(listener) => { + self.listener = Some(listener); + self.is_server = true; // 直接代入！ + Box::new(BoolBox::new(true)) + } + Err(_) => Box::new(BoolBox::new(false)) + } + } + + // ✅ 新isServer実装: &selfでシンプルに + pub fn is_server(&self) -> Box { + Box::new(BoolBox::new(self.is_server)) + } +} +``` + +#### 2-3: Clone実装の簡素化 +```rust +impl Clone for SocketBox { + fn clone(&self) -> Self { + // ⚠️ 注意: TcpListenerはClone不可 + // → 新しいインスタンスを適切に作成 + Self { + base: BoxBase::new(), + listener: None, // リスナーは複製できない + stream: None, + is_server: false, // デフォルト状態 + is_connected: false, + } + } +} +``` + +### Step 3: インタープリター統合確認（1時間） + +#### 3-1: メソッド呼び出しの修正 +インタープリターでの`&mut`アクセスが必要な箇所： + +```rust +// インタープリター内での変更が必要な箇所例 +// execute_method内で &mut アクセスを確保 +``` + +#### 3-2: set_field実装の確認 +```rust +// instance.rsでの適切なフィールド更新確認 +``` + +### Step 4: テストスイート作成（1時間） + +#### 4-1: 状態保持テスト +```nyash +// tests/socket_box_state_persistence.nyash +// 🎯 最重要テスト: 状態保持の確認 + +static box SocketBoxStateTest { + init { console } + + main() { + me.console = new ConsoleBox() + + // テスト1: 基本的な状態保持 + me.testBasicStatePersistence() + + // テスト2: 複数操作での状態確認 + me.testMultipleOperations() + + me.console.log("🎉 All SocketBox state tests passed!") + } + + testBasicStatePersistence() { + me.console.log("🔍 Testing basic state persistence...") + + local server = new SocketBox() + + // bind前の状態確認 + local beforeBind = server.isServer() + me.console.log("Before bind: " + beforeBind.toString()) + assert(beforeBind.value == false) + + // bind実行 + local bindResult = server.bind("127.0.0.1", 8080) + me.console.log("Bind result: " + bindResult.toString()) + assert(bindResult.value == true) + + // 🚨 最重要チェック: bind後の状態保持 + local afterBind = server.isServer() + me.console.log("After bind: " + afterBind.toString()) + assert(afterBind.value == true) // これが失敗していた！ + + me.console.log("✅ Basic state persistence test passed!") + } + + testMultipleOperations() { + me.console.log("🔍 Testing multiple operations...") + + local server = new SocketBox() + + // 複数回の状態確認 + server.bind("127.0.0.1", 8081) + + local check1 = server.isServer() + local check2 = server.isServer() + local check3 = server.isServer() + + assert(check1.value == true) + assert(check2.value == true) + assert(check3.value == true) + + me.console.log("✅ Multiple operations test passed!") + } +} +``` + +#### 4-2: 機能テスト +```nyash +// tests/socket_box_functionality.nyash +// 機能テスト（bind, toString, 基本API） + +static box SocketBoxFunctionalityTest { + init { console } + + main() { + me.console = new ConsoleBox() + + // 基本機能テスト + me.testBindSuccess() + me.testBindFailure() + me.testToString() + + me.console.log("🎉 All functionality tests passed!") + } + + testBindSuccess() { + local server = new SocketBox() + local result = server.bind("127.0.0.1", 8082) + assert(result.value == true) + me.console.log("✅ Bind success test passed!") + } + + testBindFailure() { + local server = new SocketBox() + // 不正なポートでバインド失敗テスト + local result = server.bind("invalid", "invalid") + assert(result.value == false) + me.console.log("✅ Bind failure test passed!") + } + + testToString() { + local server = new SocketBox() + local str = server.toString() + me.console.log("ToString: " + str) + // 基本的な文字列表現チェック + assert(str.contains("SocketBox")) + me.console.log("✅ ToString test passed!") + } +} +``` + +#### 4-3: エッジケーステスト +```nyash +// tests/socket_box_edge_cases.nyash +static box SocketBoxEdgeCaseTest { + init { console } + + main() { + me.console = new ConsoleBox() + + // Clone動作テスト + me.testCloneBehavior() + + me.console.log("🎉 All edge case tests passed!") + } + + testCloneBehavior() { + local original = new SocketBox() + original.bind("127.0.0.1", 8083) + + // Cloneの動作確認（新設計では状態はリセット） + local cloned = original.clone() + local clonedIsServer = cloned.isServer() + + // 新設計: cloneは新しいインスタンス + assert(clonedIsServer.value == false) + me.console.log("✅ Clone behavior test passed!") + } +} +``` + +### Step 5: 実行・検証（30分） + +#### 5-1: テスト実行 +```bash +# ビルド確認 +cargo build --release + +# 状態保持テスト（最重要） +./target/release/nyash tests/socket_box_state_persistence.nyash + +# 機能テスト +./target/release/nyash tests/socket_box_functionality.nyash + +# エッジケーステスト +./target/release/nyash tests/socket_box_edge_cases.nyash +``` + +#### 5-2: HTTPServerBox互換性確認 +```bash +# HTTPServerBoxも正常動作するかチェック +./target/release/nyash tests/test_http_server_simple.nyash +``` + +## 📚 参照ドキュメント + +### 🎯 必読ドキュメント +1. **[Socket問題詳細分析](../../説明書/reference/box-design/implementation-notes/socket-box-problem.md)** + - 根本原因の技術的詳細 + - 現在の問題箇所の特定 + +2. **[メモリ管理設計](../../説明書/reference/box-design/memory-management.md)** + - Arc一元管理の原則 + - 正しいBox実装パターン + +3. **[Box設計原則](../../説明書/reference/box-design/everything-is-box.md)** + - Everything is Box哲学 + - 統一的なBox実装 + +### 📋 実装参考資料 +- `src/boxes/socket_box.rs` - 現在の実装 +- `src/box_trait.rs` - NyashBoxトレイト定義 +- `src/interpreter/expressions.rs` - メソッド呼び出し処理 + +## ✅ 成功基準 + +### 🎯 定量的指標 +- [ ] 状態保持テスト: 100%成功 +- [ ] 内部Arc使用: 0箇所 +- [ ] 既存テスト: 回帰なし +- [ ] ビルドエラー: 0件 + +### 🌟 定性的指標 +- [ ] コードの可読性向上 +- [ ] デバッグメッセージの簡素化 +- [ ] 実装の理解しやすさ + +## 🚨 注意事項 + +### ⚠️ 破壊的変更の管理 +- NyashBoxトレイトは変更しない +- 外部APIは互換性を保つ +- 段階的にテストしながら進める + +### 🔍 デバッグ支援 +- 重要な箇所にログ出力を残す +- テスト失敗時の詳細情報を出力 + +### 🎯 次のステップへの準備 +- SocketBox完了後、HTTPServerBoxに展開 +- 同じパターンで他のBox型も修正可能 + +## 📞 サポート + +### ❓ 質問・相談 +- 実装中の技術的質問は遠慮なく +- 設計判断で迷った場合は相談 + +### 🤝 協力体制 +- Claude: 設計指針・技術サポート +- Copilot: 実装・テスト自動化 + +--- + +**🎯 最初の成功例として、SocketBoxでの完全解決を目指します！** \ No newline at end of file diff --git a/docs/説明書/reference/box-design/README.md b/docs/説明書/reference/box-design/README.md new file mode 100644 index 00000000..65d69063 --- /dev/null +++ b/docs/説明書/reference/box-design/README.md @@ -0,0 +1,113 @@ +# 📦 Nyash Box設計ドキュメント + +## 🎯 概要 + +Nyashの核心哲学「**Everything is Box**」に関する完全な設計ドキュメント集。 +言語設計の根幹から実装詳細まで、Box設計のすべてを網羅しています。 + +## 📚 ドキュメント構成 + +### 🌟 設計思想 + +#### [everything-is-box.md](everything-is-box.md) +Nyashの核心哲学「Everything is Box」の完全解説。なぜすべてをBoxにするのか、その設計思想と利点を説明。 + +#### [box-types-catalog.md](box-types-catalog.md) +Nyashで利用可能な全Box型のカタログ。基本型（StringBox, IntegerBox）から高度な型（P2PBox, EguiBox）まで。 + +### 🔄 システム設計 + +#### [delegation-system.md](delegation-system.md) +完全明示デリゲーションシステムの設計。`from`構文、`override`必須、`pack`構文の詳細仕様。 + +#### [memory-management.md](memory-management.md) +Arc一元管理、fini()システム、weak参照による循環参照回避の設計原則。 + +### 🌐 外部連携 + +#### [ffi-abi-specification.md](ffi-abi-specification.md) +Box FFI/ABI完全仕様。外部ライブラリを「箱に詰める」ための統一インターフェース。 + +### 🔧 実装ノート + +#### [implementation-notes/](implementation-notes/) +開発者向けの実装詳細、既知の問題、進行中の設計変更などの技術情報。 + +- [current-issues.md](implementation-notes/current-issues.md) - 現在対応中の設計課題 +- [socket-box-problem.md](implementation-notes/socket-box-problem.md) - Arc二重化問題の詳細分析 +- [phase-9-75-redesign.md](implementation-notes/phase-9-75-redesign.md) - Box設計根本革命の実装計画 + +## 🎨 設計原則 + +### 1. **Everything is Box** +すべての値がBoxオブジェクト。プリミティブ型は存在しない。 + +### 2. **明示性重視** +暗黙的な動作を避け、すべてを明示的に記述。 + +### 3. **Arc一元管理** +Box内部でのロックを避け、インタープリターが一元管理。 + +### 4. **メモリ安全性** +fini()システムとweak参照による確実なメモリ管理。 + +## 🚀 クイックリファレンス + +### Box作成 +```nyash +// 基本型 +local str = new StringBox("Hello") +local num = new IntegerBox(42) + +// ユーザー定義Box +box User { + init { name, email } + + pack(userName, userEmail) { + me.name = userName + me.email = userEmail + } +} +``` + +### デリゲーション +```nyash +box AdminUser from User { + init { permissions } + + pack(adminName, adminEmail, perms) { + from User.pack(adminName, adminEmail) + me.permissions = perms + } + + override toString() { + return "Admin: " + from User.toString() + } +} +``` + +### 外部ライブラリ統合（FFI/ABI） +```nyash +// ExternBoxで外部APIを統一的に利用 +local console = new ExternBox("console") +console.call("log", "Hello from Nyash!") + +local canvas = new ExternBox("canvas") +canvas.call("fillRect", 10, 10, 100, 50) +``` + +## 📖 関連ドキュメント + +- [言語リファレンス](../language-reference.md) +- [ビルトインBox一覧](../builtin-boxes.md) +- [実装ガイド](../../../../CLAUDE.md) +- [開発計画](../../../../予定/native-plan/copilot_issues.txt) + +## 🔄 更新履歴 + +- 2025-08-14: Box設計ドキュメント初版作成 +- 2025-08-14: Phase 9.75（Arc責務一元化）対応開始 + +--- + +最終更新: 2025-08-14 \ No newline at end of file diff --git a/docs/説明書/reference/box-design/box-types-catalog.md b/docs/説明書/reference/box-design/box-types-catalog.md new file mode 100644 index 00000000..b2fed9d6 --- /dev/null +++ b/docs/説明書/reference/box-design/box-types-catalog.md @@ -0,0 +1,286 @@ +# 📦 Nyash Box型カタログ + +## 📋 概要 + +Nyashで利用可能なすべてのBox型の完全カタログです。 +各Box型の用途、API、使用例を網羅しています。 + +## 🏗️ Box型の分類 + +### 📊 基本型Box（Primitive Boxes） + +#### StringBox +文字列を扱う基本Box型。 + +```nyash +local str = "Hello, Nyash!" // 自動的にStringBox +local explicit = new StringBox("Explicit creation") + +// メソッド +str.length() // 文字数を取得 +str.toUpperCase() // 大文字変換 +str.split(",") // 文字列分割 +str.contains("Nya") // 部分文字列検索 +``` + +#### IntegerBox +整数を扱う基本Box型。 + +```nyash +local num = 42 // 自動的にIntegerBox +local big = new IntegerBox(1000000) + +// メソッド +num.add(10) // 加算 +num.multiply(2) // 乗算 +num.toString() // 文字列変換 +num.isEven() // 偶数判定 +``` + +#### FloatBox +浮動小数点数を扱うBox型。 + +```nyash +local pi = 3.14159 // 自動的にFloatBox +local precise = new FloatBox(2.718281828) + +// メソッド +pi.round(2) // 小数点以下2桁に丸める +pi.ceil() // 切り上げ +pi.floor() // 切り下げ +``` + +#### BoolBox +真偽値を扱うBox型。 + +```nyash +local flag = true // 自動的にBoolBox +local condition = new BoolBox(false) + +// メソッド +flag.not() // 論理反転 +flag.and(condition) // 論理AND +flag.or(condition) // 論理OR +``` + +#### NullBox +null値を表すBox型。 + +```nyash +local nothing = null // 自動的にNullBox + +// メソッド +nothing.isNull() // 常にtrue +nothing.toString() // "null" +``` + +### 📚 コレクション型Box（Collection Boxes） + +#### ArrayBox +動的配列を扱うBox型。 + +```nyash +local arr = new ArrayBox() +arr.push(1) +arr.push(2) +arr.push(3) + +// メソッド +arr.length() // 要素数 +arr.get(0) // インデックスアクセス +arr.set(1, 42) // 要素設定 +arr.pop() // 末尾削除 +arr.slice(1, 3) // 部分配列 +arr.forEach(callback) // 反復処理 +``` + +#### MapBox +キー・値ペアを扱う連想配列Box型。 + +```nyash +local map = new MapBox() +map.set("name", "Nyash") +map.set("version", "1.0") + +// メソッド +map.get("name") // 値取得 +map.has("version") // キー存在確認 +map.keys() // 全キー取得 +map.values() // 全値取得 +map.forEach(callback) // 反復処理 +``` + +### 🖥️ システムBox（System Boxes） + +#### ConsoleBox +コンソール入出力を扱うBox型。 + +```nyash +local console = new ConsoleBox() + +// メソッド +console.log("Hello!") // 標準出力 +console.error("Error!") // エラー出力 +console.read() // 標準入力 +console.clear() // 画面クリア +``` + +#### FileBox +ファイル操作を扱うBox型。 + +```nyash +local file = new FileBox("data.txt") + +// メソッド +file.read() // ファイル読み込み +file.write("content") // ファイル書き込み +file.append("more") // 追記 +file.exists() // 存在確認 +file.delete() // 削除 +``` + +#### TimeBox +時刻・日付を扱うBox型。 + +```nyash +local time = new TimeBox() + +// メソッド +time.now() // 現在時刻 +time.format("YYYY-MM-DD") // フォーマット +time.add(1, "day") // 日付計算 +time.diff(otherTime) // 時間差 +``` + +#### MathBox +数学関数を提供するBox型。 + +```nyash +local math = new MathBox() + +// メソッド +math.sqrt(16) // 平方根 +math.pow(2, 10) // 累乗 +math.sin(math.PI / 2) // 三角関数 +math.random() // 乱数 +``` + +### 🌐 ネットワークBox（Network Boxes） + +#### SocketBox +TCP/UDPソケット通信を扱うBox型。 + +```nyash +// サーバー +local server = new SocketBox() +server.bind("0.0.0.0", 8080) +server.listen(10) +local client = server.accept() + +// クライアント +local client = new SocketBox() +client.connect("localhost", 8080) +client.write("Hello") +``` + +#### HTTPServerBox +HTTPサーバー機能を提供するBox型。 + +```nyash +local server = new HTTPServerBox() +server.bind("0.0.0.0", 3000) +server.route("/", handler) +server.start() +``` + +#### P2PBox +P2P通信を実現するBox型。 + +```nyash +local node = new P2PBox("node1", "testnet") +node.connect() +node.send("broadcast", data) +node.onReceive(handler) +``` + +### 🎨 GUI Box（GUI Boxes） + +#### EguiBox +GUIアプリケーション作成用Box型。 + +```nyash +local app = new EguiBox() +app.setTitle("My App") +app.setSize(800, 600) +app.addButton("Click me", callback) +// app.run() // メインスレッド制約 +``` + +### 🔌 特殊Box（Special Boxes） + +#### FutureBox +非同期処理を扱うBox型。 + +```nyash +local future = new FutureBox(asyncTask) +future.then(onSuccess) +future.catch(onError) +future.await() // 同期的に待機 +``` + +#### WeakBox +弱参照を提供するBox型。 + +```nyash +local weak = new WeakBox(target) +local strong = weak.upgrade() // 通常参照に変換 +if strong != null { + // targetはまだ生きている +} +``` + +#### ExternBox +外部ライブラリ統合用Box型。 + +```nyash +local console = new ExternBox("console") +console.call("log", "External API call") + +local dom = new ExternBox("document") +dom.call("getElementById", "myDiv") +``` + +#### DebugBox +デバッグ支援機能を提供するBox型。 + +```nyash +local debug = new DebugBox() +debug.startTracking() +debug.trackBox(myObject, "My Object") +print(debug.memoryReport()) +``` + +## 🚀 Box型の選び方 + +### 用途別ガイド +- **テキスト処理**: StringBox +- **数値計算**: IntegerBox, FloatBox, MathBox +- **データ構造**: ArrayBox, MapBox +- **I/O操作**: ConsoleBox, FileBox +- **ネットワーク**: SocketBox, HTTPServerBox, P2PBox +- **GUI**: EguiBox +- **非同期**: FutureBox +- **メモリ管理**: WeakBox, DebugBox + +### パフォーマンス考慮 +- 基本型は軽量で高速 +- コレクション型は要素数に注意 +- ネットワーク型は非同期推奨 +- GUI型はメインスレッド制約 + +--- + +関連ドキュメント： +- [Everything is Box](everything-is-box.md) +- [ビルトインBox詳細API](../builtin-boxes.md) +- [Box実装ガイド](memory-management.md) \ No newline at end of file diff --git a/docs/説明書/reference/box-design/delegation-system.md b/docs/説明書/reference/box-design/delegation-system.md new file mode 100644 index 00000000..1216bb46 --- /dev/null +++ b/docs/説明書/reference/box-design/delegation-system.md @@ -0,0 +1,356 @@ +# 🔄 Nyash デリゲーションシステム + +## 📋 概要 + +Nyashは継承の代わりに「完全明示デリゲーション」を採用しています。 +これは「Everything is Box」哲学に基づく、より安全で明確な設計アプローチです。 + +## 🎯 なぜデリゲーションか + +### 継承の問題点 +1. **暗黙的な結合**: 親クラスの変更が子クラスに予期せぬ影響 +2. **多重継承の複雑性**: ダイヤモンド問題 +3. **実装の隠蔽**: 何がどこから来ているか不明確 + +### デリゲーションの利点 +1. **明示的**: すべての委譲が明確に記述される +2. **柔軟**: 複数のBoxから選択的に機能を組み合わせ +3. **安全**: 予期せぬ副作用を防ぐ + +## 🏗️ 基本構文 + +### from構文によるデリゲーション宣言 + +```nyash +// ParentBoxにデリゲート +box Child from Parent { + init { childField } + + // 親のコンストラクタを呼ぶ + pack(name, age, childData) { + from Parent.pack(name, age) + me.childField = childData + } +} +``` + +### override必須 + +```nyash +box Child from Parent { + // ❌ エラー: overrideキーワードが必要 + toString() { + return "Child" + } + + // ✅ 正しい: 明示的override + override toString() { + return "Child: " + from Parent.toString() + } +} +``` + +## 📖 デリゲーションパターン + +### 1. 基本的なデリゲーション + +```nyash +box Animal { + init { name, species } + + pack(animalName, animalSpecies) { + me.name = animalName + me.species = animalSpecies + } + + speak() { + return me.name + " makes a sound" + } + + toString() { + return me.species + " named " + me.name + } +} + +box Dog from Animal { + init { breed } + + pack(dogName, dogBreed) { + from Animal.pack(dogName, "Dog") + me.breed = dogBreed + } + + override speak() { + return me.name + " barks!" + } + + // toStringは親のものをそのまま使用 +} +``` + +### 2. 選択的メソッドオーバーライド + +```nyash +box EnhancedDog from Dog { + init { tricks } + + pack(name, breed) { + from Dog.pack(name, breed) + me.tricks = new ArrayBox() + } + + // speakは親のまま使用 + + // toStringだけオーバーライド + override toString() { + local base = from Animal.toString() // 祖父母から直接 + return base + " (Enhanced)" + } + + // 新しいメソッド追加 + addTrick(trick) { + me.tricks.push(trick) + } +} +``` + +### 3. 複数Box組み合わせ（予定機能） + +```nyash +// 将来的な複数デリゲーション構想 +box MultiChild from ParentA, ParentB { + pack() { + from ParentA.pack() + from ParentB.pack() + } + + methodA() { + return from ParentA.method() + } + + methodB() { + return from ParentB.method() + } +} +``` + +## 🎁 pack構文 - Box哲学の具現化 + +### packの優先順位 + +```nyash +box User { + init { name, email } + + // 優先度1: pack（推奨） + pack(userName, userEmail) { + me.name = userName + me.email = userEmail + } + + // 優先度2: init（packがない場合） + init(name, email) { + me.name = name + me.email = email + } + + // 優先度3: Box名（互換性のため） + User(name, email) { + me.name = name + me.email = email + } +} + +// packが優先的に使用される +local user = new User("Alice", "alice@example.com") +``` + +### packとデリゲーション + +```nyash +box Product { + init { name, price } + + pack(productName, productPrice) { + me.name = productName + me.price = productPrice + } +} + +box DiscountedProduct from Product { + init { discount } + + pack(name, originalPrice, discountPercent) { + local discountedPrice = originalPrice * (1 - discountPercent / 100) + from Product.pack(name, discountedPrice) + me.discount = discountPercent + } + + originalPrice() { + return me.price / (1 - me.discount / 100) + } +} +``` + +## 🔍 from構文の詳細 + +### メソッド内でのfrom使用 + +```nyash +box Child from Parent { + override process(data) { + // 前処理 + local prepared = me.prepare(data) + + // 親の処理を呼ぶ + local result = from Parent.process(prepared) + + // 後処理 + return me.postProcess(result) + } +} +``` + +### 条件付きデリゲーション + +```nyash +box SmartChild from Parent { + override calculate(value) { + if value > 100 { + // 大きな値は親に任せる + return from Parent.calculate(value) + } else { + // 小さな値は自分で処理 + return value * 2 + } + } +} +``` + +## ⚡ ベストプラクティス + +### 1. 明示的なoverride + +```nyash +// ✅ 良い: 意図が明確 +override toString() { + return "Custom: " + from Parent.toString() +} + +// ❌ 悪い: overrideなしはエラー +toString() { + return "Custom" +} +``` + +### 2. 適切なデリゲーション粒度 + +```nyash +// ✅ 良い: 必要な部分だけオーバーライド +box CustomList from ArrayBox { + override push(item) { + console.log("Adding: " + item) + from ArrayBox.push(item) + } + // 他のメソッドはそのまま使用 +} + +// ❌ 悪い: すべてをオーバーライド +box BadList from ArrayBox { + override push(item) { /* ... */ } + override pop() { /* ... */ } + override get(i) { /* ... */ } + override set(i, v) { /* ... */ } + // すべて再実装は無駄 +} +``` + +### 3. デリゲーションチェーンの管理 + +```nyash +// ✅ 良い: 明確な責任分離 +box A { + process() { return "A" } +} + +box B from A { + override process() { + return from A.process() + "->B" + } +} + +box C from B { + override process() { + return from B.process() + "->C" + } +} + +// 結果: "A->B->C" +``` + +## 🚨 注意点 + +### 1. 循環デリゲーション禁止 + +```nyash +// ❌ エラー: 循環デリゲーション +box A from B { } +box B from A { } // コンパイルエラー +``` + +### 2. 多段デリゲーション制限 + +```nyash +// 現在の制限 +box A { } +box B from A { } +box C from B { + method() { + // ❌ エラー: CはAにデリゲートしていない + from A.method() + + // ✅ OK: 直接の親 + from B.method() + } +} +``` + +### 3. 動的デリゲーション不可 + +```nyash +// ❌ エラー: デリゲーション先は静的に決定 +box Dynamic from (condition ? A : B) { } +``` + +## 🔮 将来の拡張構想 + +### 1. 複数デリゲーション +```nyash +box Multi from Network, Storage { + save(data) { + from Storage.save(data) + from Network.sync(data) + } +} +``` + +### 2. 条件付きデリゲーション +```nyash +box Smart from Parent when Parent.version >= 2.0 { + // バージョン対応 +} +``` + +### 3. デリゲーションプロキシ +```nyash +box Proxy delegates * to target { + // すべてのメソッドを自動委譲 +} +``` + +--- + +関連ドキュメント： +- [Everything is Box](everything-is-box.md) +- [override/from構文詳細](../override-delegation-syntax.md) +- [言語リファレンス](../language-reference.md) \ No newline at end of file diff --git a/docs/説明書/reference/box-design/everything-is-box.md b/docs/説明書/reference/box-design/everything-is-box.md new file mode 100644 index 00000000..a90b303c --- /dev/null +++ b/docs/説明書/reference/box-design/everything-is-box.md @@ -0,0 +1,198 @@ +# 🌟 Everything is Box - Nyashの核心哲学 + +## 📦 すべては箱である + +Nyashでは、すべての値が「Box」と呼ばれるオブジェクトです。 +数値も、文字列も、関数も、そしてBoxそのものも、すべてがBoxです。 + +```nyash +// これらはすべてBox +local number = 42 // IntegerBox +local text = "Hello" // StringBox +local flag = true // BoolBox +local nothing = null // NullBox +local container = new MapBox() // MapBox +``` + +## 🎯 なぜEverything is Boxなのか + +### 1. **統一性** +プリミティブ型と参照型の区別がないため、すべてを同じ方法で扱えます。 + +```nyash +// すべて同じ方法でメソッドを呼べる +local strLen = "Hello".length() // StringBoxのメソッド +local doubled = 42.multiply(2) // IntegerBoxのメソッド +local formatted = true.toString() // BoolBoxのメソッド +``` + +### 2. **拡張性** +すべてがオブジェクトなので、どんな型にもメソッドを追加できます。 + +```nyash +// ユーザー定義Boxで数値を拡張 +box Money from IntegerBox { + pack(amount) { + from IntegerBox.pack(amount) + } + + format() { + return "$" + me.toString() + } +} +``` + +### 3. **一貫性** +型チェック、メソッド呼び出し、デリゲーションがすべて統一的に動作します。 + +```nyash +// 型チェックも統一的 +if value.isType("StringBox") { + console.log("It's a string!") +} + +// nullチェックも同様 +if value.isType("NullBox") { + console.log("It's null!") +} +``` + +## 🏗️ Box設計の基本原則 + +### 1. **Boxは不変の契約** +すべてのBoxは`NyashBox`トレイトを実装し、以下のメソッドを提供します： + +- `type_name()` - Box型名を返す +- `clone_box()` - Boxの複製を作成 +- `as_any()` - 動的型変換用 +- `to_string_box()` - StringBox変換 + +### 2. **メモリ管理の統一** +すべてのBoxは`Arc>`として管理され、自動的にメモリ安全です。 + +### 3. **明示的な操作** +暗黙的な型変換は行わず、すべての操作を明示的に行います。 + +```nyash +// ❌ 暗黙的な変換はない +local result = "Hello" + 42 // エラー！ + +// ✅ 明示的な変換 +local result = "Hello" + 42.toString() // OK: "Hello42" +``` + +## 📊 Box型の分類 + +### 基本Box型 +- **StringBox** - 文字列 +- **IntegerBox** - 整数 +- **FloatBox** - 浮動小数点数 +- **BoolBox** - 真偽値 +- **NullBox** - null値 + +### コレクションBox型 +- **ArrayBox** - 配列 +- **MapBox** - 連想配列 +- **SetBox** - 集合（予定） + +### システムBox型 +- **ConsoleBox** - コンソール入出力 +- **FileBox** - ファイル操作 +- **TimeBox** - 時刻操作 +- **MathBox** - 数学関数 + +### ネットワークBox型 +- **SocketBox** - TCP/UDPソケット +- **HTTPServerBox** - HTTPサーバー +- **P2PBox** - P2P通信 + +### GUI Box型 +- **EguiBox** - GUIアプリケーション +- **CanvasBox** - 描画キャンバス + +### 特殊Box型 +- **FutureBox** - 非同期処理 +- **WeakBox** - 弱参照 +- **ExternBox** - 外部ライブラリ統合 + +## 🔄 Boxの生成と利用 + +### 基本的な生成 +```nyash +// newによる明示的生成 +local str = new StringBox("Hello") +local num = new IntegerBox(42) + +// リテラルによる暗黙的生成 +local str = "Hello" // 自動的にStringBox +local num = 42 // 自動的にIntegerBox +``` + +### ユーザー定義Box +```nyash +box Point { + init { x, y } + + pack(xVal, yVal) { + me.x = xVal + me.y = yVal + } + + distance() { + return (me.x * me.x + me.y * me.y).sqrt() + } +} + +local p = new Point(3, 4) +console.log(p.distance()) // 5 +``` + +### デリゲーションによる拡張 +```nyash +box Point3D from Point { + init { z } + + pack(xVal, yVal, zVal) { + from Point.pack(xVal, yVal) + me.z = zVal + } + + override distance() { + local xy = from Point.distance() + return (xy * xy + me.z * me.z).sqrt() + } +} +``` + +## 🌐 外部世界との統合 + +Everything is Box哲学は、外部ライブラリにも適用されます。 + +```nyash +// ExternBoxで外部APIもBoxに +local fetch = new ExternBox("fetch") +local response = fetch.call("get", "https://api.example.com/data") + +// JavaScript APIもBoxとして利用 +local dom = new ExternBox("document") +local element = dom.call("getElementById", "myDiv") +``` + +## 🎉 まとめ + +Everything is Box哲学により、Nyashは： + +1. **シンプル** - すべてが同じルールに従う +2. **強力** - どんなものにもメソッドを追加できる +3. **安全** - 統一的なメモリ管理 +4. **拡張可能** - 新しいBox型を簡単に追加 +5. **統合的** - 外部ライブラリも同じ方法で利用 + +この哲学こそが、Nyashを特別な言語にしているのです。 + +--- + +関連ドキュメント： +- [Box型カタログ](box-types-catalog.md) +- [デリゲーションシステム](delegation-system.md) +- [メモリ管理](memory-management.md) \ No newline at end of file diff --git a/docs/予定/native-plan/box_ffi_abi.md b/docs/説明書/reference/box-design/ffi-abi-specification.md similarity index 100% rename from docs/予定/native-plan/box_ffi_abi.md rename to docs/説明書/reference/box-design/ffi-abi-specification.md diff --git a/docs/説明書/reference/box-design/implementation-notes/current-issues.md b/docs/説明書/reference/box-design/implementation-notes/current-issues.md new file mode 100644 index 00000000..8fb9444c --- /dev/null +++ b/docs/説明書/reference/box-design/implementation-notes/current-issues.md @@ -0,0 +1,117 @@ +# 🔧 Box設計の現在の課題 + +## 📅 最終更新: 2025-08-14 + +このドキュメントは、Nyash Box設計における現在進行中の技術的課題と対応状況をまとめています。 + +## 🚨 Critical: Arc責務の二重化問題 + +### 問題の概要 +現在、15個のBox型において、内部と外部で二重にロック管理が行われています。 + +```rust +// 🚨 現在の問題構造 +pub struct SocketBox { + listener: Arc>>, // 内部ロック + is_server: Arc>, // 内部ロック +} + +// インタープリター側 +Arc> // 外部ロック + +// 結果: 二重ロック → デッドロック・状態不整合 +``` + +### 影響を受けるBox型（15個） +1. **ネットワーク系**: SocketBox, HTTPServerBox +2. **コレクション系**: ArrayBox, MapBox, BufferBox +3. **I/O系**: FileBox, StreamBox +4. **P2P系**: P2PBox, IntentBox, SimpleIntentBox +5. **GUI系**: EguiBox +6. **特殊系**: RandomBox, DebugBox, FutureBox, JSONBox + +### 根本原因 +- **責務の混在**: Box自身がスレッドセーフティを管理 +- **設計の不統一**: 各Box実装者が独自にArcを使用 +- **ガイドライン不足**: 正しいBox実装パターンが未確立 + +### 対応計画 +**Phase 9.75**として緊急対応中。詳細は[phase-9-75-redesign.md](phase-9-75-redesign.md)参照。 + +## ⚠️ High: SocketBox状態保持問題 + +### 問題の詳細 +SocketBoxで`bind()`後に`isServer()`を呼ぶと、状態が保持されていない。 + +```nyash +// 期待される動作 +server = new SocketBox() +server.bind("127.0.0.1", 8080) // true +server.isServer() // true であるべき + +// 実際の動作 +server.isServer() // false （状態が失われる） +``` + +### 技術的分析 +詳細は[socket-box-problem.md](socket-box-problem.md)参照。 + +### 暫定対策 +- PR #75でArc参照共有を試みたが、根本解決には至らず +- デッドロック問題は解決したが、状態保持問題は継続 + +## 🟡 Medium: Box型の増殖管理 + +### 現状 +- 基本実装済みBox: 20種類以上 +- 各Boxが独自の実装パターン +- 統一的な品質管理が困難 + +### 課題 +1. **実装の一貫性**: 各Boxで異なる実装スタイル +2. **テストカバレッジ**: Box間でテスト密度にばらつき +3. **ドキュメント**: API仕様の記述レベルが不統一 + +### 対応方針 +- Box実装テンプレートの作成 +- 自動テスト生成ツールの検討 +- APIドキュメント自動生成 + +## 🟢 Low: パフォーマンス最適化 + +### 観測された問題 +- 二重ロックによるパフォーマンス低下 +- Box生成時のオーバーヘッド +- メソッド呼び出しの動的ディスパッチコスト + +### 最適化の機会 +1. **ロック削減**: Arc一元化で改善見込み +2. **Box生成**: オブジェクトプールの検討 +3. **メソッド呼び出し**: インライン化・特殊化 + +## 📊 課題の優先順位 + +1. **🔴 最優先**: Arc責務一元化（Phase 9.75） +2. **🟠 高優先**: SocketBox状態保持問題の根本解決 +3. **🟡 中優先**: Box実装ガイドライン策定 +4. **🟢 低優先**: パフォーマンス最適化 + +## 🔄 進捗追跡 + +### 2025-08-14 +- Phase 9.75として「Box設計根本革命」を`copilot_issues.txt`に追加 +- Box設計ドキュメントフォルダを新規作成 +- 現在の課題を体系的に整理 + +### 今後の予定 +- Phase 9.75 Phase A: 設計ガイドライン策定（3日） +- Phase 9.75 Phase B: 最優先Box修正（1週間） +- Phase 9.75 Phase C: ステートフルBox修正（1週間） +- Phase 9.75 Phase D: 残りのBox統一（3日） + +--- + +関連ドキュメント： +- [Phase 9.75実装計画](phase-9-75-redesign.md) +- [SocketBox問題詳細](socket-box-problem.md) +- [Box設計原則](../memory-management.md) \ No newline at end of file diff --git a/docs/説明書/reference/box-design/implementation-notes/phase-9-75-redesign.md b/docs/説明書/reference/box-design/implementation-notes/phase-9-75-redesign.md new file mode 100644 index 00000000..3fe4a454 --- /dev/null +++ b/docs/説明書/reference/box-design/implementation-notes/phase-9-75-redesign.md @@ -0,0 +1,231 @@ +# 🔧 Phase 9.75: Box設計根本革命 - 実装計画詳細 + +## 📅 実施期間: 2025-08 (Phase 9.7完了後) + +## 🎯 目標 + +Arc責務の二重化問題を根本的に解決し、すべてのBox型で統一的な設計を実現する。 + +## 🏗️ 新設計アーキテクチャ + +### Before（現在の問題設計） +```rust +// Box内部でロック管理 +pub struct SocketBox { + listener: Arc>>, + is_server: Arc>, +} + +// インタープリターでも二重ロック +Arc> +``` + +### After（新設計） +```rust +// 純粋なデータコンテナ +pub struct SocketBox { + listener: Option, + is_server: bool, +} + +// インタープリターが一元管理 +Arc> +``` + +## 📋 実装フェーズ + +### Phase A: 設計ガイドライン策定（3日） + +#### A-1: Box実装パターンドキュメント +```rust +// ✅ 推奨パターン +pub struct MyBox { + base: BoxBase, + data: String, // シンプルなフィールド + count: usize, // Arc不要 + items: Vec, // 直接保持 +} + +// ❌ アンチパターン +pub struct BadBox { + data: Arc>, // 内部ロック禁止 + count: Arc>, // 過剰な同期 +} +``` + +#### A-2: テンプレート作成 +- `box_template.rs` - 新Box実装のひな形 +- `box_test_template.rs` - テストスイートひな形 +- マクロによる定型処理自動化検討 + +#### A-3: 既存コードレビュー +- 15個のBox型の実装詳細調査 +- 問題パターンの分類 +- 修正難易度の評価 + +### Phase B: 最優先Box修正（1週間） + +#### B-1: SocketBox修正 +```rust +// 新実装 +impl NyashBox for SocketBox { + fn bind(&mut self, addr: &str, port: u16) -> Result<(), String> { + match TcpListener::bind((addr, port)) { + Ok(listener) => { + self.listener = Some(listener); + self.is_server = true; + Ok(()) + } + Err(e) => Err(e.to_string()) + } + } +} +``` + +#### B-2: HTTPServerBox修正 +- SocketBoxと同様のパターンで修正 +- 内部SocketBoxとの連携確認 + +#### B-3: テストスイート作成 +```nyash +// 状態保持テスト +test "SocketBox state persistence" { + server = new SocketBox() + assert(server.bind("127.0.0.1", 8080) == true) + assert(server.isServer() == true) // 必ず成功すること +} + +// 並行アクセステスト +test "Concurrent access safety" { + // 複数スレッドからのアクセステスト +} +``` + +### Phase C: ステートフルBox修正（1週間） + +#### C-1: コレクション系Box +- **ArrayBox**: `Vec>`直接保持 +- **MapBox**: `HashMap>`直接保持 +- **BufferBox**: バッファ管理の簡素化 + +#### C-2: I/O系Box +- **FileBox**: ファイルハンドル管理 +- **StreamBox**: ストリーム状態管理 + +#### C-3: P2P系Box +- **P2PBox**: ピア管理の再設計 +- **IntentBox**: インテント処理の簡素化 + +### Phase D: 残りのBox統一（3日） + +#### D-1: 機械的修正 +- RandomBox, DebugBox等の単純なBox +- Arc除去の機械的適用 + +#### D-2: 統合テスト +- 全Box型の動作確認 +- 相互運用性テスト +- メモリリークチェック + +#### D-3: パフォーマンス検証 +- ベンチマーク実行 +- ロック競合の削減確認 +- メモリ使用量の改善確認 + +## 🤖 Copilot協力タスク + +### 自動化可能な作業 +1. **Arc検出スクリプト** + ```bash + grep -r "Arc>` → `T` + - `.lock().unwrap()` 除去 + - Clone実装の簡素化 + +3. **テストケース生成** + - 各Boxの状態保持テスト + - 並行アクセステスト + - エッジケーステスト + +## 📊 成功指標 + +### 定量的指標 +- [ ] Arc使用箇所: 0個（Box内部） +- [ ] デッドロック発生: 0件 +- [ ] 状態保持テスト: 100%成功 +- [ ] パフォーマンス: 10%以上向上 + +### 定性的指標 +- [ ] コード可読性の向上 +- [ ] デバッグの容易さ +- [ ] 新規開発者の理解しやすさ + +## 🚨 リスクと対策 + +### リスク1: 既存コード互換性 +**対策**: +- NyashBoxトレイトは変更しない +- 段階的移行（deprecated警告） + +### リスク2: パフォーマンス劣化 +**対策**: +- 事前ベンチマーク取得 +- ホットパスの最適化 + +### リスク3: 実装工数超過 +**対策**: +- 優先順位付け（SocketBox最優先） +- Copilot活用による自動化 + +## 📅 詳細スケジュール + +``` +Week 1: +月: Phase A-1 パターンドキュメント +火: Phase A-2 テンプレート作成 +水: Phase A-3 既存コードレビュー +木: Phase B-1 SocketBox修正開始 +金: Phase B-1 SocketBox修正完了 + +Week 2: +月: Phase B-2 HTTPServerBox修正 +火: Phase B-3 テストスイート作成 +水: Phase C-1 ArrayBox/MapBox修正 +木: Phase C-2 FileBox/StreamBox修正 +金: Phase C-3 P2PBox修正 + +Week 3: +月: Phase D-1 残りBox修正 +火: Phase D-2 統合テスト +水: Phase D-3 パフォーマンス検証 +木: ドキュメント最終化 +金: リリース準備 +``` + +## 🎉 期待される成果 + +1. **技術的成果** + - デッドロック問題の根絶 + - 状態管理の信頼性向上 + - パフォーマンス改善 + +2. **開発効率向上** + - 新Box実装の簡素化 + - デバッグ時間の短縮 + - 保守コストの削減 + +3. **Everything is Box哲学の強化** + - より純粋なBox設計 + - 統一的な実装パターン + - 初学者にも理解しやすい構造 + +--- + +関連ドキュメント： +- [現在の課題](current-issues.md) +- [SocketBox問題詳細](socket-box-problem.md) +- [copilot_issues.txt](../../../../../予定/native-plan/copilot_issues.txt) \ No newline at end of file diff --git a/docs/説明書/reference/box-design/implementation-notes/socket-box-problem.md b/docs/説明書/reference/box-design/implementation-notes/socket-box-problem.md new file mode 100644 index 00000000..5a59559b --- /dev/null +++ b/docs/説明書/reference/box-design/implementation-notes/socket-box-problem.md @@ -0,0 +1,183 @@ +# 🔌 SocketBox Arc二重化問題の詳細分析 + +## 🚨 問題の症状 + +### 観測された現象 +```nyash +// テストコード +server = new SocketBox() +server.bind("127.0.0.1", 8080) // ✅ 成功: true +server.isServer() // ❌ 失敗: false (期待値: true) +``` + +### デバッグ出力 +``` +🔥 SOCKETBOX DEBUG: bind() called +🔥 Socket ID = 17 +🔥 Arc pointer = 0x7ffd5b8a3d20 +🔥 Arc data pointer = 0x5565423a6d60 +🔥 AFTER MUTATION: is_server = true + +🔥 SOCKETBOX DEBUG: isServer() called +🔥 Socket ID = 17 +🔥 Arc pointer = 0x7ffd5b8a3d20 +🔥 Arc data pointer = 0x5565423a6d60 // 同じポインタ！ +🔥 IS_SERVER READ: is_server = false // しかし値は失われている +``` + +## 🔍 根本原因の分析 + +### 1. 責務の二重化 +```rust +// 現在のSocketBox実装 +pub struct SocketBox { + base: BoxBase, + listener: Arc>>, // 内部ロック + stream: Arc>>, // 内部ロック + is_server: Arc>, // 内部ロック + is_connected: Arc>, // 内部ロック +} + +// インタープリター側 +let socket: Arc> = Arc::new(Mutex::new(SocketBox::new())); +``` + +### 2. 状態更新の問題 +```rust +// bind()メソッド内での状態更新 +pub fn bind(&self, address: Box, port: Box) -> Box { + // ... + *self.is_server.lock().unwrap() = true; // 内部Mutexへの書き込み + // ... +} +``` + +### 3. Clone実装の複雑性 +```rust +impl Clone for SocketBox { + fn clone(&self) -> Self { + Self { + base: BoxBase::new(), // 新しいID（デバッグ用） + listener: Arc::clone(&self.listener), // Arcを共有 + stream: Arc::clone(&self.stream), // Arcを共有 + is_server: Arc::clone(&self.is_server), // Arcを共有 + is_connected: Arc::clone(&self.is_connected), // Arcを共有 + } + } +} +``` + +## 💀 デッドロックの危険性 + +### 発生パターン +1. インタープリターがSocketBoxをロック +2. SocketBoxメソッドが内部フィールドをロック +3. 別スレッドが逆順でロックを試みる +4. デッドロック発生 + +### 実際に観測されたデッドロック +```rust +// PR #75修正前 +pub fn bind(&self, ...) -> Box { + // ... + let updated = SocketBox { /* ... */ }; + Box::new(updated.clone()) // ここでデッドロック +} +``` + +## 🔄 試みられた修正と結果 + +### PR #75: Arc統合 +**目的**: 状態を共有するためにArc参照を使用 +**結果**: +- ✅ デッドロック解消 +- ❌ 状態保持問題は未解決 + +### PR #81: フィールド更新メカニズム +**目的**: インスタンスフィールドの更新を修正 +**結果**: +- ✅ フィールド更新は動作 +- ❌ SocketBox内部状態は依然として失われる + +## 🎯 Gemini先生の根本解決策 + +### 設計原則の転換 +```rust +// ❌ 現在の設計: Box自身がロック責務を持つ +pub struct SocketBox { + is_server: Arc>, // Box内部でロック管理 +} + +// ✅ 新設計: 純粋なデータコンテナ +pub struct PlainSocketBox { + pub listener: Option, + pub is_server: bool, // シンプルなフィールド +} +``` + +### 責務の明確化 +- **Box**: 純粋なデータとロジックのみ +- **インタープリター**: すべてのロック管理を一元化 + +### 実装例 +```rust +// 新しいbind()実装 +impl PlainSocketBox { + pub fn bind(&mut self, addr: &str, port: u16) -> bool { + match TcpListener::bind((addr, port)) { + Ok(listener) => { + self.listener = Some(listener); + self.is_server = true; // 直接代入、ロック不要 + true + }, + Err(_) => false + } + } +} +``` + +## 📊 影響分析 + +### 同じ問題を抱えるBox型 +1. **HTTPServerBox**: SocketBoxを内包、同様の問題 +2. **ArrayBox**: `Arc>>` +3. **MapBox**: `Arc>>` +4. **P2PBox**: 複雑な内部状態管理 +5. その他10個のBox型 + +### リファクタリングの規模 +- 影響Box数: 15個 +- 推定作業量: 2-3週間（Phase 9.75） +- リスク: 既存コードの互換性 + +## 🚀 移行戦略 + +### Phase A: 設計ガイドライン（3日） +1. 新Box実装パターンの確立 +2. Arc禁止ルールの明文化 +3. テンプレート・サンプルコード作成 + +### Phase B: 最優先修正（1週間） +1. SocketBox → PlainSocketBox +2. HTTPServerBox → PlainHTTPServerBox +3. 状態保持テストスイート作成 + +### Phase C: 全Box統一（1-2週間） +1. 残り13個のBox型修正 +2. 統合テスト実施 +3. パフォーマンス検証 + +## 🎉 期待される効果 + +1. **デッドロック根絶**: 二重ロック構造の排除 +2. **状態整合性保証**: インタープリター一元管理 +3. **デバッグ容易性**: シンプルな実装 +4. **パフォーマンス向上**: ロック競合の削減 +5. **保守性向上**: 統一的な実装パターン + +--- + +関連ドキュメント： +- [現在の課題一覧](current-issues.md) +- [Phase 9.75実装計画](phase-9-75-redesign.md) +- [メモリ管理設計](../memory-management.md) \ No newline at end of file diff --git a/docs/説明書/reference/box-design/memory-management.md b/docs/説明書/reference/box-design/memory-management.md new file mode 100644 index 00000000..46a35610 --- /dev/null +++ b/docs/説明書/reference/box-design/memory-management.md @@ -0,0 +1,307 @@ +# 🧠 Nyash メモリ管理設計 + +## 📋 概要 + +Nyashは「Everything is Box」哲学のもと、すべての値をBoxとして統一的に管理します。 +メモリ安全性を保証しながら、シンプルで直感的なメモリ管理を実現しています。 + +## 🏗️ 基本アーキテクチャ + +### Arc一元管理 + +```rust +// インタープリターレベルでの統一管理 +type NyashObject = Arc>; +``` + +すべてのBoxは、インタープリターレベルで`Arc`によって管理されます。 +これにより： +- **スレッドセーフティ**: 自動的に保証 +- **参照カウント**: 自動的なメモリ解放 +- **統一的アクセス**: すべて同じ方法で操作 + +### ❌ アンチパターン（Phase 9.75で修正中） + +```rust +// 現在の問題: Box内部での二重ロック +pub struct BadBox { + data: Arc>, // ❌ Box内部でロック管理 +} + +// 正しい設計 +pub struct GoodBox { + data: String, // ✅ シンプルなフィールド +} +``` + +## 🔄 fini()システム + +### 概要 +Nyashは決定論的なリソース解放のために`fini()`システムを提供します。 + +```nyash +box FileHandler { + init { file } + + fini() { + // オブジェクト削除時に自動呼び出し + if me.file != null { + me.file.close() + console.log("File closed automatically") + } + } +} +``` + +### fini()の特徴 + +1. **自動呼び出し**: オブジェクトの参照がゼロになると自動実行 +2. **決定論的**: GCのタイミングに依存しない +3. **伝播**: 親オブジェクトのfini()が子オブジェクトに伝播 + +### 実装例 + +```nyash +box DatabaseConnection { + init { connection, transactions } + + fini() { + // トランザクションをすべてロールバック + for tx in me.transactions { + tx.rollback() + } + // 接続を閉じる + me.connection.close() + } +} + +// 使用例 +{ + local db = new DatabaseConnection() + db.connect("localhost:5432") + // ... データベース操作 ... +} // スコープを抜けると自動的にfini()が呼ばれる +``` + +## 💭 weak参照システム + +### 循環参照の問題と解決 + +```nyash +// 循環参照の例 +box Parent { + init { children } + + pack() { + me.children = new ArrayBox() + } + + addChild(child) { + me.children.push(child) + child.parent = me // 循環参照！ + } +} + +box Child { + init { parent } +} +``` + +### weak参照による解決 + +```nyash +box Parent { + init { children } + + pack() { + me.children = new ArrayBox() + } + + addChild(child) { + me.children.push(child) + child.parent = weak me // weak参照で循環を防ぐ + } +} + +box Child { + init { parent } // weak参照として保持 + + getParent() { + // weak参照から通常参照を取得 + local p = strong me.parent + if p == null { + console.log("Parent has been deleted") + return null + } + return p + } +} +``` + +### weak参照の特徴 + +1. **自動null化**: 参照先が削除されるとnullになる +2. **メモリリーク防止**: 循環参照を断ち切る +3. **明示的変換**: `strong`で通常参照に変換 + +## 📊 メモリ管理パターン + +### 1. 所有権パターン + +```nyash +box Container { + init { items } // Containerがitemsを所有 + + pack() { + me.items = new ArrayBox() + } + + fini() { + // itemsも自動的に解放される + console.log("Container and all items released") + } +} +``` + +### 2. 共有参照パターン + +```nyash +// 複数のオブジェクトで共有 +local sharedData = new DataBox() + +local viewer1 = new DataViewer(sharedData) +local viewer2 = new DataViewer(sharedData) + +// sharedDataは両方のviewerから参照されている間は生存 +``` + +### 3. 観察者パターン + +```nyash +box Subject { + init { observers } + + pack() { + me.observers = new ArrayBox() + } + + attach(observer) { + // weak参照で観察者を保持 + me.observers.push(weak observer) + } + + notify() { + // weak参照をチェックしながら通知 + local aliveObservers = new ArrayBox() + + for weakObs in me.observers { + local obs = strong weakObs + if obs != null { + obs.update(me) + aliveObservers.push(weakObs) + } + } + + // 死んだ参照を削除 + me.observers = aliveObservers + } +} +``` + +## 🛡️ メモリ安全性保証 + +### 1. 二重解放防止 +Arcにより、同じオブジェクトの二重解放は不可能。 + +### 2. Use-After-Free防止 +参照カウントにより、使用中のオブジェクトは解放されない。 + +### 3. データ競合防止 +Mutexにより、同時アクセスは自動的に同期される。 + +### 4. メモリリーク検出 +```nyash +// デバッグモードでメモリリーク検出 +DEBUG = new DebugBox() +DEBUG.startTracking() + +// ... プログラム実行 ... + +print(DEBUG.memoryReport()) +// 出力: 未解放オブジェクト一覧 +``` + +## 🚀 ベストプラクティス + +### 1. fini()の正しい使い方 +```nyash +box ResourceManager { + init { resources } + + fini() { + // 1. 子リソースから順に解放 + for resource in me.resources { + resource.release() + } + + // 2. 自身のリソースを解放 + me.cleanup() + + // 3. ログを残す（デバッグ用） + console.log("ResourceManager cleaned up") + } +} +``` + +### 2. weak参照の使い時 +- **親子関係**: 子→親はweak参照 +- **イベントリスナー**: Subject→Observerはweak参照 +- **キャッシュ**: 一時的な参照はweak + +### 3. メモリ効率的なコード +```nyash +// ❌ 非効率 +loop(i < 1000000) { + local temp = new StringBox("temp") + // tempが毎回作られる +} + +// ✅ 効率的 +local temp = new StringBox("") +loop(i < 1000000) { + temp.set("temp") + // 既存オブジェクトを再利用 +} +``` + +## 📈 パフォーマンス考慮事項 + +### 1. 参照カウントのオーバーヘッド +- 小さいが無視できない +- ホットパスでは最小限に + +### 2. Mutexロックの競合 +- Phase 9.75で一元化により改善予定 +- 細粒度ロックを避ける + +### 3. fini()の実行コスト +- 複雑なfini()は避ける +- 非同期処理は避ける + +## 🔮 将来の拡張 + +### 1. 世代別GC +参照カウントと世代別GCのハイブリッド検討 + +### 2. メモリプール +頻繁に生成・破棄されるBoxのプール化 + +### 3. コンパクション +メモリ断片化対策 + +--- + +関連ドキュメント： +- [Everything is Box](everything-is-box.md) +- [fini/weak参照リファレンス](../finalization-system.md) +- [Phase 9.75実装計画](implementation-notes/phase-9-75-redesign.md) \ No newline at end of file