# 機能設計書 4-イベントループ停止

## 概要

本ドキュメントは、libuvライブラリにおけるイベントループ停止機能（`uv_stop()`）の設計仕様を記述する。

### 本機能の処理概要

`uv_stop()`は、イベントループの`stop_flag`を設定することで、`uv_run()`による実行中のイベントループを停止する関数である。現在のイテレーションの処理は完了してから停止する。

**業務上の目的・背景**：アプリケーションの終了処理やシグナル受信時など、イベントループを安全に停止させる必要がある場面で使用される。`stop_flag`を設定するだけの軽量な操作であり、コールバック内からも安全に呼び出せる。

**機能の利用シーン**：
- シグナルハンドラ内からアプリケーションを終了する場合
- タイマーコールバック内で条件が満たされた際にループを終了する場合
- 外部条件に応じてイベントループを停止する場合

**主要な処理内容**：
1. `loop->stop_flag`を1に設定する

**関連システム・外部連携**：特になし。`uv_run()`のメインループ条件で`stop_flag`が参照される。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | イベントループ | 主機能 | uv_stop()によるイベントループ停止のAPI定義 |
| 38 | イベントループ応用 | 補助機能 | ループ停止タイミングの説明 |

## 機能種別

状態制御

## 入力仕様

### 入力パラメータ

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

### 入力データソース

`uv_loop_init()`で初期化済みのイベントループ。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| （なし） | void | 戻り値なし |

### 出力先

`loop->stop_flag`フィールドの更新。

## 処理フロー

### 処理シーケンス

```
1. stop_flagの設定
   └─ loop->stop_flag = 1
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[loop->stop_flag = 1]
    B --> C[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 遅延停止 | 現在のイテレーションの処理は完了してから停止する | 常時 |
| BR-02 | 自動リセット | stop_flagはuv_run()終了時に自動的に0にリセットされる | uv_run()終了時 |
| BR-03 | 安全呼び出し | コールバック内からも安全に呼び出せる | 常時 |

### 計算ロジック

特になし。

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

該当なし。

## エラー処理

### エラーケース一覧

エラーケースなし。`stop_flag`の設定は常に成功する。

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

`stop_flag`への代入は単一の整数代入操作であり、実質的にゼロコストである。

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

特になし。

## 備考

- `uv_stop()`を呼び出しても、現在のイテレーション内のI/Oポーリングがブロック中の場合は、そのポーリングが完了するまで待機する
- `uv_run()`の戻り後に再度`uv_run()`を呼び出すと、`stop_flag`は既にリセットされているため正常に実行される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **1954行目**: `uv_loop_s`の`stop_flag`フィールド定義（unsigned int） |

**読解のコツ**: `stop_flag`は`uv_run()`のwhile条件で参照されるため、`uv_run()`の実装と合わせて読む。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | **311行目**: `uv_stop()`のAPI宣言 |
| 2-2 | uv-common.c | `src/uv-common.c` | **638-640行目**: `uv_stop()`の実装。`loop->stop_flag = 1`のみ |

**主要処理フロー**:
1. **639行目**: `loop->stop_flag = 1` - フラグを設定するだけ

#### Step 3: stop_flagの参照箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.c | `src/unix/core.c` | **445行目**: `while (r != 0 && loop->stop_flag == 0)` - メインループ条件 |
| 3-2 | core.c | `src/unix/core.c` | **488-489行目**: `if (loop->stop_flag != 0) loop->stop_flag = 0` - リセット処理 |

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

```
uv_stop(loop)                            [src/uv-common.c:638]
    |
    └── loop->stop_flag = 1
        |
        └── [uv_run()のwhile条件で参照]    [src/unix/core.c:445]
            └── [uv_run()終了時にリセット]  [src/unix/core.c:488]
```

### データフロー図

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

uv_loop_t* loop -->  stop_flag = 1           -->  loop->stop_flag更新
                     |                             |
                     └── uv_run()のwhile条件  -->  ループ終了
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | uv_stop()のAPI宣言、stop_flagの定義 |
| uv-common.c | `src/uv-common.c` | ソース | uv_stop()の実装 |
| core.c | `src/unix/core.c` | ソース | uv_run()でのstop_flag参照 |
