# 機能設計書 147-CPU情報取得

## 概要

本ドキュメントは、libuvのOS情報機能におけるCPU情報取得・解放機能 `uv_cpu_info()` / `uv_free_cpu_info()` の設計仕様を定義する。

### 本機能の処理概要

`uv_cpu_info()` はシステムに搭載されたCPUの情報（モデル名、クロック速度、各状態の使用時間）を取得する。`uv_free_cpu_info()` は取得した情報のメモリを解放する。

**業務上の目的・背景**：システム監視、パフォーマンス分析、リソース管理等のアプリケーションでは、CPUの詳細情報が必要となる。CPU数の把握はスレッドプールやワーカープロセスの数を決定する際にも利用される。本機能はOS固有のAPIの差異を吸収し、統一的なインターフェースでCPU情報を提供する。

**機能の利用シーン**：システムモニタリングツールでのCPU使用率表示、マルチスレッドアプリケーションでのワーカー数決定、アプリケーションのシステム要件チェック、パフォーマンスプロファイリングなどに使用される。

**主要な処理内容**：
1. OS固有のAPIでCPU数とCPU情報を取得する
2. 各CPUのモデル名、クロック速度（MHz）を収集する
3. 各CPUのuser/nice/sys/idle/irq各状態の累積時間（ミリ秒）を収集する
4. 結果を `uv_cpu_info_t` 構造体の配列として返却する

**関連システム・外部連携**：macOSでは `host_processor_info()` と `sysctlbyname()`、Linuxでは `/proc/stat` と `/proc/cpuinfo`、Windowsでは `GetSystemInfo()` と `NtQuerySystemInformation()` 等を使用する。

**権限による制御**：一般ユーザー権限で実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 29 | その他ユーティリティ | 主機能 | uv_cpu_info()/free_cpu_info()によるCPU情報取得のAPI定義 |

## 機能種別

情報取得処理（システムハードウェア情報のリードオンリー参照）

## 入力仕様

### 入力パラメータ

#### uv_cpu_info()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| cpu_infos | uv_cpu_info_t** | Yes | 結果配列のポインタ格納先 | NULLの場合は未定義動作 |
| count | int* | Yes | CPU数の格納先 | NULLの場合は未定義動作 |

#### uv_free_cpu_info()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| cpu_infos | uv_cpu_info_t* | Yes | 解放対象の配列ポインタ | NULLの場合はnoop |
| count | int | Yes | CPU数 | 非負整数 |

### 入力データソース

OSのCPU情報API。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 成功時0、失敗時はlibuvエラーコード |
| cpu_infos | uv_cpu_info_t* | CPU情報の配列 |
| count | int | CPU（論理コア）数 |

#### uv_cpu_info_t 構造体

| フィールド | 型 | 説明 |
|-----------|-----|------|
| model | char* | CPUモデル名文字列（例: "Intel(R) Core(TM) i7-9750H"） |
| speed | int | クロック速度（MHz） |
| cpu_times.user | uint64_t | ユーザーモード累積時間（ミリ秒） |
| cpu_times.nice | uint64_t | nice優先度プロセス累積時間（ミリ秒） |
| cpu_times.sys | uint64_t | システムモード累積時間（ミリ秒） |
| cpu_times.idle | uint64_t | アイドル累積時間（ミリ秒） |
| cpu_times.irq | uint64_t | 割り込み処理累積時間（ミリ秒） |

### 出力先

呼び出し元が提供するポインタを介してヒープメモリ上の配列が返却される。

## 処理フロー

### 処理シーケンス

```
[uv_cpu_info - macOS版]
1. sysctlbyname("machdep.cpu.brand_string") でCPUモデル名を取得
   └─ 失敗時は sysctlbyname("hw.model") にフォールバック
2. sysctlbyname("hw.cpufrequency") でクロック速度を取得
3. host_processor_info() でCPU数と負荷情報を取得
4. uv__calloc() で uv_cpu_info_t 配列を確保
5. 各CPUについてモデル名(uv__strdup)、速度、cpu_timesを設定
   └─ CPU_STATE_USER/NICE/SYSTEM/IDLE からミリ秒に変換

[uv_free_cpu_info]
1. Linux版: uv__free(cpu_infos) で一括解放
2. その他: 各cpu_infos[i].modelを個別解放後、配列を解放
```

### フローチャート

```mermaid
flowchart TD
    A[uv_cpu_info 呼び出し] --> B[CPUモデル名取得]
    B --> C[クロック速度取得]
    C --> D[CPU数と負荷情報取得]
    D --> E{取得成功?}
    E -->|No| F[エラーコード返却]
    E -->|Yes| G[uv__calloc でメモリ確保]
    G --> H{確保成功?}
    H -->|No| I[UV_ENOMEM 返却]
    H -->|Yes| J[各CPUの情報を構造体に格納]
    J --> K[0 を返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-147-01 | 時間単位 | cpu_timesの各値はミリ秒単位で格納される | 常時 |
| BR-147-02 | CPU数 | countにはOS/ハイパースレッディング含む論理CPU数が返る | 常時 |
| BR-147-03 | モデル名フォールバック | macOSではmachdep.cpu.brand_stringが失敗した場合hw.modelを使用 | macOS |
| BR-147-04 | Linux一括解放 | Linuxではモデル名文字列はcpu_infos配列と一体で確保されるため一括解放 | Linux |

### 計算ロジック

macOS版: `cpu_times = info[i].cpu_ticks[STATE] * (1000 / sysconf(_SC_CLK_TCK))`
各OS固有のクロックティック数からミリ秒に変換。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_ENOMEM | メモリ不足 | uv__callocが失敗した場合 | 十分なメモリを確保する |
| UV__ERR(errno) | システムエラー | OS API呼び出しが失敗した場合 | OS設定を確認する |

### リトライ仕様

一時的なリソース不足の場合は再試行可能。

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

該当なし。

## パフォーマンス要件

OS APIへの問い合わせを伴う。Linux版は `/proc/stat` と `/proc/cpuinfo` のファイル読み取りを含む。

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

- CPU情報にはハードウェア構成の詳細が含まれるため、情報漏洩に注意
- 取得した情報は使用後に `uv_free_cpu_info()` で適切に解放すること

## 備考

- 各プラットフォームで実装が大きく異なる（macOS, Linux, FreeBSD, Windows等）
- Linux版ではモデル名文字列と配列を1回のmallocで一体確保する最適化が行われている
- `uv_free_cpu_info()` はLinux版とそれ以外で解放方法が異なる

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_cpu_times_s構造体（L1203-1209）とuv_cpu_info_s構造体（L1211-1215） |

**読解のコツ**: cpu_timesのuser/nice/sys/idle/irqは全てミリ秒単位のuint64_t。

#### Step 2: API宣言を確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | API宣言（L1355-1356） |

#### Step 3: macOS版の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | darwin.c | `src/unix/darwin.c` | macOS版 uv_cpu_info() 実装 |

**主要処理フロー**:
- **190行目**: `uv_cpu_info()` 関数開始
- **191-192行目**: sysconf(_SC_CLK_TCK)でティック値取得、ミリ秒乗算係数計算
- **202-205行目**: sysctlbynameで "machdep.cpu.brand_string" からモデル名取得、失敗時 "hw.model" にフォールバック
- **host_processor_info()**: CPU数と各CPUの負荷情報を取得

#### Step 4: 解放関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | uv-common.c | `src/uv-common.c` | uv_free_cpu_info() 実装（L952-964） |

**主要処理フロー**:
- **952-964行目**: Linux版は `uv__free(cpu_infos)` で一括解放、それ以外は各 `cpu_infos[i].model` を個別に `uv__free()` してから配列を `uv__free()` する

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

```
uv_cpu_info(cpu_infos, count)              [公開API - プラットフォーム別]
    ├─ [macOS] sysctlbyname()              [OS API]
    ├─ [macOS] host_processor_info()       [OS API]
    ├─ [Linux] /proc/stat, /proc/cpuinfo   [ファイル読み取り]
    ├─ uv__calloc() / uv__malloc()         [メモリ確保]
    └─ uv__strdup()                        [文字列複製]

uv_free_cpu_info(cpu_infos, count)         [公開API - src/uv-common.c L952]
    ├─ [Linux] uv__free(cpu_infos)         [一括解放]
    └─ [Other] uv__free(model) + uv__free(cpu_infos) [個別+一括解放]
```

### データフロー図

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

OS CPU情報 ────▶ uv_cpu_info()                ────▶ uv_cpu_info_t[]
                  ├─ モデル名取得                     ├─ model
                  ├─ クロック速度取得                  ├─ speed
                  └─ CPU時間取得                      └─ cpu_times
                                                          ├─ user
                                                          ├─ nice
                                                          ├─ sys
                                                          ├─ idle
                                                          └─ irq
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | 構造体定義 (L1203-1215)、API宣言 (L1355-1356) |
| darwin.c | `src/unix/darwin.c` | ソース | macOS版実装 (L190) |
| linux.c | `src/unix/linux.c` | ソース | Linux版実装 |
| freebsd.c | `src/unix/freebsd.c` | ソース | FreeBSD版実装 |
| aix.c | `src/unix/aix.c` | ソース | AIX版実装 |
| sunos.c | `src/unix/sunos.c` | ソース | Solaris版実装 |
| util.c | `src/win/util.c` | ソース | Windows版実装 |
| uv-common.c | `src/uv-common.c` | ソース | uv_free_cpu_info() 共通実装 (L952-964) |
