# 画面設計書 9-タイマー

## 概要

uv_timer_tのAPIリファレンスページ（timer.rst）に関する画面設計書。タイマーハンドルの初期化・開始・停止・再開・リピート制御・残り時間取得のAPI定義を提供する。

### 本画面の処理概要

本画面はlibuvのタイマーハンドル（uv_timer_t）のAPIリファレンスページである。将来の特定時点でコールバックを呼び出すスケジューリング機能を提供し、ワンショットタイマーとリピートタイマーの両方をサポートする。

**業務上の目的・背景**：タイマーはイベント駆動プログラミングにおいて最も基本的な時間制御機構である。タイムアウト処理、定期的なポーリング、遅延実行など多くのユースケースで使用される。libuvのタイマーはイベントループの"now"概念に基づいてスケジューリングされ、オーバーヘッドの補正は行わないがリピートタイマーは相対的に再スケジュールされる特性を持つ。

**画面へのアクセス方法**：APIドキュメント一覧ページ（api.rst）の "uv_timer_t --- Timer handle" リンク押下、または `/timer.html` に直接アクセスする。

**主要な操作・処理内容**：
1. データ型定義の参照 - uv_timer_t, uv_timer_cb の型情報確認
2. タイマー初期化API参照 - uv_timer_init()
3. タイマー開始API参照 - uv_timer_start()のタイムアウト・リピート間隔指定
4. タイマー停止API参照 - uv_timer_stop()
5. タイマー再開API参照 - uv_timer_again()
6. リピート間隔制御API参照 - uv_timer_set_repeat()/uv_timer_get_repeat()
7. 残り時間取得API参照 - uv_timer_get_due_in()

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：Sphinx相互参照を通じてhandle.rst（uv_handle_t基底API）、loop.rst（uv_update_time等）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 79 | タイマー初期化 | 主機能 | uv_timer_init()によるタイマーハンドル初期化のAPI定義 |
| 80 | タイマー開始 | 主機能 | uv_timer_start()によるタイマー開始のAPI定義（タイムアウト・リピート間隔指定） |
| 81 | タイマー停止 | 主機能 | uv_timer_stop()によるタイマー停止のAPI定義 |
| 82 | タイマー再開 | 主機能 | uv_timer_again()によるリピートタイマー再開のAPI定義 |
| 83 | タイマーリピート間隔制御 | 主機能 | uv_timer_set_repeat()/uv_timer_get_repeat()によるリピート間隔制御のAPI定義 |
| 84 | タイマー残り時間取得 | 主機能 | uv_timer_get_due_in()によるタイマー発火までの残り時間取得のAPI定義 |

## 画面種別

APIリファレンスページ（タイマーハンドル）

## URL/ルーティング

- ソースファイル: `docs/src/timer.rst`
- 生成先URL: `/timer.html`
- Sphinxアンカー: `.. _timer:`

## 入出力項目

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| ページタイトル | 出力 | テキスト | "uv_timer_t --- Timer handle" |
| データ型定義 | 出力 | 型定義 | uv_timer_t, uv_timer_cb |
| パブリックメンバ | 出力 | テキスト | N/A（uv_handle_tメンバを参照） |
| API関数定義 | 出力 | 関数シグネチャ+説明 | 7個のAPI関数 |

## 表示項目

### Data types セクション

| データ型 | 説明 |
|----------|------|
| uv_timer_t | タイマーハンドル型 |
| uv_timer_cb | タイマーコールバック型 `void (*uv_timer_cb)(uv_timer_t* handle)` |

### Public members セクション

- N/A と記載。uv_handle_tのメンバ（loop, type, data）が適用される旨の参照リンクあり。

### API セクション

| API関数 | シグネチャ | 説明 | バージョン |
|---------|-----------|------|-----------|
| uv_timer_init | `int uv_timer_init(uv_loop_t* loop, uv_timer_t* handle)` | ハンドル初期化 | - |
| uv_timer_start | `int uv_timer_start(uv_timer_t* handle, uv_timer_cb cb, uint64_t timeout, uint64_t repeat)` | タイマー開始。timeout=0で次のイテレーションで発火。既にアクティブなら更新 | - |
| uv_timer_stop | `int uv_timer_stop(uv_timer_t* handle)` | タイマー停止 | - |
| uv_timer_again | `int uv_timer_again(uv_timer_t* handle)` | リピートタイマー再開。未開始ならUV_EINVAL | - |
| uv_timer_set_repeat | `void uv_timer_set_repeat(uv_timer_t* handle, uint64_t repeat)` | リピート間隔設定（ミリ秒） | - |
| uv_timer_get_repeat | `uint64_t uv_timer_get_repeat(const uv_timer_t* handle)` | リピート間隔取得 | - |
| uv_timer_get_due_in | `uint64_t uv_timer_get_due_in(const uv_timer_t* handle)` | 発火までの残り時間取得（uv_now()相対） | v1.40.0 |

## イベント仕様

### 1-Sphinx相互参照リンク押下

`:c:func:` 参照リンク（uv_update_time等）を押下すると、対応するAPIリファレンスページへ遷移する。`:c:type:` 参照リンク（uv_handle_t）を押下すると、ハンドル基底ページへ遷移する。

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | N/A | N/A | データベースアクセスなし |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| N/A | N/A | N/A | 静的HTMLのため動的メッセージなし |

## 例外処理

本画面は静的リファレンスドキュメントのため、画面固有の例外処理は存在しない。

## 備考

- リピートタイマーはオーバーヘッド補正なし。50ms間隔でコールバックが17ms掛かる場合、次は33ms後に発火
- uv_timer_start()でtimeout=0を指定すると、次のイベントループイテレーションでコールバックが発火する
- uv_timer_start()は既にアクティブなタイマーに対して呼んだ場合、単純にタイマーを更新する（内部でstopしてから再start）
- uv_timer_set_repeat()をコールバック内から呼んでも即座には反映されない
- タイマーはminヒープ（二分ヒープ）で管理されており、最もタイムアウトが近いものが先に処理される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_timer_t構造体の定義。timer_cb, timeout, repeat, start_id メンバ |
| 1-2 | heap-inl.h | `src/heap-inl.h` | タイマー管理に使用されるminヒープの実装 |

**読解のコツ**: タイマーはminヒープ（二分ヒープ）で管理される。`timer_less_than()` 比較関数でtimeoutの小さいものが先に処理される。同一timeoutの場合はstart_idで順序付けされる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | timer.c | `src/timer.c` | 全タイマーAPI関数の実装 |

**主要処理フロー**:
1. **timer.c 57行目**: `uv_timer_init()` - uv__handle_init()でハンドル初期化、timer_cb/timeout/repeatをゼロ初期化
2. **timer.c 67行目**: `uv_timer_start()` - クローズ中/cb==NULL時にUV_EINVAL。uv_timer_stop()で既存タイマーをクリア
3. **timer.c 78行目**: `clamped_timeout = handle->loop->time + timeout` - ループの現在時刻にtimeoutを加算
4. **timer.c 86行目**: `handle->start_id = handle->loop->timer_counter++` - 順序保証用カウンタ
5. **timer.c 88-90行目**: `heap_insert()` - minヒープにタイマーを挿入
6. **timer.c 91行目**: `uv__handle_start()` - ハンドルをアクティブ化
7. **timer.c 97行目**: `uv_timer_stop()` - ヒープからの除去とハンドル停止
8. **timer.c 112行目**: `uv_timer_again()` - repeat値でstop+start
9. **timer.c 135行目**: `uv_timer_get_due_in()` - timeout - loop->timeを計算

#### Step 3: タイマー実行処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | timer.c | `src/timer.c` | uv__run_timers()（164行目）- イベントループからの呼び出し |

**主要処理フロー**:
- **timer.c 164-194行目**: `uv__run_timers()` - ヒープから期限到来タイマーを取り出し、ready_queueに移動後、順次コールバック実行
- **timer.c 172-183行目**: ヒープの最小要素を取り出し、timeout > loop->timeならbreak
- **timer.c 185-193行目**: ready_queueからタイマーを取り出し、uv_timer_again()でリピート処理後、timer_cb(handle)を呼び出し

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

```
uv_timer_init(loop, handle) [src/timer.c:57]
    |
    +-- uv__handle_init(loop, handle, UV_TIMER)
    +-- timer_cb = NULL, timeout = 0, repeat = 0

uv_timer_start(handle, cb, timeout, repeat) [src/timer.c:67]
    |
    +-- uv_timer_stop(handle) [既存タイマー停止]
    +-- clamped_timeout = loop->time + timeout
    +-- heap_insert() [minヒープに挿入]
    +-- uv__handle_start(handle)

uv__run_timers(loop) [src/timer.c:164]
    |
    +-- heap_min() [最小タイムアウト取得]
    +-- uv_timer_stop() [停止]
    +-- uv__queue_insert_tail() [ready_queueへ]
    |
    +-- (ready_queue走査)
            +-- uv_timer_again() [リピート処理]
            +-- handle->timer_cb(handle) [コールバック呼び出し]
```

### データフロー図

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

uv_timer_t*, cb,          --> uv_timer_start()           --> タイマーヒープに登録
timeout, repeat                (ヒープ挿入)

loop->time到達時          --> uv__run_timers()            --> timer_cb(handle)呼び出し
                               (ヒープから取り出し)

uv_timer_t*               --> uv_timer_get_due_in()      --> uint64_t 残り時間(ms)
                               (timeout - loop->time)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| timer.rst | `docs/src/timer.rst` | テンプレート | タイマーページのRSTソース |
| timer.c | `src/timer.c` | ソース | 全タイマーAPI関数の実装 |
| heap-inl.h | `src/heap-inl.h` | ソース | minヒープの実装（タイマー管理用） |
| uv.h | `include/uv.h` | ソース | uv_timer_t型定義 |
| core.c | `src/unix/core.c` | ソース | uv_run()内のuv__run_timers()呼び出し |
