# 機能設計書 84-タイマー残り時間取得

## 概要

本ドキュメントは、libuvにおけるタイマー残り時間取得機能（uv_timer_get_due_in）の設計仕様を記述する。uv_timer_get_due_in()はタイマーが次に発火するまでの残り時間をミリ秒単位で取得する。

### 本機能の処理概要

**業務上の目的・背景**：タイマーが次にいつ発火するかを知ることは、UIでのカウントダウン表示、デバッグ目的でのタイマー状態確認、タイマー残り時間に基づく処理の最適化などに有用である。uv_timer_get_due_in()はこの情報を簡潔に取得する手段を提供する。

**機能の利用シーン**：タイマー発火までの残り時間の表示、タイマーのデバッグ・監視、複数タイマー間の残り時間比較、条件に基づくタイマーの動的管理などで使用される。

**主要な処理内容**：
1. ループの現在時刻（loop->time）とタイマーのタイムアウト値（handle->timeout）を比較する
2. 現在時刻がタイムアウト以上であれば0を返す（既に期限切れ）
3. そうでなければタイムアウト値から現在時刻を差し引いた値を返す

**関連システム・外部連携**：libuvのタイマーサブシステムおよびイベントループの時刻管理と連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | タイマー | 主機能 | uv_timer_get_due_in()によるタイマー発火までの残り時間取得のAPI定義 |

## 機能種別

情報取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | const uv_timer_t* | Yes | 対象のタイマーハンドル | NULLであってはならない |

### 入力データソース

呼び出し元のアプリケーションコードから直接渡されるタイマーハンドルポインタ。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | uint64_t | タイマー発火までの残りミリ秒。既に期限切れの場合は0 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 時刻比較
   └─ loop->time >= handle->timeout かチェック
2a. 期限切れの場合
   └─ 0を返す
2b. まだ期限前の場合
   └─ handle->timeout - loop->time を返す
```

### フローチャート

```mermaid
flowchart TD
    A[uv_timer_get_due_in 呼び出し] --> B{loop->time >= handle->timeout?}
    B -->|Yes| C[return 0]
    B -->|No| D[return handle->timeout - loop->time]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-84-01 | 期限切れゼロ | タイマーが既に期限切れの場合は0を返す | loop->time >= handle->timeout |
| BR-84-02 | 残り時間計算 | 残り時間はtimeout - loop->timeで算出 | loop->time < handle->timeout |
| BR-84-03 | キャッシュ依存 | 結果はloop->timeのキャッシュ値に依存する | 常時 |

### 計算ロジック

```
due_in = (loop->time >= handle->timeout) ? 0 : (handle->timeout - loop->time)
```

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | - | エラーは発生しない | - |

### リトライ仕様

リトライ不要。

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

トランザクション制御なし。

## パフォーマンス要件

- O(1)の定数時間操作。

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

特になし。

## 備考

- 返される値はイベントループの内部時刻キャッシュ（loop->time）に基づくため、uv_update_time()を呼ばない限り厳密にリアルタイムではない。
- タイマーが停止中（非アクティブ）の場合でも、最後に設定されたtimeout値に基づいて残り時間を計算する。
- handle->timeoutはuv_timer_start()で設定される絶対時刻（loop->time + timeout引数）であり、相対時刻ではない。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **971-974行目**: uv_timer_s構造体。timeoutフィールドは発火予定の絶対時刻を保持 |

**読解のコツ**: timeoutフィールドの値はuv_timer_start()で `loop->time + timeout引数` として計算される絶対時刻である。相対時間ではないことに注意。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | timer.c | `src/timer.c` | **135-140行目**: uv_timer_get_due_in()関数の実装 |

**主要処理フロー**:
1. **136行目**: `handle->loop->time >= handle->timeout` で期限切れチェック
2. **137行目**: 期限切れなら0を返す
3. **139行目**: `handle->timeout - handle->loop->time` を返す

#### Step 3: timeout値の設定元を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | timer.c | `src/timer.c` | **78-80行目**: uv_timer_start()内でclamped_timeoutが計算される。`loop->time + timeout`でオーバーフロー対策あり |

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

```
uv_timer_get_due_in(handle)
    |
    +-- handle->loop->time を参照
    +-- handle->timeout を参照
    +-- 差分を計算して返す（または0）
```

### データフロー図

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

uv_timer_t* ───> uv_timer_get_due_in()        ───> uint64_t
  handle            |                                (残りミリ秒 or 0)
                    +-- loop->time (現在時刻)
                    +-- handle->timeout (発火時刻)
                    +-- 差分計算
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | uv_timer_get_due_in()のAPI宣言（985行目） |
| timer.c | `src/timer.c` | ソース | uv_timer_get_due_in()の実装（135-140行目） |
