# 機能設計書 79-タイマー初期化

## 概要

uv_timer_init()によりタイマーハンドルを初期化する機能の設計書である。

### 本機能の処理概要

uv_timer_init()は、タイマーハンドルをイベントループに登録し、初期状態に設定する関数である。タイマーハンドルは指定した時間後にコールバックを呼び出すために使用され、ワンショットまたはリピートモードで動作する。初期化後はuv_timer_start()で実際にタイマーを開始する。

**業務上の目的・背景**：非同期プログラミングにおいて、一定時間後の処理実行やポーリング処理の実装は頻繁に必要となる。libuvのタイマーハンドルは、イベントループのminヒープに基づいた効率的なタイマー管理を提供する。これにより、大量のタイマーを同時に管理しつつ、O(log n)の挿入・削除性能を維持できる。

**機能の利用シーン**：
- タイムアウト処理の設定
- 定期的なポーリング・ヘルスチェック
- デバウンス・スロットリング処理
- アニメーションフレームの制御

**主要な処理内容**：
1. uv__handle_init()でハンドル基本初期化（UV_TIMERタイプ）
2. timer_cbをNULLに初期化
3. timeout, repeatを0に初期化
4. ノードキューを初期化

**関連システム・外部連携**：イベントループの内部時刻キャッシュ（uv_now()）。

**権限による制御**：特段の権限制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | タイマー | 主機能 | uv_timer_init()によるタイマーハンドル初期化のAPI定義 |

## 機能種別

リソース初期化処理 - タイマーハンドルの生成と初期設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| loop | uv_loop_t* | Yes | イベントループ | 初期化済みであること |
| handle | uv_timer_t* | Yes | 初期化するタイマーハンドル | 有効なメモリ領域 |

### 入力データソース

関数呼び出し時の引数として渡される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 常に0（成功） |
| handle->timer_cb | uv_timer_cb | NULLに初期化 |
| handle->timeout | uint64_t | 0に初期化 |
| handle->repeat | uint64_t | 0に初期化 |

### 出力先

uv_timer_t構造体が初期化され、イベントループのハンドルキューに登録される。

## 処理フロー

### 処理シーケンス

```
1. uv__handle_init(loop, handle, UV_TIMER)でハンドル基本初期化
   └─ ハンドルタイプをUV_TIMERに設定、ループのハンドルキューに登録
2. handle->timer_cb = NULL
3. handle->timeout = 0
4. handle->repeat = 0
5. uv__queue_init(&handle->node.queue)でキュー初期化
6. return 0
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[uv__handle_init UV_TIMER]
    B --> C[timer_cb = NULL]
    C --> D[timeout = 0]
    D --> E[repeat = 0]
    E --> F[queue_init]
    F --> G[return 0]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-79-01 | 常に成功 | uv_timer_init()は常に0を返す | 常時 |
| BR-79-02 | 非アクティブ初期化 | 初期化直後のタイマーは非アクティブ状態 | 常時 |
| BR-79-03 | ヒープ未登録 | 初期化直後はタイマーヒープに登録されない | 常時 |

### 計算ロジック

特段の計算ロジックはない。

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

該当なし。

## エラー処理

### エラーケース一覧

uv_timer_init()はエラーを返さない。常に0を返す。

### リトライ仕様

リトライは不要。

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

該当なし。

## パフォーマンス要件

初期化処理はO(1)の軽量な操作である。

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

特段のセキュリティ考慮はない。

## 備考

- タイマーハンドルはヒープ（バイナリminヒープ）で管理される。初期化時点ではヒープに登録されず、uv_timer_start()呼び出し時にヒープに挿入される
- uv_timer_t構造体にはUV_HANDLE_FIELDSとUV_TIMER_PRIVATE_FIELDSが含まれる

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **L971-974**: uv_timer_s構造体。UV_HANDLE_FIELDS + UV_TIMER_PRIVATE_FIELDS |
| 1-2 | heap-inl.h | `src/heap-inl.h` | **L27-43**: ヒープノード構造体とヒープ構造体。タイマーの優先度キュー管理の基盤 |

**読解のコツ**: UV_TIMER_PRIVATE_FIELDSには、timer_cb, timeout, repeat, start_id, node(heap/queue union)が含まれる。ヒープノードはleft/right/parentのポインタで構成される二分ヒープである。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | timer.c | `src/timer.c` | **L57-64**: uv_timer_init()の全実装 |

**主要処理フロー**:
1. **58行目**: uv__handle_init(loop, handle, UV_TIMER)
2. **59行目**: handle->timer_cb = NULL
3. **60行目**: handle->timeout = 0
4. **61行目**: handle->repeat = 0
5. **62行目**: uv__queue_init(&handle->node.queue)
6. **63行目**: return 0

#### Step 3: 関連するヒープ操作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | timer.c | `src/timer.c` | **L28-34**: timer_heap()ヘルパー。ループからタイマーヒープを取得 |
| 3-2 | timer.c | `src/timer.c` | **L37-54**: timer_less_than()比較関数。タイムアウト値とstart_idで順序を決定 |

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

```
uv_timer_init(loop, handle)              [src/timer.c L57]
    +-- uv__handle_init(loop, handle, UV_TIMER)  [ハンドル基本初期化]
    +-- uv__queue_init(&handle->node.queue)       [キュー初期化]
```

### データフロー図

```
[入力]              [処理]                    [出力]
loop (ループ) ----> uv__handle_init() ------> handle (初期化済み)
handle (未初期化) -> フィールド初期化 -------> timer_cb = NULL
                                        ----> timeout = 0
                                        ----> repeat = 0
                                        ----> return 0
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | uv_timer_t構造体・API宣言（L971-976） |
| timer.c | `src/timer.c` | ソース | uv_timer_init()実装（L57-64）、ヒープ操作全般 |
| heap-inl.h | `src/heap-inl.h` | ヘッダ | バイナリminヒープの実装 |
