# 画面設計書 23-ファイルシステムポーリング

## 概要

本ドキュメントは、libuvドキュメントサイトにおけるファイルシステムポーリング（`uv_fs_poll_t`）APIリファレンスページの画面設計書である。stat()を用いたファイル変更検出機能のAPI定義を記載する。

### 本画面の処理概要

本ページは、libuvにおけるstat()ベースのファイル変更ポーリング機能のAPIリファレンスを提供する。`uv_fs_event_t`と異なり、カーネルイベント通知を使用せずstat()による定期的なポーリングで変更を検出するため、NFSマウント等のリモートファイルシステムでも動作する。

**業務上の目的・背景**：カーネルベースのファイル監視（inotify、kqueue等）がサポートされないファイルシステム（NFS、CIFS等のリモートファイルシステム）でもファイル変更を検出する必要がある場合に、stat()ベースのポーリング方式が有効である。本ページはその代替手段のAPIリファレンスとして重要である。

**画面へのアクセス方法**：トップページからAPIドキュメント一覧（api.rst）を経由し、ファイルシステムポーリングリンクをクリックして本ページに遷移する。

**主要な操作・処理内容**：
1. FSポーリングハンドルの初期化（`uv_fs_poll_init`）のAPI仕様確認
2. ファイル変更ポーリングの開始（`uv_fs_poll_start`）と停止（`uv_fs_poll_stop`）のAPI仕様確認
3. ポーリング対象パスの取得（`uv_fs_poll_getpath`）のAPI仕様確認
4. コールバック仕様（前回・今回のuv_stat_t比較）の確認

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：ハンドル基底（handle.rst）へのseealsoリンク
- 関連：ファイルシステムイベント（fs_event.rst）との比較参照

**権限による表示制御**：なし（公開ドキュメント）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 118 | FSポーリング初期化 | 主機能 | uv_fs_poll_init()によるstat()ベースポーリング初期化のAPI定義 |
| 119 | FSポーリング開始・停止 | 主機能 | uv_fs_poll_start()/stop()によるファイル変更ポーリング制御のAPI定義 |
| 120 | FSポーリングパス取得 | 主機能 | uv_fs_poll_getpath()によるポーリング対象パス取得のAPI定義 |

## 画面種別

APIリファレンス（詳細表示）

## URL/ルーティング

`/docs/src/fs_poll.rst` (Sphinx生成後: `/fs_poll.html`)

## 入出力項目

| API関数 | パラメータ名 | 型 | 入出力 | 説明 |
|---------|-------------|-----|--------|------|
| uv_fs_poll_init | loop | uv_loop_t* | 入力 | イベントループ |
| uv_fs_poll_init | handle | uv_fs_poll_t* | 出力 | 初期化されるFSポーリングハンドル |
| uv_fs_poll_start | handle | uv_fs_poll_t* | 入力 | FSポーリングハンドル |
| uv_fs_poll_start | poll_cb | uv_fs_poll_cb | 入力 | 変更検知コールバック |
| uv_fs_poll_start | path | const char* | 入力 | 監視対象ファイルパス |
| uv_fs_poll_start | interval | unsigned int | 入力 | ポーリング間隔（ミリ秒） |
| uv_fs_poll_stop | handle | uv_fs_poll_t* | 入力 | 停止するハンドル |
| uv_fs_poll_getpath | handle | uv_fs_poll_t* | 入力 | FSポーリングハンドル |
| uv_fs_poll_getpath | buffer | char* | 出力 | パス格納バッファ |
| uv_fs_poll_getpath | size | size_t* | 入出力 | バッファサイズ/結果長 |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | `uv_fs_poll_t` --- FS Poll handle | ページタイトル |
| 概要説明 | FS Poll handles allow... | FSポーリングの概要とfs_eventとの違い |
| Data types | uv_fs_poll_t, uv_fs_poll_cb | データ型の定義 |
| Public members | N/A | 固有の公開メンバーなし |
| API | 4関数（init, start, stop, getpath） | ポーリング制御の全API |

## イベント仕様

### 1-ファイル変更検知コールバック

`uv_fs_poll_start`で登録したコールバック（`uv_fs_poll_cb`）が、ポーリング間隔ごとにstat()を実行し、前回との差分を検出した際に呼び出される。コールバックにはstatus、前回のuv_stat_t（prev）、今回のuv_stat_t（curr）が渡される。status < 0の場合はファイルが存在しないかアクセスできないことを示す。

### 2-seealsoリンク遷移

ページ末尾の「See also」セクションから `uv_handle_t` の基底APIリファレンスページへ遷移する。

## データベース更新仕様

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

該当なし（本プロジェクトはCライブラリであり、データベースは使用しない）

## メッセージ仕様

| メッセージ種別 | 条件 | 内容 |
|--------------|------|------|
| note | ポーリング間隔 | 最大限の移植性のため、複数秒間隔を推奨。サブ秒間隔では全ての変更を検出できない場合がある |
| versionchanged | uv_fs_poll_getpath | v1.3.0/v1.9.0でのバッファ動作変更 |

## 例外処理

| エラーコード | 発生条件 | 説明 |
|-------------|---------|------|
| UV_ENOBUFS | バッファサイズ不足時 | uv_fs_poll_getpath()でバッファが小さい場合 |
| status < 0 | ファイルアクセス不可 | コールバック内でstatus < 0の場合、パスが存在しないかアクセス不可 |

## 備考

- uv_fs_event_tと異なり、stat()ベースのポーリングはリモートファイルシステムでも動作する
- ポーリング間隔はミリ秒単位で指定するが、サブ秒間隔では全変更を検出できない可能性がある
- status < 0の場合でもウォッチャーは停止しないが、状況が変化するまでコールバックは呼ばれない
- コールバックで渡されるprev/currのuv_stat_tポインタはコールバック実行中のみ有効

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_fs_poll_t, uv_fs_poll_cb, uv_stat_tの定義 |

**読解のコツ**: uv_fs_poll_cbの引数であるuv_stat_tの構造（st_dev, st_mode, st_size等）を理解することが重要。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | fs-poll.c | `src/fs-poll.c` | FSポーリングのプラットフォーム共通実装（init, start, stop, getpath） |

**主要処理フロー**:
- `uv_fs_poll_init()`: ハンドル初期化
- `uv_fs_poll_start()`: タイマーベースのポーリング開始、内部でuv_fs_stat()を定期実行
- `uv_fs_poll_stop()`: タイマー停止
- `uv_fs_poll_getpath()`: 内部保存パスの取得

#### Step 3: 内部のstat呼び出しを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | fs.c (Unix) | `src/unix/fs.c` | uv_fs_stat()のUnix実装 |
| 3-2 | fs.c (Win) | `src/win/fs.c` | uv_fs_stat()のWindows実装 |

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

```
uv_fs_poll_init() [src/fs-poll.c]
    |
    +-- uv__handle_init()

uv_fs_poll_start() [src/fs-poll.c]
    |
    +-- uv_timer_init() [内部タイマー作成]
    +-- uv_timer_start() [定期ポーリング開始]
           |
           +-- poll_cb() [内部コールバック]
                  |
                  +-- uv_fs_stat() [stat()実行]
                  +-- 前回stat結果と比較
                  +-- 変更検出時 → ユーザーコールバック呼び出し
```

### データフロー図

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

監視対象パス ---------> uv_fs_poll_start()
ポーリング間隔             |
                           v
                    uv_timer_t [定期実行]
                           |
                           v
                    uv_fs_stat() [stat呼び出し]
                           |
                           v
                    prev_stat vs curr_stat [比較]
                           |
                           v
変更検出 ------------> uv_fs_poll_cb() -------> アプリケーション通知
                       (status, prev, curr)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| fs_poll.rst | `docs/src/fs_poll.rst` | テンプレート | FSポーリングページのSphinxソース |
| uv.h | `include/uv.h` | ソース | uv_fs_poll_t等の公開API定義 |
| fs-poll.c | `src/fs-poll.c` | ソース | FSポーリングのプラットフォーム共通実装 |
| fs.c (Unix) | `src/unix/fs.c` | ソース | Unix系stat()実装 |
| fs.c (Win) | `src/win/fs.c` | ソース | Windows系stat()実装 |
| api.rst | `docs/src/api.rst` | テンプレート | API一覧ページ（遷移元） |
| handle.rst | `docs/src/handle.rst` | テンプレート | ハンドル基底ページ（参照先） |
| fs_event.rst | `docs/src/fs_event.rst` | テンプレート | FSイベントページ（比較対象） |
