# 帳票設計書 6-スレッドリソース使用状況レポート

## 概要

本ドキュメントは、libuvライブラリにおける `uv_getrusage_thread()` API関数の帳票設計書である。現在スレッドのリソース使用状況をuv_rusage_t構造体に出力する機能について定義する。

### 本帳票の処理概要

本帳票は、POSIXの `getrusage(RUSAGE_THREAD)` に相当する機能を提供し、プロセス全体ではなく現在実行中のスレッド単位のリソース使用状況を取得する。プラットフォームによって異なる実装が用いられる。

**業務上の目的・背景**：マルチスレッドアプリケーションにおいて、特定のスレッド（例：イベントループスレッド、ワーカースレッド）のリソース消費を個別に計測する必要がある。プロセス全体のリソース使用量（No.5）では各スレッドの負荷を区別できないため、スレッド単位の計測が必要となる。

**帳票の利用シーン**：ワーカースレッドプールの効率評価、イベントループスレッドのCPU使用率計測、スレッド別パフォーマンスプロファイリング。

**主要な出力内容**：
1. ユーザーCPU時間（ru_utime）
2. システムCPU時間（ru_stime）
3. その他のリソース使用情報（プラットフォーム依存）

**帳票の出力タイミング**：`uv_getrusage_thread(&rusage)` 呼び出し時に即座に出力される。

**帳票の利用者**：パフォーマンスエンジニア、マルチスレッドアプリケーション開発者。

## 帳票種別

リソース使用状況レポート（構造体出力）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | N/A（C API呼び出し） | N/A | `uv_getrusage_thread(&rusage)` 関数呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | メモリ構造体（uv_rusage_t） |
| 出力方法 | 構造体フィールドへの値格納 |

## 帳票レイアウト

### 明細部

No.5「プロセスリソース使用状況レポート」と同一のuv_rusage_t構造体に出力される。ただし、プラットフォームにより取得可能なフィールドが異なる。

| No | 項目名 | 説明 | macOS | Linux/RUSAGE_THREAD対応 | 非対応OS |
|----|-------|------|-------|------------------------|---------|
| 1 | ru_utime | ユーザーCPU時間 | thread_info API | getrusage(RUSAGE_THREAD) | 非対応 |
| 2 | ru_stime | システムCPU時間 | thread_info API | getrusage(RUSAGE_THREAD) | 非対応 |
| 3-16 | その他 | 各種リソース情報 | 0（未設定） | getrusage()から取得 | 非対応 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| rusageポインタ | 結果を格納するuv_rusage_t構造体へのポインタ | Yes |

## データベース参照仕様

### 参照テーブル一覧

| テーブル名（データ構造） | 用途 | プラットフォーム |
|-----------|------|----------------|
| thread_basic_info_data_t | macOSスレッドCPU時間 | macOS |
| struct rusage | POSIXリソース使用状況 | Linux等（RUSAGE_THREAD/RUSAGE_LWP対応OS） |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| macOS: ru_utime.tv_sec | info.user_time.seconds | N/A | Machスレッド情報から |
| macOS: ru_utime.tv_usec | info.user_time.microseconds | N/A | Machスレッド情報から |
| macOS: ru_stime.tv_sec | info.system_time.seconds | N/A | Machスレッド情報から |
| macOS: ru_stime.tv_usec | info.system_time.microseconds | N/A | Machスレッド情報から |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[uv_getrusage_thread呼び出し] --> B{プラットフォーム判定}
    B -->|macOS| C[mach_thread_selfでスレッドポート取得]
    C --> D[thread_info THREAD_BASIC_INFO呼び出し]
    D --> E{成功?}
    E -->|No| F[mach_port_deallocate後にUV_EINVAL返却]
    E -->|Yes| G[memsetで構造体ゼロ初期化]
    G --> H[user_time/system_timeをコピー]
    H --> I[mach_port_deallocate]
    I --> J[0を返却]
    B -->|RUSAGE_LWP対応| K[uv__getrusage RUSAGE_LWP 呼び出し]
    B -->|RUSAGE_THREAD対応| L[uv__getrusage RUSAGE_THREAD 呼び出し]
    B -->|非対応| M[UV_ENOTSUP返却]
    K --> J
    L --> J
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| Machカーネルエラー | macOSでthread_info()がKERN_SUCCESS以外を返した場合 | N/A | UV_EINVALを返却 |
| 非サポート | RUSAGE_THREAD/RUSAGE_LWPのいずれも利用できないプラットフォーム | N/A | UV_ENOTSUPを返却 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1件（固定） |
| 目標出力時間 | マイクロ秒オーダー |
| 同時出力数上限 | N/A |

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

特になし。

## 備考

- macOSではMach thread_info APIを使用し、ru_utime/ru_stimeのみが設定される（他フィールドはゼロ初期化）
- Solarisでは RUSAGE_LWP を使用
- Linuxでは RUSAGE_THREAD を使用
- いずれも未定義のプラットフォームではUV_ENOTSUPが返される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_rusage_t構造体（1291-1308行目）はNo.5と共通 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | core.c | `src/unix/core.c` | uv_getrusage_thread()（1144-1180行目）の条件コンパイル分岐を理解する |

**主要処理フロー**:
1. **1145行目**: `#if defined(__APPLE__)` でmacOS固有パスに分岐
2. **1151行目**: `mach_thread_self()` で現在スレッドのMachポートを取得
3. **1153-1156行目**: `thread_info(thread, THREAD_BASIC_INFO, ...)` でスレッド情報を取得
4. **1163行目**: `memset(rusage, 0, sizeof(*rusage))` で構造体をゼロ初期化
5. **1165-1168行目**: user_time/system_timeをru_utime/ru_stimeにコピー
6. **1174行目**: `#elif defined(RUSAGE_LWP)` でSolaris向けパス
7. **1176行目**: `#elif defined(RUSAGE_THREAD)` でLinux向けパス
8. **1179行目**: いずれにも該当しない場合 `UV_ENOTSUP` を返却

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

```
uv_getrusage_thread(rusage)                       [src/unix/core.c:1144]
    |
    +-- [macOS] mach_thread_self()                [Mach API]
    |       +-- thread_info(THREAD_BASIC_INFO)    [Mach API]
    |       +-- mach_port_deallocate()            [Mach API]
    |
    +-- [Solaris] uv__getrusage(RUSAGE_LWP)       [src/unix/core.c:1097]
    |       +-- getrusage(RUSAGE_LWP)             [POSIX]
    |
    +-- [Linux] uv__getrusage(RUSAGE_THREAD)      [src/unix/core.c:1097]
            +-- getrusage(RUSAGE_THREAD)          [Linux拡張]
```

### データフロー図

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

[macOS]                         uv_getrusage_thread()         uv_rusage_t*
thread_basic_info_data_t ---->  user_time/system_time ---->   .ru_utime
                                memset(0) + コピー             .ru_stime

[Linux]                         uv__getrusage()               uv_rusage_t*
getrusage(RUSAGE_THREAD) ---->  全フィールドコピー ---->       全フィールド
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | uv_rusage_t構造体定義、API宣言 |
| core.c | `src/unix/core.c` | ソース | uv_getrusage_thread()実装（プラットフォーム分岐） |
