# 機能設計書 118-FSポーリング初期化

## 概要

本ドキュメントは、libuvのstat()ベースのファイル変更ポーリングハンドル初期化機能 `uv_fs_poll_init()` の設計仕様を記述する。タイマー駆動のstat()による変更検知ハンドルの初期化処理について定義する。

### 本機能の処理概要

`uv_fs_poll_init()` は、ファイルシステムポーリングハンドル（uv_fs_poll_t）をイベントループに登録し、stat()ベースのファイル変更検知に使用できる状態に初期化する機能である。FSイベント（kqueue/inotify等）がサポートされない環境や、ネットワークファイルシステム（NFS等）上のファイル監視に有用である。

**業務上の目的・背景**：カーネルベースのファイルシステムイベント通知は高効率だが、ネットワークファイルシステム（NFS, CIFS等）やFUSE等の特殊なファイルシステムでは動作しない場合がある。stat()による定期ポーリングは全てのファイルシステムで動作する汎用的な変更検知メカニズムを提供する。

**機能の利用シーン**：NFSマウント上のファイル監視、FSイベントが使用できない環境でのファイル変更検知、低頻度での設定ファイル更新チェックなど。

**主要な処理内容**：
1. uv__handle_initマクロによるハンドル基本初期化（UV_FS_POLLタイプ設定）
2. poll_ctxのNULL初期化
3. 成功時は0を返す

**関連システム・外部連携**：libuvの内部タイマー機構およびuv_fs_stat()機能。

**権限による制御**：特になし。監視開始時にファイルへのアクセス権が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 23 | ファイルシステムポーリング | 主機能 | uv_fs_poll_init()によるstat()ベースポーリング初期化のAPI定義 |

## 機能種別

初期化処理（ハンドル初期化・リソース確保）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| loop | uv_loop_t* | Yes | イベントループハンドル | NULLでないこと |
| handle | uv_fs_poll_t* | Yes | FSポーリングハンドル | NULLでないこと |

### 入力データソース

ユーザーが確保したuv_fs_poll_t構造体のメモリ。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 常に0（成功） |

### 出力先

handleが初期化され、イベントループに登録される。

## 処理フロー

### 処理シーケンス

```
1. ハンドル初期化
   └─ uv__handle_init(loop, (uv_handle_t*)handle, UV_FS_POLL)
2. ポーリングコンテキスト初期化
   └─ handle->poll_ctx = NULL
3. 成功返却
   └─ return 0
```

### フローチャート

```mermaid
flowchart TD
    A[uv_fs_poll_init 呼び出し] --> B[uv__handle_init: ハンドル基本初期化]
    B --> C[handle->poll_ctx = NULL]
    C --> D[return 0]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-118-1 | 初期化のみ | init関数は初期化のみ行い、ポーリングは開始しない | 常時 |
| BR-118-2 | poll_ctx遅延確保 | ポーリングコンテキストはstart時に確保される | 常時 |

### 計算ロジック

特になし。

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

### 操作別データベース影響一覧

該当なし。

## エラー処理

### エラーケース一覧

本関数はエラーを返さない（常に0を返す）。

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

- 単純なメモリ初期化のため、オーバーヘッドはほぼゼロ

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

- 特になし。

## 備考

- uv_fs_poll_s構造体はUV_HANDLE_FIELDSとvoid* poll_ctxのみで構成される（include/uv.h L1703-1707）
- poll_ctxは内部構造体poll_ctx（src/fs-poll.c L37-49）で、タイマーハンドル、FSリクエスト、statバッファ、パス等を含む
- 同一ハンドルでstart/stopを繰り返すと、previousリンクリストでコンテキストが管理される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **L1700-1707**: uv_fs_poll_s構造体。UV_HANDLE_FIELDSとpoll_ctxのみ |
| 1-2 | fs-poll.c | `src/fs-poll.c` | **L37-49**: struct poll_ctx。parent_handle, busy_polling, interval, start_time, loop, poll_cb, timer_handle, fs_req, statbuf, previous, path |

**読解のコツ**: poll_ctxは可変長構造体。path[1]フィールドは構造体末尾に置かれ、callocで実際のパス長分を追加確保する。previousフィールドはstart/stopの繰り返しで前のコンテキストをリンクリストで保持する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | **L1709**: uv_fs_poll_init()のAPI宣言 |
| 2-2 | fs-poll.c | `src/fs-poll.c` | **L59-63**: uv_fs_poll_init()の実装 |

**主要処理フロー**:
1. **L60**: uv__handle_init(loop, (uv_handle_t*)handle, UV_FS_POLL)
2. **L61**: handle->poll_ctx = NULL
3. **L62**: return 0

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

```
uv_fs_poll_init()                [src/fs-poll.c L59]
    |
    +-- uv__handle_init()        [ハンドル共通初期化マクロ]
         |
         +-- UV_FS_POLLタイプ設定
         +-- フラグ初期化
         +-- ループのハンドルリストに登録
```

### データフロー図

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

uv_loop_t* loop       ──> uv__handle_init()    ──> 初期化されたuv_fs_poll_t
uv_fs_poll_t* handle  ──> poll_ctx = NULL      ──> ループに登録済み
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | uv_fs_poll_init()のAPI宣言、uv_fs_poll_s構造体定義 |
| fs-poll.c | `src/fs-poll.c` | ソース | FSポーリング実装（init/start/stop/getpath） |
