# 機能設計書 9-時刻更新

## 概要

本ドキュメントは、libuvライブラリにおける時刻更新機能（`uv_update_time()`）の設計仕様を記述する。

### 本機能の処理概要

`uv_update_time()`は、イベントループの内部時刻キャッシュを更新する関数である。内部関数`uv__update_time()`を呼び出し、高精度タイマーから現在時刻を取得してループ構造体の`time`フィールド（ミリ秒精度）に格納する。

**業務上の目的・背景**：イベントループは各イテレーションの開始時に時刻を1回キャッシュし、そのイテレーション中は同じ時刻を使用する。これによりシステムコールの呼び出し回数を削減し、パフォーマンスを向上させている。しかし、コールバック内で長時間の処理を行った場合、キャッシュされた時刻と実際の時刻に乖離が生じるため、手動で更新する必要がある。

**機能の利用シーン**：
- コールバック内で長時間のブロッキング処理を行った後にタイマーの精度を改善したい場合
- イベントループの時刻キャッシュを手動でリフレッシュしたい場合

**主要な処理内容**：
1. `uv__hrtime(UV_CLOCK_FAST)`で高速クロックからナノ秒精度の時刻を取得
2. ナノ秒をミリ秒に変換（1000000で除算）
3. `loop->time`に格納

**関連システム・外部連携**：プラットフォーム固有の高精度タイマー（macOS: `mach_absolute_time()`、Linux: `clock_gettime(CLOCK_MONOTONIC)`等）。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | イベントループ | 主機能 | uv_update_time()による内部時刻キャッシュ更新のAPI定義 |

## 機能種別

状態更新

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| loop | uv_loop_t* | Yes | 時刻を更新するイベントループ | NULLチェックなし |

### 入力データソース

システムのモノトニッククロック（単調増加時計）。

## 出力仕様

### 出力データ

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

### 出力先

`loop->time`フィールド（uint64_t、ミリ秒）の更新。

## 処理フロー

### 処理シーケンス

```
1. 高速クロックからナノ秒精度の時刻取得
   └─ uv__hrtime(UV_CLOCK_FAST)
2. ミリ秒への変換
   └─ / 1000000
3. loop->timeに格納
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[uv__hrtime UV_CLOCK_FAST]
    B --> C[ナノ秒→ミリ秒変換]
    C --> D[loop->time = 結果]
    D --> E[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 自動更新 | uv_run()の各イテレーションで自動的にuv__update_time()が呼ばれる | uv_run()実行中 |
| BR-02 | 手動更新 | ユーザーが明示的に呼び出して時刻キャッシュを更新できる | コールバック内 |
| BR-03 | モノトニック | 使用されるクロックはモノトニック（単調増加）であり、システム時刻変更の影響を受けない | 常時 |
| BR-04 | UV_CLOCK_FAST | 高速だがやや精度が低いクロックソースを使用する（ミリ秒精度で十分） | 常時 |

### 計算ロジック

```c
loop->time = uv__hrtime(UV_CLOCK_FAST) / 1000000;
```

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

該当なし。

## エラー処理

### エラーケース一覧

エラーケースなし。戻り値はvoid。

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

`UV_CLOCK_FAST`を指定することで、`UV_CLOCK_PRECISE`よりも低コストで時刻を取得する。Linux環境ではvDSOを通じてユーザー空間で完結する場合がある。

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

特になし。

## 備考

- `uv_update_time()`は`uv_run()`内部で自動的に呼ばれるため、通常は明示的に呼び出す必要はない
- `loop->time`はタイマー処理の基準時刻として使用される
- `UV_CLOCK_FAST`と`UV_CLOCK_PRECISE`の精度差はプラットフォーム依存

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | UV_LOOP_PRIVATE_FIELDSマクロ内の`time`フィールド（uint64_t）。ミリ秒精度のキャッシュ時刻 |

**読解のコツ**: `time`フィールドはUV_LOOP_PRIVATE_FIELDSマクロ内で定義されており、`include/uv/unix.h`を参照する必要がある。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | **317行目**: `uv_update_time()`のAPI宣言 |
| 2-2 | core.c | `src/unix/core.c` | **495-497行目**: `uv_update_time()`の実装。`uv__update_time(loop)`への委譲 |

**主要処理フロー**:
1. **496行目**: `uv__update_time(loop)` - 内部インライン関数の呼び出し

#### Step 3: 内部実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | internal.h | `src/unix/internal.h` | **467-471行目**: `uv__update_time()`のインライン実装 |

**主要処理フロー**:
- **470行目**: `loop->time = uv__hrtime(UV_CLOCK_FAST) / 1000000` - ナノ秒からミリ秒への変換と格納

#### Step 4: uv_run()内での使用箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | core.c | `src/unix/core.c` | **434行目**: ループ開始前の時刻更新 |
| 4-2 | core.c | `src/unix/core.c` | **441行目**: DEFAULTモード初回の時刻更新 |
| 4-3 | core.c | `src/unix/core.c` | **477行目**: 各イテレーション末尾での時刻更新 |

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

```
uv_update_time(loop)                     [src/unix/core.c:495]
    |
    └── uv__update_time(loop)            [src/unix/internal.h:467]
            |
            └── uv__hrtime(UV_CLOCK_FAST) [プラットフォーム固有]
                    └── clock_gettime(CLOCK_MONOTONIC) / mach_absolute_time()
```

### データフロー図

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

uv_loop_t* loop     -->  uv__hrtime(CLOCK_FAST)          -->  loop->time (uint64_t)
                         |                                     ミリ秒精度
                         └── / 1000000 (ns→ms)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | uv_update_time()のAPI宣言 |
| core.c | `src/unix/core.c` | ソース | uv_update_time()の実装 |
| internal.h | `src/unix/internal.h` | ヘッダ | uv__update_time()のインライン実装 |
| darwin.c | `src/unix/darwin.c` | ソース | macOSのuv__hrtime()実装 |
| linux.c | `src/unix/linux.c` | ソース | Linuxのuv__hrtime()実装 |
