# 機能設計書 23-ハンドルデータ取得・設定

## 概要

本ドキュメントは、libuv の `uv_handle_get_data()` および `uv_handle_set_data()` 関数によるハンドルへのユーザーデータの関連付け機能の設計を記述する。

### 本機能の処理概要

本機能は、ハンドルに任意のユーザーデータポインタを関連付けるためのgetter/setter関数ペアを提供する。`uv_handle_set_data()`でハンドルの`data`フィールドにユーザーポインタを設定し、`uv_handle_get_data()`で取得する。

**業務上の目的・背景**：libuvのコールバック関数はハンドルポインタを引数として受け取るが、コールバック内でアプリケーション固有のコンテキスト情報にアクセスする必要がある。`data`フィールドはそのための汎用的なメカニズムを提供し、コールバックベースの非同期プログラミングにおいてアプリケーション状態の受け渡しを可能にする。

**機能の利用シーン**：
- コールバック関数内で、ハンドルに紐づくアプリケーション状態にアクセスする場合
- イベントハンドラからアプリケーションのコンテキスト（接続情報、セッション情報等）を参照する場合
- 言語バインディングで、ネイティブハンドルとラッパーオブジェクトを対応付ける場合

**主要な処理内容**：
1. `uv_handle_get_data()`: ハンドルの`data`フィールドの値を返却
2. `uv_handle_set_data()`: ハンドルの`data`フィールドにユーザーポインタを設定

**関連システム・外部連携**：特になし。ライブラリ内部で完結する単純なフィールドアクセス。

**権限による制御**：なし。ただし`data`フィールドは`uv_handle_t`の`public`領域に定義されており、直接フィールドアクセスも可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | ハンドル基底 | 主画面 | uv_handle_get_data()/uv_handle_set_data()によるユーザーデータ関連付けのAPI定義 |

## 機能種別

データ取得・設定処理（ハンドルへのユーザーデータポインタの読み書き）

## 入力仕様

### 入力パラメータ

#### uv_handle_get_data()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | const uv_handle_t* | Yes | データを取得するハンドルへのポインタ | NULLでないこと |

#### uv_handle_set_data()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | uv_handle_t* | Yes | データを設定するハンドルへのポインタ | NULLでないこと |
| data | void* | Yes | 設定するユーザーデータポインタ | 任意（NULLも許容） |

### 入力データソース

呼び出し元から直接引数として渡される。

## 出力仕様

### 出力データ

#### uv_handle_get_data()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | void* | ハンドルに関連付けられたユーザーデータポインタ |

#### uv_handle_set_data()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | void | なし（戻り値なし） |

### 出力先

`uv_handle_get_data()`は関数の戻り値として返却。`uv_handle_set_data()`はハンドル構造体のdataフィールドに書き込み。

## 処理フロー

### 処理シーケンス

```
uv_handle_get_data():
1. handle->data を返却

uv_handle_set_data():
1. handle->data に data を設定
```

### フローチャート

```mermaid
flowchart TD
    A1[uv_handle_get_data] --> B1[return handle->data]
    A2[uv_handle_set_data] --> B2[handle->data = data]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-23-01 | 直接フィールドアクセス | getter/setterはhandle->dataフィールドへの直接アクセスのラッパー | 常時 |
| BR-23-02 | ポインタ管理責任 | dataに設定したメモリの管理はユーザー責任 | 常時 |
| BR-23-03 | publicフィールド | dataフィールドはUV_HANDLE_FIELDSのpublic領域に定義 | 常時 |

### 計算ロジック

特別な計算ロジックはない。

## データベース操作仕様

データベース操作は存在しない。

## エラー処理

### エラーケース一覧

明示的なエラー処理は存在しない。NULLハンドルを渡した場合はセグメンテーションフォルトが発生する。

### リトライ仕様

リトライは不要。

## トランザクション仕様

トランザクションは存在しない。

## パフォーマンス要件

O(1)の定数時間。単純なフィールドの読み書きのみ。

## セキュリティ考慮事項

- dataフィールドに格納されるポインタのライフタイム管理はユーザー責任。
- マルチスレッド環境でのdataフィールドへのアクセスは同期が必要。

## 備考

- `data`フィールドは`UV_HANDLE_FIELDS`マクロのpublic部に定義されており（`include/uv.h` L465）、`handle->data`として直接アクセスすることも可能。getter/setterは言語バインディングや将来的なAPIの安定性のために提供されている。
- 対になる`uv_loop_get_data()`/`uv_loop_set_data()`がループ用に存在する（No.13参照）。
- 対になる`uv_req_get_data()`/`uv_req_set_data()`がリクエスト用に存在する（No.28参照）。

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | UV_HANDLE_FIELDSマクロ（L463-476）のdataフィールド（L465）。publicとコメントされている |
| 1-2 | uv.h | `include/uv.h` | uv_handle_s構造体（L479-481）がUV_HANDLE_FIELDSを展開している |

**読解のコツ**: `void* data`フィールドはUV_HANDLE_FIELDSマクロの最初のフィールドであり、`/* public */`とコメントされている。これは直接アクセスが許容されていることを意味する。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | 関数宣言（L486-488） |
| 2-2 | uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | uv_handle_get_data()の実装（L40-42）とuv_handle_set_data()の実装（L48-50） |

**主要処理フロー**:
1. **40-42行目**: `uv_handle_get_data()` - return handle->data
2. **48-50行目**: `uv_handle_set_data()` - handle->data = data

### プログラム呼び出し階層図

```
uv_handle_get_data(handle)
    └─ return handle->data

uv_handle_set_data(handle, data)
    └─ handle->data = data
```

### データフロー図

```
[入力]                    [処理]                       [出力]

uv_handle_t* ───▶ handle->data参照 ───▶ void* (ユーザーデータ)

uv_handle_t*, void* ───▶ handle->data設定 ───▶ (なし)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | dataフィールド定義・関数宣言 |
| uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | ソース | getter/setterの実装 |
