# 機能設計書 10-現在時刻取得

## 概要

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

### 本機能の処理概要

`uv_now()`は、イベントループの現在のタイムスタンプ（ミリ秒）を取得する関数である。`loop->time`フィールドの値をそのまま返却する極めて軽量な操作である。この値は`uv_update_time()`によってキャッシュされたものであり、システムコールを発行しない。

**業務上の目的・背景**：イベントループ内でのタイマー計算やタイムアウト判定など、時刻を参照する処理で使用される。システムコールを伴わないため、高頻度での呼び出しに適している。タイマーの基準時刻としても機能する。

**機能の利用シーン**：
- コールバック内で経過時間を計算する場合
- タイムアウト判定を行う場合
- パフォーマンス計測（簡易的な経過時間測定）
- タイマーの残り時間を手動で計算する場合

**主要な処理内容**：
1. `loop->time`の値を返却する

**関連システム・外部連携**：特になし。時刻の実際の取得は`uv_update_time()`（No.9）が担当する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | イベントループ | 主機能 | uv_now()によるループ内タイムスタンプ取得のAPI定義 |

## 機能種別

データ取得

## 入力仕様

### 入力パラメータ

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

### 入力データソース

イベントループの`time`フィールド（`uv_update_time()`で事前にキャッシュされた値）。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | uint64_t | イベントループのキャッシュされたタイムスタンプ（ミリ秒、モノトニック） |

### 出力先

関数の戻り値。

## 処理フロー

### 処理シーケンス

```
1. loop->timeの返却
   └─ return loop->time
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[return loop->time]
    B --> C[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | キャッシュ値 | 返却される値はuv__update_time()でキャッシュされた値であり、リアルタイムではない | 常時 |
| BR-02 | モノトニック | 返却される値はモノトニック（単調増加）であり、システム時刻変更の影響を受けない | 常時 |
| BR-03 | ミリ秒精度 | タイムスタンプはミリ秒精度である | 常時 |
| BR-04 | システムコール不要 | フィールド参照のみでシステムコールを発行しない | 常時 |

### 計算ロジック

```c
return loop->time;
```

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

該当なし。

## エラー処理

### エラーケース一覧

エラーケースなし。フィールド参照は常に成功する。

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

`loop->time`フィールドの直接参照のみであり、O(1)の定数時間、システムコール不要。非常に高頻度での呼び出しに耐えうる。

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

特になし。入力がconst修飾されており、ループ状態を変更しない。

## 備考

- `uv_now()`はキャッシュ値を返すため、コールバック内で長時間のブロッキング処理を行った場合、実際の時刻と乖離する可能性がある。その場合は`uv_update_time()`で明示的にキャッシュを更新する
- より精度の高い時刻が必要な場合は`uv_hrtime()`（ナノ秒精度）を使用する
- `uv_now()`の基準時点（エポック）は不定であり、絶対時刻としては使用できない。経過時間の計測に使用する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | UV_LOOP_PRIVATE_FIELDSマクロ内の`time`フィールド（uint64_t）。`uv_update_time()`でキャッシュされたミリ秒タイムスタンプ |

**読解のコツ**: `time`フィールドはprivateフィールドであるため、`include/uv/unix.h`または`include/uv/win.h`のUV_LOOP_PRIVATE_FIELDSマクロ内を確認する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | **318行目**: `uv_now()`のAPI宣言。`uint64_t uv_now(const uv_loop_t*)` |
| 2-2 | uv-common.c | `src/uv-common.c` | **643-645行目**: `uv_now()`の実装 |

**主要処理フロー**:
1. **644行目**: `return loop->time` - キャッシュされたタイムスタンプの返却

#### Step 3: 関連する時刻管理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | internal.h | `src/unix/internal.h` | **467-471行目**: `uv__update_time()`。`loop->time`を更新する関数 |
| 3-2 | core.c | `src/unix/core.c` | **495-497行目**: `uv_update_time()`。ユーザー向けの時刻更新API |

**主要処理フロー**:
- uv_now()は読み取り専用、uv_update_time()は書き込み。この対の関係を理解する。

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

```
uv_now(loop)                              [src/uv-common.c:643]
    |
    └── return loop->time                 [フィールド参照のみ]

[参考: loop->timeの更新パス]
uv_update_time(loop)                      [src/unix/core.c:495]
    └── uv__update_time(loop)             [src/unix/internal.h:467]
        └── loop->time = uv__hrtime(UV_CLOCK_FAST) / 1000000
```

### データフロー図

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

const uv_loop_t*    -->  loop->time参照                  -->  uint64_t (ミリ秒)
                         （フィールド読み取りのみ）

[参考: 更新フロー]
uv__hrtime()        -->  / 1000000                       -->  loop->time
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | uv_now()のAPI宣言 |
| uv-common.c | `src/uv-common.c` | ソース | uv_now()の実装 |
| internal.h | `src/unix/internal.h` | ヘッダ | uv__update_time()（timeフィールドの書き込み側） |
| core.c | `src/unix/core.c` | ソース | uv_update_time()の実装、uv_run()内での自動更新 |
