# 機能設計書 83-タイマーリピート間隔制御

## 概要

本ドキュメントは、libuvにおけるタイマーリピート間隔制御機能（uv_timer_set_repeat/uv_timer_get_repeat）の設計仕様を記述する。これらの関数はタイマーハンドルのリピート間隔を動的に設定・取得する。

### 本機能の処理概要

**業務上の目的・背景**：タイマーのリピート間隔を動的に変更する必要がある場面は多い。例えば、ネットワーク接続のリトライ間隔を指数バックオフで増加させたり、負荷状況に応じてポーリング間隔を調整したりする場合である。uv_timer_set_repeat()とuv_timer_get_repeat()はこのような動的な間隔変更を可能にする。

**機能の利用シーン**：指数バックオフによるリトライ間隔の動的変更、負荷に応じたポーリング間隔の調整、タイマー発火前のリピート間隔の事前設定、現在のリピート間隔の監視・ロギングなどで使用される。

**主要な処理内容**：
1. uv_timer_set_repeat(): handle->repeatフィールドに新しいリピート間隔をミリ秒単位で設定する
2. uv_timer_get_repeat(): handle->repeatフィールドの現在値をミリ秒単位で返す

**関連システム・外部連携**：libuvのタイマーサブシステム内部で完結する。設定した値はuv_timer_again()やuv__run_timers()経由でのタイマー再開時に使用される。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | タイマー | 主機能 | uv_timer_set_repeat()/uv_timer_get_repeat()によるリピート間隔制御のAPI定義 |

## 機能種別

プロパティ設定・取得

## 入力仕様

### 入力パラメータ

#### uv_timer_set_repeat

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | uv_timer_t* | Yes | 対象のタイマーハンドル | NULLであってはならない |
| repeat | uint64_t | Yes | リピート間隔（ミリ秒）。0でワンショット | 特になし |

#### uv_timer_get_repeat

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

### 入力データソース

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

## 出力仕様

### 出力データ

#### uv_timer_set_repeat

| 項目名 | 型 | 説明 |
|--------|-----|------|
| なし | void | 戻り値なし |

#### uv_timer_get_repeat

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | uint64_t | 現在のリピート間隔（ミリ秒） |

### 出力先

uv_timer_set_repeat: handle->repeatフィールドへの書き込み。uv_timer_get_repeat: 呼び出し元への値返却。

## 処理フロー

### 処理シーケンス

```
uv_timer_set_repeat:
1. handle->repeatに引数repeatの値を代入

uv_timer_get_repeat:
1. handle->repeatの値を返す
```

### フローチャート

```mermaid
flowchart TD
    subgraph set_repeat
    A1[uv_timer_set_repeat] --> B1[handle->repeat = repeat]
    end
    subgraph get_repeat
    A2[uv_timer_get_repeat] --> B2[return handle->repeat]
    end
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-83-01 | 即時反映 | set_repeatで設定した値は次のuv_timer_again()呼び出し時に反映される | 常時 |
| BR-83-02 | 実行中タイマー非影響 | set_repeatは現在実行中のタイムアウトには影響しない | タイマーがアクティブな場合 |
| BR-83-03 | ワンショット化 | repeat値を0に設定するとワンショットタイマーに変更される | repeat = 0の場合 |

### 計算ロジック

特になし。単純なフィールドの読み書き。

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

該当なし。

## エラー処理

### エラーケース一覧

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

### リトライ仕様

リトライ不要。

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

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

## パフォーマンス要件

- 両関数ともO(1)の定数時間操作。

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

特になし。

## 備考

- uv_timer_set_repeat()で値を変更しても、現在実行中のタイマーの残り時間には影響しない。変更はuv_timer_again()が次に呼ばれたとき、またはタイマーが次に発火してリピートする際に反映される。
- repeat値を0にしてuv_timer_again()を呼ぶと、タイマーは再開されない。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **971-974行目**: uv_timer_s構造体。repeatフィールドがリピート間隔を保持する |

**読解のコツ**: repeatフィールドはuv_timer_start()の引数で初期設定され、uv_timer_set_repeat()で動的に変更可能。uv_timer_again()やuv__run_timers()がこの値を参照する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | timer.c | `src/timer.c` | **125-127行目**: uv_timer_set_repeat()の実装。handle->repeatに値を代入するのみ |
| 2-2 | timer.c | `src/timer.c` | **130-132行目**: uv_timer_get_repeat()の実装。handle->repeatを返すのみ |

**主要処理フロー**:
- **126行目**: `handle->repeat = repeat;`（set）
- **131行目**: `return handle->repeat;`（get）

#### Step 3: 値の利用箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | timer.c | `src/timer.c` | **84行目**: uv_timer_start()内でrepeat値がセットされる |
| 3-2 | timer.c | `src/timer.c` | **116-118行目**: uv_timer_again()内でrepeat値が参照される |
| 3-3 | timer.c | `src/timer.c` | **191行目**: uv__run_timers()内でuv_timer_again()経由でrepeat値が使用される |

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

```
uv_timer_set_repeat(handle, repeat)
    +-- handle->repeat = repeat  [直接代入]

uv_timer_get_repeat(handle)
    +-- return handle->repeat    [直接参照]

repeat値の利用先:
    uv_timer_again(handle)
        +-- uv_timer_start(handle, cb, handle->repeat, handle->repeat)
```

### データフロー図

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

uint64_t repeat ───> uv_timer_set_repeat() ───> handle->repeat (更新)
                         |
uv_timer_t* ───────> uv_timer_get_repeat() ───> uint64_t (現在値)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | API宣言（983-984行目） |
| timer.c | `src/timer.c` | ソース | 実装（125-132行目） |
