# 機能設計書 11-バックエンドFD取得

## 概要

libuvイベントループが内部で使用するI/Oポーリングのバックエンドファイルディスクリプタを取得する機能(`uv_backend_fd()`)の設計書である。

### 本機能の処理概要

**業務上の目的・背景**：libuvのイベントループは内部的にOS固有のI/O多重化メカニズム（Linux: epoll、macOS: kqueue、Windows: IOCP）を使用してI/Oイベントを監視している。外部のイベントループ（GLib、Qt等）にlibuvを組み込む場合、libuvのI/Oポーリングに使用しているファイルディスクリプタを取得し、外部のイベントループにそのFDを登録する必要がある。本機能はそのためのFDを提供する。

**機能の利用シーン**：libuvのイベントループを別のイベント駆動フレームワークに統合する際に利用される。例えば、GLibのメインループにlibuvのFDを登録して、GLibのイベントループがlibuvのI/Oイベントも検出できるようにする場合などである。また、`uv_backend_timeout()`と組み合わせて、外部ループからlibuvのI/Oポーリングを駆動する際にも使用される。

**主要な処理内容**：
1. イベントループ構造体(`uv_loop_t`)の`backend_fd`フィールドを直接返却する
2. Unix系OSではepoll/kqueue等のFDを返し、Windowsでは常に-1を返す

**関連システム・外部連携**：OS固有のI/O多重化機構（epoll_create、kqueue等）によって生成されたファイルディスクリプタに依存する。外部イベントループとの統合時に使用される。

**権限による制御**：特になし。公開APIとして任意のスレッドから呼び出し可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | イベントループ | 主機能 | uv_backend_fd()によるI/Oポーリング用FD取得のAPI定義 |
| 38 | イベントループ応用 | 補助機能 | 他イベントループへの組み込み時のバックエンドFD使用例 |

## 機能種別

データ取得（読み取り専用）

## 入力仕様

### 入力パラメータ

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

### 入力データソース

呼び出し元から渡されるイベントループ構造体ポインタ。`uv_loop_init()`または`uv_default_loop()`で初期化済みである必要がある。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | バックエンドのファイルディスクリプタ。Unix系ではepoll/kqueue FD、Windowsでは-1 |

### 出力先

関数の戻り値として呼び出し元へ返却。

## 処理フロー

### 処理シーケンス

```
1. uv_backend_fd()が呼び出される
   └─ 引数としてconst uv_loop_t* loopを受け取る
2. loop->backend_fdを直接返却する
   └─ Unix系: epoll/kqueue等のFD値（0以上の整数）
   └─ Windows: 常に-1を返す
```

### フローチャート

```mermaid
flowchart TD
    A[uv_backend_fd 呼び出し] --> B{プラットフォーム}
    B -->|Unix| C[loop->backend_fd を返却]
    B -->|Windows| D[-1 を返却]
    C --> E[終了]
    D --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-11-01 | プラットフォーム依存 | Windowsでは常に-1を返し、Unix系ではepoll/kqueue等のFDを返す | 常時 |
| BR-11-02 | 読み取り専用 | ループの状態を変更しない純粋な読み取り操作である | 常時 |

### 計算ロジック

特になし。構造体フィールドの直接返却のみ。

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

該当なし（インメモリのデータ構造操作のみ）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| -1 | プラットフォーム非対応 | Windowsで呼び出した場合 | 戻り値-1を確認し、Windows環境では本機能を使用しない |

### リトライ仕様

リトライ不要。

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

該当なし。

## パフォーマンス要件

O(1)の定数時間で完了。構造体フィールドの読み取りのみであるため、パフォーマンス上の懸念はない。

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

返却されるファイルディスクリプタは、libuv内部のI/Oポーリング機構が使用するものであり、外部から不正に操作するとイベントループの動作が破壊される可能性がある。読み取り目的でのみ使用すべきである。

## 備考

- `uv_backend_fd()`と`uv_backend_timeout()`は対で使用されることが多い
- 外部イベントループとの統合パターンでは、`uv_backend_fd()`の返り値をpoll/select等に渡し、`uv_backend_timeout()`をタイムアウト値として使用する
- Unix系ではイベントループ初期化時（`uv__platform_loop_init()`）にバックエンドFDが生成される

---

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

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

### 推奨読解順序

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

イベントループ構造体の`backend_fd`フィールドの位置づけを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | L1941-1956: `uv_loop_s`構造体の定義。`backend_fd`はUV_LOOP_PRIVATE_FIELDSマクロ内に含まれる |
| 1-2 | unix.h | `include/uv/unix.h` | UV_LOOP_PRIVATE_FIELDSマクロの定義。`backend_fd`フィールドが宣言されている |

**読解のコツ**: libuvではプラットフォーム固有フィールドを`UV_*_PRIVATE_FIELDS`マクロで定義する設計パターンが一貫して使用されている。`uv_loop_s`構造体の末尾にある`UV_LOOP_PRIVATE_FIELDS`を展開して確認するとよい。

#### Step 2: エントリーポイントを理解する（Unix実装）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | **L320**: `uv_backend_fd()`のAPI宣言 |
| 2-2 | core.c | `src/unix/core.c` | **L388-390**: `uv_backend_fd()`のUnix実装。`loop->backend_fd`を返すだけの1行関数 |

**主要処理フロー**:
1. **388行目**: `int uv_backend_fd(const uv_loop_t* loop)` 関数定義
2. **389行目**: `return loop->backend_fd;` で直接フィールドを返却

#### Step 3: バックエンドFDの初期化元を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | linux.c | `src/unix/linux.c` | `uv__platform_loop_init()`内で`epoll_create1()`を呼びbackend_fdを設定 |
| 3-2 | kqueue.c | `src/unix/kqueue.c` | `uv__platform_loop_init()`内で`kqueue()`を呼びbackend_fdを設定 |

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

```
uv_backend_fd(loop)              [src/unix/core.c:388]
    │
    └─ loop->backend_fd を返却   [構造体フィールドの直接参照]
       （設定元: uv__platform_loop_init() → epoll_create1() / kqueue()）
```

### データフロー図

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

const uv_loop_t* loop ──> loop->backend_fd 読取 ──> int (FD値 or -1)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | 公開API宣言（L320） |
| core.c (unix) | `src/unix/core.c` | ソース | Unix系プラットフォーム実装（L388-390） |
| core.c (win) | `src/win/core.c` | ソース | Windowsプラットフォーム実装 |
| linux.c | `src/unix/linux.c` | ソース | Linux固有のbackend_fd初期化（epoll） |
| kqueue.c | `src/unix/kqueue.c` | ソース | macOS/BSD固有のbackend_fd初期化（kqueue） |
| unix.h | `include/uv/unix.h` | ヘッダ | UV_LOOP_PRIVATE_FIELDSにbackend_fdが含まれる |
