# 機能設計書 115-FSイベント初期化

## 概要

本ドキュメントは、libuvのファイルシステムイベントハンドル初期化機能 `uv_fs_event_init()` の設計仕様を記述する。カーネルベースのファイル変更監視ハンドルの初期化処理について定義する。

### 本機能の処理概要

`uv_fs_event_init()` は、ファイルシステムイベントハンドル（uv_fs_event_t）をイベントループに登録し、ファイル/ディレクトリの変更監視に使用できる状態に初期化する機能である。初期化されたハンドルはuv_fs_event_start()で監視を開始できる。

**業務上の目的・背景**：ファイルの変更をリアルタイムに検知する必要があるアプリケーション（ファイル監視ツール、ホットリロード機能、設定ファイルの自動再読み込み等）において、カーネルレベルのファイルシステムイベント通知メカニズム（inotify/kqueue/FSEvents等）を利用するためのハンドルを準備する。

**機能の利用シーン**：ファイル監視機能の初期セットアップ時、ホットリロード機能の初期化時、ログファイルの更新監視開始前などで使用される。

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

**関連システム・外部連携**：各OS固有のファイルシステムイベント通知メカニズム（Linux: inotify, macOS: kqueue/FSEvents, Windows: ReadDirectoryChangesW）。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | ファイルシステムイベント | 主機能 | uv_fs_event_init()によるFSイベントハンドル初期化のAPI定義 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. ハンドル初期化
   └─ uv__handle_init(loop, handle, UV_FS_EVENT)
   └─ ハンドルタイプ設定、フラグ初期化、ループへの登録
2. 成功返却
   └─ return 0
```

### フローチャート

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

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-115-1 | 初期化のみ | init関数は初期化のみ行い、監視は開始しない | 常時 |
| BR-115-2 | ループ登録 | 初期化時にハンドルがイベントループのハンドルリストに登録される | 常時 |

### 計算ロジック

特になし。

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

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

該当なし。

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

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

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

- 特になし。

## 備考

- kqueue実装（macOS/BSD）ではuv__handle_initのみで初期化が完了する
- Linux実装ではinotify関連の追加初期化が行われる場合がある
- macOS環境ではFSEventsとkqueueの2つのバックエンドが存在し、ディレクトリ監視時にFSEventsが優先される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **L1742-1767**: uv_fs_event_flags列挙型（WATCH_ENTRY, STAT, RECURSIVE） |
| 1-2 | uv.h | `include/uv.h` | **L1770**: uv_fs_event_init()のAPI宣言 |

**読解のコツ**: uv_fs_event_tはUV_HANDLE_FIELDSマクロでハンドル共通フィールドを持つ。プラットフォーム固有のフィールドはUV_FS_EVENT_PRIVATE_FIELDSで定義される（kqueue: event_watcher, macOS: cf_cb/realpath等）。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kqueue.c | `src/unix/kqueue.c` | **L537-540**: kqueue実装のuv_fs_event_init() |

**主要処理フロー**:
1. **L538**: uv__handle_init(loop, (uv_handle_t*)handle, UV_FS_EVENT)
2. **L539**: return 0

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

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

### データフロー図

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

uv_loop_t* loop    ──> uv__handle_init()   ──> 初期化されたuv_fs_event_t
uv_fs_event_t*     ──>                     ──> ループに登録済み
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | uv_fs_event_init()のAPI宣言、フラグ定義 |
| kqueue.c | `src/unix/kqueue.c` | ソース | macOS/BSD実装 |
| linux.c | `src/unix/linux.c` | ソース | Linux(inotify)実装 |
| fs-event.c | `src/win/fs-event.c` | ソース | Windows実装 |
| no-fsevents.c | `src/unix/no-fsevents.c` | ソース | FSEvents未対応環境のスタブ |
