# 機能設計書 16-ハンドルアクティブ判定

## 概要

`uv_is_active()`によりハンドルがアクティブかどうかを判定する機能の設計書である。

### 本機能の処理概要

**業務上の目的・背景**：libuvのハンドルは開始（start）されるとアクティブ状態になり、停止（stop）されると非アクティブになる。アプリケーションはハンドルの現在の状態を確認し、条件に応じた制御を行う必要がある。本機能はハンドルのアクティブ状態を判定するためのAPIを提供する。

**機能の利用シーン**：ハンドルの操作前にアクティブ状態を確認する場合、デバッグログの出力時にハンドル状態を表示する場合、イベントループの状態を診断する場合などに使用される。ハンドル型によってアクティブの意味が異なる（タイマー: start済み、TCP: listen/connect/read中等）。

**主要な処理内容**：
1. ハンドルの`flags`フィールドの`UV_HANDLE_ACTIVE`ビットをチェックする
2. Unix: `(flags & UV_HANDLE_ACTIVE) != 0` を返す
3. Windows: `(flags & UV_HANDLE_ACTIVE) && !(flags & UV_HANDLE_CLOSING)` を返す

**関連システム・外部連携**：特になし。内部フラグの参照のみ。

**権限による制御**：特になし。公開APIとして任意のタイミングで呼び出し可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | ハンドル基底 | 主機能 | uv_is_active()によるハンドルアクティブ状態判定のAPI定義 |

## 機能種別

データ取得（状態判定）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | const uv_handle_t* | Yes | 対象のハンドル | NULLチェックなし |

### 入力データソース

呼び出し元から渡されるハンドル構造体ポインタ。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | アクティブなら非ゼロ、非アクティブなら0 |

### 出力先

関数の戻り値として呼び出し元へ返却。

## 処理フロー

### 処理シーケンス

```
1. uv_is_active()が呼び出される
2. Unix: uv__is_active()マクロを呼ぶ
   └─ (handle->flags & UV_HANDLE_ACTIVE) != 0 を返す
3. Windows: ACTIVEフラグかつCLOSINGでないことを確認
   └─ (flags & UV_HANDLE_ACTIVE) && !(flags & UV_HANDLE_CLOSING) を返す
```

### フローチャート

```mermaid
flowchart TD
    A[uv_is_active 呼び出し] --> B{UV_HANDLE_ACTIVE フラグ?}
    B -->|セット| C[非ゼロを返す Unix]
    B -->|未セット| D[0を返す]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-16-01 | アクティブの定義 | ハンドルがstart等で開始されるとACTIVEフラグがセットされる | 常時 |
| BR-16-02 | プラットフォーム差異 | Windows版はCLOSINGフラグも考慮する（Unix版は考慮しない） | プラットフォームにより異なる |
| BR-16-03 | クローズ中の状態 | Unix版ではクローズ中でもACTIVEフラグが残っている場合がある | CLOSINGフラグセット後 |

### 計算ロジック

Unix: `(handle->flags & UV_HANDLE_ACTIVE) != 0`
Windows: `(handle->flags & UV_HANDLE_ACTIVE) && !(handle->flags & UV_HANDLE_CLOSING)`

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

該当なし。

## エラー処理

### エラーケース一覧

本関数はエラーを返さない。

### リトライ仕様

リトライ不要。

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

該当なし。

## パフォーマンス要件

O(1)の定数時間。ビットフラグの確認のみ。

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

特になし。

## 備考

- ACTIVEフラグは`uv__handle_start()`マクロでセットされ、`uv__handle_stop()`マクロで解除される
- 各ハンドル型のstart/stop関数内でこれらマクロが呼ばれる
- 参照: include/uv.h L496

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv-common.h | `src/uv-common.h` | **L84**: UV_HANDLE_ACTIVE = 0x00000004 の定義 |

**読解のコツ**: ACTIVEフラグはビット2に対応する。`uv__handle_start()`（L288-294）でセットされ、`uv__handle_stop()`（L296-302）で解除される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | **L496**: uv_is_active()のAPI宣言 |
| 2-2 | core.c (unix) | `src/unix/core.c` | **L500-502**: Unix実装。uv__is_active()マクロに委譲 |
| 2-3 | handle.c (win) | `src/win/handle.c` | **L61-64**: Windows実装。ACTIVE && !CLOSINGを確認 |

**主要処理フロー**:
- **500行目**: `int uv_is_active(const uv_handle_t* handle)` 関数定義
- **501行目**: `return uv__is_active(handle);` マクロ呼び出し

#### Step 3: ACTIVEフラグの設定元を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | uv-common.h | `src/uv-common.h` | **L274-275**: `uv__is_active()`マクロ定義 |
| 3-2 | uv-common.h | `src/uv-common.h` | **L288-294**: `uv__handle_start()`マクロ - ACTIVEフラグセット |
| 3-3 | uv-common.h | `src/uv-common.h` | **L296-302**: `uv__handle_stop()`マクロ - ACTIVEフラグ解除 |

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

```
uv_is_active(handle)           [src/unix/core.c:500]
    │
    └─ uv__is_active(h)        [src/uv-common.h:274 マクロ]
         └─ (h->flags & UV_HANDLE_ACTIVE) != 0
```

### データフロー図

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

const uv_handle_t* handle ──> flags & UV_HANDLE_ACTIVE ──> int (0 or 非ゼロ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | 公開API宣言（L496） |
| core.c (unix) | `src/unix/core.c` | ソース | Unix実装（L500-502） |
| handle.c (win) | `src/win/handle.c` | ソース | Windows実装（L61-64） |
| uv-common.h | `src/uv-common.h` | ヘッダ | マクロ定義（L274-275, L288-302） |
