# 機能設計書 7-イベントループ存続確認

## 概要

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

### 本機能の処理概要

`uv_loop_alive()`は、イベントループにアクティブなハンドルやリクエストがあるかどうかを確認する関数である。内部関数`uv__loop_alive()`をそのまま呼び出すラッパーとして実装されている。

**業務上の目的・背景**：イベントループが処理すべき作業を持っているかを外部から確認する必要がある場面で使用される。`uv_run()`が`UV_RUN_ONCE`や`UV_RUN_NOWAIT`で使用される場合、戻り後にループが引き続き処理を必要とするか判定するのに役立つ。

**機能の利用シーン**：
- `UV_RUN_ONCE`/`UV_RUN_NOWAIT`モードでイベントループを使用する際の継続判定
- アプリケーション独自のメインループ内でのイベントループ状態監視
- デバッグ時のイベントループ状態確認

**主要な処理内容**：
1. アクティブなハンドルの有無確認（`uv__has_active_handles()`）
2. アクティブなリクエストの有無確認（`uv__has_active_reqs()`）
3. 保留中キュー（pending_queue）の空チェック
4. クロージング中ハンドル（closing_handles）の有無確認

**関連システム・外部連携**：特になし。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | イベントループ | 主機能 | uv_loop_alive()によるアクティブハンドル・リクエスト有無確認のAPI定義 |

## 機能種別

状態照会

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | アクティブな処理がある場合は非0（true）、ない場合は0（false） |

### 出力先

関数の戻り値。

## 処理フロー

### 処理シーケンス

```
1. 4条件のOR判定
   a. uv__has_active_handles(loop) - アクティブハンドルが1つ以上ある
   b. uv__has_active_reqs(loop) - アクティブリクエストが1つ以上ある
   c. !uv__queue_empty(&loop->pending_queue) - 保留中キューが空でない
   d. loop->closing_handles != NULL - クロージング中ハンドルがある
2. いずれかがtrueなら非0を返却、すべてfalseなら0を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{active_handles > 0?}
    B -->|Yes| G[非0を返却]
    B -->|No| C{active_reqs > 0?}
    C -->|Yes| G
    C -->|No| D{pending_queue非空?}
    D -->|Yes| G
    D -->|No| E{closing_handles != NULL?}
    E -->|Yes| G
    E -->|No| F[0を返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 4条件OR判定 | 4つの条件のいずれかが真であればループは生存と判定する | 常時 |
| BR-02 | uv_run()との一貫性 | uv_run()内部でも同じuv__loop_alive()が使用される | 常時 |

### 計算ロジック

```c
return uv__has_active_handles(loop) ||
       uv__has_active_reqs(loop) ||
       !uv__queue_empty(&loop->pending_queue) ||
       loop->closing_handles != NULL;
```

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

該当なし。

## エラー処理

### エラーケース一覧

エラーケースなし。判定処理は常に成功する。

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

各チェックは定数時間で完了する軽量な操作。

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

特になし。入力がconst修飾されており、ループ状態を変更しない。

## 備考

- `uv_loop_alive()`の戻り値は`uv_run()`の戻り値と同じ意味を持つ
- 内部ハンドル（`UV_HANDLE_INTERNAL`）もactive_handlesのカウントに含まれる可能性があるが、通常はunrefされている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **1945行目**: `active_handles`フィールド |
| 1-2 | uv.h | `include/uv.h` | **1947-1950行目**: `active_reqs`フィールド（union、countメンバ） |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | **306行目**: `uv_loop_alive()`のAPI宣言 |
| 2-2 | core.c | `src/unix/core.c` | **422-424行目**: `uv_loop_alive()`の実装。`uv__loop_alive(loop)`を直接呼び出す |

**主要処理フロー**:
1. **423行目**: `return uv__loop_alive(loop)` - 内部関数への委譲

#### Step 3: 内部実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.c | `src/unix/core.c` | **393-398行目**: `uv__loop_alive()`の実装。4条件のOR演算 |

**主要処理フロー**:
- **394行目**: `uv__has_active_handles(loop)` - active_handles > 0
- **395行目**: `uv__has_active_reqs(loop)` - active_reqs.count > 0
- **396行目**: `!uv__queue_empty(&loop->pending_queue)` - 保留中キュー非空
- **397行目**: `loop->closing_handles != NULL` - クロージング中ハンドル存在

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

```
uv_loop_alive(loop)                      [src/unix/core.c:422]
    |
    └── uv__loop_alive(loop)             [src/unix/core.c:393]
            |
            +-- uv__has_active_handles() [マクロ]
            +-- uv__has_active_reqs()    [マクロ]
            +-- uv__queue_empty()        [インライン]
            └── closing_handles比較      [フィールド参照]
```

### データフロー図

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

const uv_loop_t*    -->  4条件OR判定                     -->  int (非0/0)
                         |
                         +-- active_handles > 0
                         +-- active_reqs.count > 0
                         +-- pending_queue非空
                         +-- closing_handles != NULL
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | uv_loop_alive()のAPI宣言 |
| core.c | `src/unix/core.c` | ソース | uv_loop_alive()およびuv__loop_alive()の実装 |
