hakorune/docs/説明書/reference/builtin-boxes.md

ビルトインBox型 API リファレンス

Nyashで利用できる全ビルトインBox型のAPI仕様書です。

📡 P2PBox - 通信ノードBox

P2P通信を行うノードを表すBox。通信世界（IntentBox）に参加してメッセージを送受信できます。

コンストラクタ

// 通信ノードを作成
local node = new P2PBox(node_id, world)

パラメータ:

• node_id (String): ノードの一意識別子
• world (IntentBox): 参加する通信世界

メソッド

send(intent, data, target)

特定のノードにメッセージを送信します。

local result = node.send("greeting", message_data, "target_node_id")

パラメータ:

• intent (String): メッセージの種類
• data (Box): 送信するデータ
• target (String): 送信先ノードID

戻り値: StringBox("sent")

on(intent, callback)

指定したintentのメッセージを受信した際のリスナーを登録します。

node.on("chat", callback_function)

パラメータ:

• intent (String): 監視するメッセージ種類
• callback (MethodBox): 受信時に呼ばれる関数

戻り値: StringBox("listener added")

off(intent)

指定したintentのリスナーを解除します。

node.off("chat")

パラメータ:

• intent (String): 解除するメッセージ種類

戻り値: StringBox("listener removed" / "no listener found")

get_node_id()

このノードのIDを取得します。

local id = node.get_node_id()

戻り値: StringBox(ノードID)

使用例

// 通信世界を作成
local world = new IntentBox()

// 2つのノードを作成
local alice = new P2PBox("alice", world)
local bob = new P2PBox("bob", world)

// Bobがgreetingを受信するリスナー設定
bob.on("greeting", greeting_handler)

// AliceからBobにメッセージ送信
local message = new MapBox()
message.set("text", "Hello Bob!")
alice.send("greeting", message, "bob")

---

📨 IntentBox - 通信世界Box

P2PBoxが通信を行うための世界（ネットワーク）を表すBox。複数のノードが同一のIntentBoxを共有して通信します。

コンストラクタ

// 通信世界を作成
local world = new IntentBox()

パラメータ: なし

特徴

• ローカル通信: 同一プロセス内のP2PBox間でメッセージをやり取り
• スレッドセーフ: Arcにより並行アクセス対応
• 将来拡張: WebSocket版や分散版への拡張予定

使用例

// 1つの通信世界に複数ノードが参加
local world = new IntentBox()
local node1 = new P2PBox("server", world)
local node2 = new P2PBox("client", world)

// 同一世界内での通信が可能
node1.send("data", payload, "client")

---

📝 StringBox - 文字列Box

文字列データを格納・操作するBox。

コンストラクタ

local text = new StringBox("Hello")

基本メソッド

• toString(): 文字列表現を取得
• length(): 文字列長を取得
• concat(other): 文字列結合
• substring(start, end): 部分文字列取得

---

🔢 IntegerBox - 整数Box

整数データを格納・操作するBox。

コンストラクタ

local num = new IntegerBox(42)

基本メソッド

• toString(): 文字列表現を取得
• add(other): 加算
• subtract(other): 減算
• multiply(other): 乗算
• divide(other): 除算

---

📺 ConsoleBox - コンソール出力Box

コンソールへの出力を行うBox。

コンストラクタ

local console = new ConsoleBox()

メソッド

• log(message): メッセージをログ出力
• error(message): エラーメッセージを出力

---

🗂️ MapBox - 連想配列Box

キー・バリューペアでデータを格納するBox。

コンストラクタ

local map = new MapBox()

メソッド

• set(key, value): キー・バリューを設定
• get(key): 値を取得
• has(key): キーが存在するかチェック
• remove(key): キー・バリューを削除

📊 BufferBox - バイナリデータ処理Box

バイナリデータの読み書きを効率的に処理するBox。ファイル操作、ネットワーク通信、画像処理で使用。

コンストラクタ

// 空のバッファを作成
local buffer = new BufferBox()

基本メソッド

• write(data): バイトデータ書き込み (ArrayBox[integers])
• read(count): 指定バイト数読み取り → ArrayBox
• readAll(): 全データ読み取り → ArrayBox
• clear(): バッファクリア → StringBox("ok")
• length(): データサイズ取得 → IntegerBox
• append(buffer): 他BufferBoxを追加 → IntegerBox(新サイズ)
• slice(start, end): 部分データ取得 → BufferBox

⭐ Phase 10: 高度なメモリ管理API

ゼロコピー検出API

// ゼロコピー共有の検出
local buffer1 = new BufferBox()
local shared_buffer = buffer1.share_reference(null)

// 共有検出
local is_shared = buffer1.is_shared_with(shared_buffer)  // → BoolBox(true)

• is_shared_with(other): 他BufferBoxとのメモリ共有を検出 → BoolBox
• share_reference(data): Arc参照を共有した新BufferBoxを作成 → BufferBox
• memory_footprint(): 現在のメモリ使用量を取得 → IntegerBox(bytes)

実装詳細

• Arc::ptr_eq(): 真のポインタ共有検出でゼロコピーを保証
• 共有状態: share_reference()で作成されたBufferは元のデータを共有
• 独立性: clone_box()は完全に独立したコピーを作成

使用例

// HTTP転送でのゼロコピー検証
static box ProxyServer {
    relay_data(client_data) {
        if (me.upstream_buffer.is_shared_with(client_data)) {
            print("✅ Zero-copy achieved!")
        }
        return me.upstream_buffer.share_reference(client_data)
    }
}

---

最終更新: 2025年8月15日 (Phase 10: BufferBox高度メモリ管理API追加)