# 機能設計書 130-スレッドCPU取得

## 概要

本ドキュメントは、libuvが提供するスレッドCPU取得機能 `uv_thread_getcpu()` の設計仕様を記述する。現在のスレッドが実行中のCPU番号を取得するための機能である。

### 本機能の処理概要

**業務上の目的・背景**：マルチコア環境でのパフォーマンスチューニングやデバッグにおいて、スレッドがどのCPUコアで実行されているかを知ることは有用である。NUMAアーキテクチャ上での最適化、CPUアフィニティ設定の効果確認、ロードバランシングの検証などに活用される。

**機能の利用シーン**：パフォーマンスモニタリング、NUMAアウェアなメモリ割り当ての判断材料、CPUアフィニティ設定後の検証、ベンチマーク時のCPUコア確認に使用される。

**主要な処理内容**：
1. Linux/FreeBSD: `sched_getcpu()` を呼び出して現在のCPU番号を取得
2. Windows: `GetCurrentProcessorNumber()` を呼び出して現在のCPU番号を取得
3. 非対応プラットフォーム: UV_ENOTSUPを返却

**関連システム・外部連携**：Linux sched_getcpu()、Windows GetCurrentProcessorNumber()。

**権限による制御**：特になし。読み取り専用の情報取得であり、特別な権限は不要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 28 | スレッド | 主機能 | uv_thread_getcpu()による実行中CPU取得のAPI定義 |

## 機能種別

情報取得処理

## 入力仕様

### 入力パラメータ

パラメータなし。

### 入力データソース

OS内部のCPU実行情報。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 0以上:CPU番号、UV_ENOTSUP:非対応プラットフォーム、負値:エラー |

### 出力先

関数の戻り値として返却。

## 処理フロー

### 処理シーケンス

```
1. プラットフォーム判定
   └─ UV__CPU_AFFINITY_SUPPORTEDマクロが定義されている場合:
      a. sched_getcpu()を呼び出し（Linux/FreeBSD）
      b. 結果が負の場合: UV__ERR(errno)を返却
      c. 成功: CPU番号を返却
   └─ 定義されていない場合（非対応プラットフォーム）:
      a. UV_ENOTSUPを返却
2. Windows:
   └─ GetCurrentProcessorNumber()を呼び出し
   └─ CPU番号を返却
```

### フローチャート

```mermaid
flowchart TD
    A[uv_thread_getcpu呼び出し] --> B{プラットフォーム}
    B -->|Linux/FreeBSD| C[sched_getcpu]
    B -->|Windows| D[GetCurrentProcessorNumber]
    B -->|その他| E[UV_ENOTSUP返却]
    C --> F{結果 < 0?}
    F -->|Yes| G[UV__ERR errno返却]
    F -->|No| H[CPU番号返却]
    D --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-130-1 | プラットフォーム制限 | UV__CPU_AFFINITY_SUPPORTEDマクロが定義されたプラットフォーム（Linux、FreeBSD）とWindowsでのみ利用可能 | 常時 |
| BR-130-2 | 瞬間値 | 返却されるCPU番号は呼び出し時点の値であり、直後に別のCPUに移動する可能性がある | 常時 |
| BR-130-3 | Windowsは常に成功 | Windows版のGetCurrentProcessorNumber()はエラーを返さない | Windows |

### 計算ロジック

なし。

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

### 操作別データベース影響一覧

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_ENOTSUP | 非対応 | 対応していないプラットフォーム | プラットフォーム対応状況を確認 |
| UV__ERR(errno) | システムエラー | sched_getcpu()失敗（Linux） | errnoの内容を確認 |

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

システムコール1回の呼び出しで即座に完了する。オーバーヘッドは無視できる程度。

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

- CPU番号はサイドチャネル攻撃の一部として悪用される可能性があるが、一般的には問題とならない
- 読み取り専用操作であり、システムに影響を与えない

## 備考

- 返却値はあくまでも呼び出し時点のスナップショットであり、スレッドスケジューラによりいつでも変更されうる
- CPUアフィニティを設定している場合は、設定されたCPUのいずれかが常に返される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **1921行目**: `uv_thread_getcpu()`の関数シグネチャ。引数なし、int返却 |

**読解のコツ**: 戻り値が成功時はCPU番号（0以上の整数）、エラー時は負のlibuvエラーコードという二重の意味を持つ点に注意。

#### Step 2: Unix実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | thread.c | `src/unix/thread.c` | **276-288行目**: `uv_thread_getcpu()`。UV__CPU_AFFINITY_SUPPORTEDが定義されている場合はsched_getcpu()を呼び出し、そうでない場合はUV_ENOTSUPを返却 |

**主要処理フロー**:
- **280行目**: `sched_getcpu()` 呼び出し
- **281-282行目**: 戻り値が負の場合はUV__ERR(errno)
- **284行目**: CPU番号を返却
- **286行目**: 非対応時はUV_ENOTSUP

#### Step 3: Windows実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | thread.c | `src/win/thread.c` | **245-247行目**: Windows版`uv_thread_getcpu()`。GetCurrentProcessorNumber()を直接返却する1行関数 |

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

```
uv_thread_getcpu() [src/unix/thread.c:276]
    │
    └── sched_getcpu() [Linux/FreeBSD libc]
            └── 現在のCPU番号を返却

uv_thread_getcpu() [src/win/thread.c:245]
    │
    └── GetCurrentProcessorNumber() [Win32]
            └── 現在のCPU番号を返却
```

### データフロー図

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

(なし) ──────▶ uv_thread_getcpu()
                    │
                    ├── sched_getcpu() [Linux]
                    ├── GetCurrentProcessorNumber() [Win]
                    └── UV_ENOTSUP [その他]
                    │
                    └──▶ int（CPU番号 or エラーコード）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | API宣言 |
| thread.c | `src/unix/thread.c` | ソース | Unix実装（対応/非対応プラットフォーム別） |
| thread.c | `src/win/thread.c` | ソース | Windows実装 |
