hakorune/docs/development/roadmap/phases/phase-12/archive/legacy-abi-docs/nyash-abi.md

Nyash ABI プラグインシステム

📦 概要

Nyash ABIは、C ABI + TypeBoxをベースに構築された高度なプラグインシステムです。C ABIの限界を超えて、より豊富な機能と言語間相互運用を提供します。

🏗️ アーキテクチャ

基本層：C ABI（シンプル・高速・安定）
   ↓
拡張層：TypeBox（プラグイン間連携）
   ↓
高度層：Nyash ABI（言語間相互運用・拡張性）

Nyash ABIは、C ABIとTypeBoxの上に構築されているため、既存のC ABIプラグインとの互換性を保ちながら、より高度な機能を提供できます。

🎯 特徴

C ABIからの進化点

1. セレクターベースの高速ディスパッチ

   • 文字列比較ではなく、事前計算されたハッシュ値を使用
   • メソッド呼び出しの高速化

2. NyashValue型による統一的な値表現

   • 16バイトに最適化された値表現
   • インライン値サポート（小さな整数やboolは直接格納）

3. 言語間相互運用

   • Python、Go、JavaScript等との連携が可能
   • 共通のオブジェクトモデルを提供

4. 高度なメモリ管理

   • アトミック参照カウント
   • 弱参照による循環参照回避

📝 実装例

基本的なNyash ABIプラグイン

#include "nyash_abi.h"

// Nyash ABIオブジェクト構造体
typedef struct {
    nyash_obj_header header;  // 共通ヘッダー（参照カウント等）
    int value;                // カスタムデータ
} CounterBox;

// メソッドディスパッチャー（セレクターベース）
nyash_status counter_call(
    nyash_ctx* ctx,
    void* self,
    nyash_selector selector,
    nyash_value* args,
    size_t arg_count,
    nyash_value* result
) {
    CounterBox* counter = (CounterBox*)self;
    
    // セレクターに基づいて高速ディスパッチ
    switch(selector) {
        case NYASH_SEL_INCREMENT:  // 事前計算されたハッシュ値
            counter->value++;
            *result = nyash_make_int(counter->value);
            return NYASH_OK;
            
        case NYASH_SEL_GET_VALUE:
            *result = nyash_make_int(counter->value);
            return NYASH_OK;
            
        default:
            return NYASH_ERROR_METHOD_NOT_FOUND;
    }
}

NyashValue - 統一的な値表現

// 16バイトに最適化された値構造（JIT/LLVM最適化を考慮）
typedef struct __attribute__((aligned(16))) {
    uint64_t type_id;     // 型識別子
    uint64_t payload;     // ポインタまたはインライン値
    uint64_t metadata;    // フラグ・追加情報
} nyash_value;

// インライン値の例
nyash_value nyash_make_int(int64_t value) {
    return (nyash_value){
        .type_id = NYASH_TYPE_INTEGER,
        .payload = (uint64_t)value,
        .metadata = NYASH_TAG_SMALL_INT  // インライン整数タグ
    };
}

// Boxオブジェクトの例
nyash_value nyash_make_box(void* box_ptr) {
    return (nyash_value){
        .type_id = ((nyash_obj_header*)box_ptr)->type_id,
        .payload = (uint64_t)box_ptr,
        .metadata = NYASH_TAG_POINTER  // ヒープポインタタグ
    };
}

🌐 言語間相互運用

Python連携

# Python側のNyash ABIラッパー
import nyash

# Nyashプラグインをロード
counter = nyash.load_plugin("counter.so")

# セレクターベースの呼び出し
result = counter.call("increment")  # 内部でセレクターに変換
print(f"Counter value: {result}")

Go連携

// Go側のNyash ABIバインディング
package main

import "github.com/nyash/go-bindings"

func main() {
    counter := nyash.LoadPlugin("counter.so")
    
    // 型安全な呼び出し
    value, err := counter.Call("increment")
    if err == nil {
        fmt.Printf("Counter value: %d\n", value.(int64))
    }
}

🚀 Nyash ABIがTypeBoxとして実装される仕組み

Nyash ABIの革新的な点は、ABIそのものがTypeBoxとして実装されることです：

// Nyash ABIプロバイダーもTypeBox（C ABI）として提供
typedef struct {
    // TypeBox標準ヘッダ
    uint32_t abi_tag;           // 'NABI'
    const char* name;           // "NyashABIProvider"
    void* (*create)(void);      // ABIプロバイダ生成
    
    // Nyash ABI専用操作
    struct {
        nyash_status (*call)(nyash_ctx*, void* obj, nyash_selector, ...);
        void (*retain)(void* obj);
        void (*release)(void* obj);
    } nyash_ops;
} NyashABITypeBox;

これにより：

1. 段階的移行: C ABIプラグインからNyash ABIへの移行が容易
2. 相互運用: C ABIとNyash ABIプラグインが同じシステムで共存
3. セルフホスティング: 最終的にNyash自身でNyashを実装可能

💡 いつNyash ABIを使うべきか？

Nyash ABIが最適な場合

• ✅ 他言語との相互運用が必要（Python/Go/JS等）
• ✅ 高度なメソッドディスパッチが必要（セレクター方式）
• ✅ 複雑な型システムを扱う
• ✅ 将来の拡張性を重視

C ABIで十分な場合

• ✅ シンプルな機能のみ必要
• ✅ 最高速度を求める（直接関数呼び出し）
• ✅ 既存のC/C++ライブラリの単純なラップ

📊 3つのABIの比較

特徴	C ABI	C ABI + TypeBox	Nyash ABI
シンプルさ	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
速度	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
プラグイン間連携	❌	✅	✅
言語間連携	⭐⭐	⭐⭐	⭐⭐⭐⭐⭐
拡張性	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐

📚 まとめ

Nyash ABIは「C ABI + TypeBoxの上に構築された高度なプラグインシステム」です。

• C ABIの安定性とシンプルさを継承
• TypeBoxによるプラグイン間連携をサポート
• セレクター方式による高速メソッドディスパッチ
• 言語間相互運用による無限の可能性

高度な機能や将来の拡張性が必要ならNyash ABIを選びましょう！