# 機能設計書 13-ループデータ取得・設定

## 概要

本ドキュメントは、libuv の `uv_loop_get_data()` / `uv_loop_set_data()` 関数によるイベントループへのユーザーデータ関連付け機能について記述する。

### 本機能の処理概要

**業務上の目的・背景**：libuvのイベントループを使用するアプリケーションは、ループに対して独自のコンテキスト情報（アプリケーション状態、設定オブジェクト等）を関連付けたい場合がある。`uv_loop_t` 構造体の `data` フィールドを通じて任意のポインタを保持・取得する機能を提供し、コールバック内からアプリケーション固有の情報にアクセスできるようにする。

**機能の利用シーン**：イベントループのコールバック処理内で、グローバル変数を使わずにアプリケーション固有のコンテキストにアクセスしたい場合に使用される。例えば、HTTPサーバーのリクエストコンテキスト、データベース接続プール、ロガーインスタンスなどをループに関連付ける。

**主要な処理内容**：
1. `uv_loop_get_data()`: ループ構造体の `data` フィールドを返す
2. `uv_loop_set_data()`: ループ構造体の `data` フィールドにポインタを設定する

**関連システム・外部連携**：特になし。内部のデータ構造操作のみ。

**権限による制御**：特になし。公開APIとして利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | イベントループ | 主機能 | uv_loop_get_data()/uv_loop_set_data()によるユーザーデータ関連付けのAPI定義 |

## 機能種別

データ取得・設定（getter/setter）

## 入力仕様

### 入力パラメータ

#### uv_loop_get_data()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| loop | const uv_loop_t* | Yes | 対象のイベントループ | NULLチェックなし |

#### uv_loop_set_data()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| loop | uv_loop_t* | Yes | 対象のイベントループ | NULLチェックなし |
| data | void* | Yes | 設定するユーザーデータポインタ | NULLも許容 |

### 入力データソース

呼び出し元から渡されるイベントループ構造体ポインタおよびユーザーデータポインタ。

## 出力仕様

### 出力データ

#### uv_loop_get_data()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | void* | ループに関連付けられたユーザーデータポインタ。未設定の場合はNULL |

#### uv_loop_set_data()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | void | 戻り値なし |

### 出力先

`uv_loop_get_data()` は戻り値として呼び出し元へ返却。`uv_loop_set_data()` はループ構造体のdataフィールドを更新。

## 処理フロー

### 処理シーケンス

```
uv_loop_get_data():
1. loop->data を返却する

uv_loop_set_data():
1. loop->data = data として設定する
```

### フローチャート

```mermaid
flowchart TD
    subgraph get_data["uv_loop_get_data()"]
        A1[呼び出し] --> B1[loop->data を返却]
    end
    subgraph set_data["uv_loop_set_data()"]
        A2[呼び出し] --> B2[loop->data = data]
    end
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | データ所有権 | dataポインタの生存期間はアプリケーション側で管理する | 常時 |
| BR-02 | 初期値 | uv_loop_init()後、dataフィールドの初期値はNULLである | ループ初期化直後 |
| BR-03 | スレッドセーフ | set/getの組み合わせはスレッドセーフではないため、呼び出し側で同期が必要 | マルチスレッド環境 |

### 計算ロジック

特になし。フィールドの直接読み書きのみ。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | - | エラーを返さない | - |

### リトライ仕様

リトライ不要。

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

該当なし。

## パフォーマンス要件

O(1)の定数時間。構造体フィールドの直接アクセスのみ。

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

`data` フィールドに格納するポインタの内容については、アプリケーション側で適切に管理する必要がある。libuv側ではポインタの検証を行わない。

## 備考

- `uv_loop_t` 構造体の `data` フィールドは `UV_HANDLE_FIELDS` マクロ内ではなく、`uv_loop_s` 構造体の先頭に直接定義されている
- ハンドルにも同様の `data` フィールドがあり（`uv_handle_get_data()`/`uv_handle_set_data()`）、使用パターンは同一

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | L1958-1959: uv_loop_get_data()/uv_loop_set_data() の関数宣言 |

**読解のコツ**: `uv_loop_t` 構造体の `data` フィールドは `void*` 型で、構造体の先頭付近にpublicフィールドとして定義されている。

#### Step 2: 実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | L113-119: getter/setterの実装。loop->dataフィールドの直接操作 |

**主要処理フロー**:
1. **113行目**: `uv_loop_get_data()` - `loop->data` を返却
2. **117行目**: `uv_loop_set_data()` - `loop->data = data` で設定

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

```
uv_loop_get_data(loop)       [src/uv-data-getter-setters.c:113]
    └─ return loop->data

uv_loop_set_data(loop, data) [src/uv-data-getter-setters.c:117]
    └─ loop->data = data
```

### データフロー図

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

const uv_loop_t* loop ────────> loop->data 読取 ────────> void* (ユーザーデータ)

uv_loop_t* loop, void* data ──> loop->data = data ──────> (なし)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | 公開API宣言（L1958-1959） |
| uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | ソース | getter/setter実装（L113-119） |
