hakorune/docs/development/roadmap/phases/phase-12/migration-guide.md

統一TypeBox ABIへの移行ガイド

📋 概要

このガイドでは、既存のC ABIプラグインやTypeBoxプラグインを、新しい統一TypeBox ABIに移行する方法を説明します。

良いニュース：既存のプラグインはそのまま動作し続けます！段階的に移行できます。

🎯 移行のメリット

1. パフォーマンス向上：最大33倍の高速化（JIT最適化時）
2. プラグイン間連携：他のBoxを自由に作成・使用可能
3. 将来性：async/await、並列実行、GPU対応への道
4. 保守性向上：統一された1つの形式

🔄 移行パターン

パターン1: 既存のC ABIプラグインから移行

Before（旧C ABI）

// 旧形式：3つの関数をエクスポート
void* string_create(const char* initial) {
    return strdup(initial);
}

void* string_method(void* self, const char* method, 
                   void** args, int argc) {
    if (strcmp(method, "length") == 0) {
        int* result = malloc(sizeof(int));
        *result = strlen((char*)self);
        return result;
    }
    return NULL;
}

void string_destroy(void* self) {
    free(self);
}

After（統一TypeBox）

#include "nyash_typebox.h"

// メソッドIDを定義（高速化のため）
#define METHOD_LENGTH 1

// resolve関数を追加
uint32_t string_resolve(const char* name) {
    if (strcmp(name, "length") == 0) return METHOD_LENGTH;
    return 0;
}

// 高速版メソッドを追加
NyResult string_invoke_id(void* self, uint32_t id, 
                         NyValue* args, int argc) {
    switch (id) {
        case METHOD_LENGTH:
            return ny_result_ok(ny_value_int(strlen((char*)self)));
        default:
            return ny_result_error("Unknown method");
    }
}

// TypeBox構造体として統合
const NyashTypeBox nyash_typebox_StringBox = {
    .abi_tag = 0x54594258,  // 'TYBX'
    .version = 1,
    .struct_size = sizeof(NyashTypeBox),
    .name = "StringBox",
    
    // 既存の関数をそのまま使用
    .create = (void*)string_create,
    .destroy = string_destroy,
    .method = string_method,  // 互換性のため残す
    
    // 新規追加
    .resolve = string_resolve,
    .invoke_id = string_invoke_id,
    
    .capabilities = NYASH_CAP_THREAD_SAFE,
    .reserved = {0}
};

パターン2: 最小限の移行（互換モード）

既存のコードをほぼ変更せずに、TypeBox形式でラップ：

// 既存の関数はそのまま
extern void* my_create(const char*);
extern void* my_method(void*, const char*, void**, int);
extern void my_destroy(void*);

// ラッパーを追加するだけ
const NyashTypeBox nyash_typebox_MyBox = {
    .abi_tag = 0x54594258,
    .version = 1,
    .struct_size = sizeof(NyashTypeBox),
    .name = "MyBox",
    
    .create = (void*)my_create,
    .destroy = my_destroy,
    .method = my_method,
    
    // 高速版は後で追加可能
    .resolve = NULL,
    .invoke_id = NULL,
    
    .capabilities = 0,
    .reserved = {0}
};

🛠️ 移行ツール

自動変換ツール

# 既存のC ABIプラグインを分析して、TypeBoxラッパーを生成
nyash-plugin migrate --input=old_plugin.c --output=new_plugin.c

# 生成されるコード例：
# - TypeBox構造体定義
# - resolve関数のスケルトン
# - invoke_id関数のスケルトン

検証ツール

# 移行後のプラグインが正しく動作するかチェック
nyash-plugin validate new_plugin.so

# 出力例：
# ✅ ABI tag: OK (TYBX)
# ✅ Version: OK (1)
# ✅ Basic functions: OK
# ⚠️ Performance functions: Not implemented (optional)
# ✅ Thread safety: Declared

📊 段階的移行戦略

Step 1: 互換ラッパー（1日）

• 最小限の変更でTypeBox形式に
• 既存の機能はそのまま維持
• テストがすべてパス

Step 2: メソッドID化（1週間）

• resolve関数を実装
• 頻出メソッドにIDを割り当て
• 10-20%の性能向上

Step 3: 高速実装（2週間）

• invoke_id関数を実装
• NyValue形式に対応
• 3-5倍の性能向上

Step 4: 最適化（1ヶ月）

• JITフレンドリーな実装に
• インラインキャッシング対応
• 最大33倍の性能向上

🚨 注意事項

メモリ管理

• NyValueはホスト管理のメモリを使用
• 戻り値の所有権ルールに注意：
  • NYASH_OWN_TRANSFER: 呼び出し元が解放責任
  • NYASH_OWN_BORROW: プラグインが管理、触らない
  • NYASH_OWN_CLONE: コピーして返す

スレッド安全性

• NYASH_CAP_THREAD_SAFEフラグを正しく設定
• グローバル状態を避ける
• 必要ならmutexで保護

エラーハンドリング

// 旧：NULLを返す
return NULL;

// 新：明示的なエラー
return ny_result_error("Invalid argument");

💡 ベストプラクティス

1. メソッドIDは列挙型で管理

enum {
    METHOD_NONE = 0,
    METHOD_LENGTH = 1,
    METHOD_TO_UPPER = 2,
    METHOD_CONCAT = 3,
    // ...
};

2. 型情報を提供

const char* my_get_type_info(void) {
    return "{"
        "\"methods\": ["
        "  {\"name\": \"length\", \"returns\": \"int\"},"
        "  {\"name\": \"toUpper\", \"returns\": \"string\"}"
        "]"
    "}";
}

3. プラグイン間連携を活用

// 他のBoxを使う例
NyashTypeBox* array_type = ny_host_get_typebox("ArrayBox");
void* array = array_type->create(NULL);

📅 移行スケジュール

フェーズ	期間	内容
現在	-	既存プラグインはそのまま動作
Phase 1	3ヶ月	新規プラグインは統一形式推奨
Phase 2	6ヶ月	移行ツール・ガイド充実
Phase 3	9ヶ月	パフォーマンス最適化
Phase 4	12ヶ月	旧形式を非推奨に

🆘 サポート

ドキュメント

• 統一TypeBox ABI仕様
• API詳細リファレンス
• サンプルコード集

コミュニティ

• Discord: #plugin-dev チャンネル
• GitHub: Issues/Discussionsで質問歓迎

移行支援

• 移行の相談・レビュー受付中
• 大規模プラグインの移行支援あり

🎯 まとめ

統一TypeBox ABIへの移行は：

• ✅ 段階的：急ぐ必要なし
• ✅ 互換性重視：既存コードを保護
• ✅ ツール充実：自動化でラクラク
• ✅ 大きなメリット：性能・機能・将来性

今すぐ始められる小さな一歩から！