# 機能設計書 154-ロードアベレージ取得

## 概要

本ドキュメントは、libuvライブラリにおけるuv_loadavg()関数によるシステムロードアベレージ取得機能の設計を記述する。

### 本機能の処理概要

uv_loadavg()関数は、システムの1分間・5分間・15分間のロードアベレージをクロスプラットフォームで取得する機能を提供する。

**業務上の目的・背景**：ロードアベレージはシステムの負荷状況を示す重要な指標である。サーバー監視、負荷分散の判断、キャパシティプランニングなどにおいて、リアルタイムのシステム負荷情報を取得する必要がある。各プラットフォームで異なるAPI（sysctl、getloadavg、sysinfo、/proc/loadavg）を統一的に提供する。

**機能の利用シーン**：サーバー負荷監視ダッシュボード、オートスケーリング判定のための負荷取得、パフォーマンスレポートの生成、リクエスト制限（スロットリング）のためのシステム負荷確認などに利用される。

**主要な処理内容**：
1. プラットフォーム固有のAPIでロードアベレージを取得
2. 取得した値をdouble配列の3要素（1分/5分/15分）に格納
3. 取得失敗時は何もしない（void関数）

**関連システム・外部連携**：
- macOS/BSD: sysctl(CTL_VM, VM_LOADAVG)
- Linux: /proc/loadavg またはsysinfo()
- Windows: 未実装（常に0.0を返す）

**権限による制御**：特別な権限は不要。一般ユーザー権限で実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 29 | その他ユーティリティ | 主機能 | uv_loadavg()によるロードアベレージ取得のAPI定義 |

## 機能種別

データ取得処理（システム負荷情報の読み取り）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| avg | double[3] | Yes | ロードアベレージを格納する配列 | なし（有効な配列が必要） |

### 入力データソース

OSカーネルからシステム負荷情報を取得する。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| avg[0] | double | 1分間ロードアベレージ |
| avg[1] | double | 5分間ロードアベレージ |
| avg[2] | double | 15分間ロードアベレージ |

### 出力先

呼び出し元が提供するdouble配列に書き込む。戻り値はvoid。

## 処理フロー

### 処理シーケンス

```
1. [macOS/BSD] sysctl(CTL_VM, VM_LOADAVG)でloadavg構造体を取得
   ├─ 失敗時はreturn（値は未設定のまま）
   └─ info.ldavg[0..2] / info.fscaleでスケーリング
2. [Linux] /proc/loadavgファイルの読み取りを試行
   ├─ 成功: sscanf()で3つのdouble値をパース
   └─ 失敗: sysinfo()にフォールバック
        └─ info.loads[0..2] / 65536.0でスケーリング
3. [Windows] avg[0]=avg[1]=avg[2]=0 を設定
   └─ Windowsではロードアベレージの概念が存在しない
4. [sysinfo-loadavg.c] sysinfo()を使用する汎用実装
   └─ info.loads[0..2] / 65536.0でスケーリング
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{プラットフォーム}
    B -->|macOS/BSD| C[sysctl VM_LOADAVG]
    B -->|Linux| D[/proc/loadavg 読み取り]
    B -->|Windows| E[avg = 0,0,0]
    B -->|Other| F[sysinfo]
    C --> G{sysctl成功?}
    G -->|No| H[return]
    G -->|Yes| I[ldavg / fscale]
    D --> J{読み取り成功?}
    J -->|Yes| K[sscanf 3値]
    J -->|No| L[sysinfo フォールバック]
    L --> M{sysinfo成功?}
    M -->|No| H
    M -->|Yes| N[loads / 65536.0]
    F --> O[loads / 65536.0]
    I --> P[return]
    K --> P
    N --> P
    O --> P
    E --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-154-01 | void戻り値 | この関数はvoid型で、エラーコードを返さない | 常時 |
| BR-154-02 | Windows非対応 | Windowsではロードアベレージを取得できないため常に0.0 | Windowsプラットフォーム |
| BR-154-03 | Linuxフォールバック | /proc/loadavgの読み取り失敗時はsysinfo()にフォールバック | Linuxプラットフォーム |
| BR-154-04 | スケーリング | macOS/BSDではfscaleで、Linuxのsysinfo()では65536.0で除算 | 各プラットフォーム |

### 計算ロジック

- macOS/BSD: `avg[i] = (double)info.ldavg[i] / info.fscale`
- Linux (sysinfo): `avg[i] = (double)info.loads[i] / 65536.0`
- Linux (/proc/loadavg): sscanf()で直接double値を取得

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

該当なし（データベース操作は行わない）。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| (なし) | (void関数) | sysctl/sysinfo失敗時は値未設定 | 呼び出し前に配列を0で初期化しておくことを推奨 |

### リトライ仕様

リトライは不要。

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

該当なし。

## パフォーマンス要件

軽量な処理であり即座に完了する。

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

ロードアベレージは一般的に機密情報ではない。

## 備考

- void関数であるため、呼び出し元は取得の成否を直接判定できない。配列を事前に0で初期化しておくことが推奨される。
- Windowsではロードアベレージの概念がないため、常に{0.0, 0.0, 0.0}が返される。

---

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

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

### 推奨読解順序

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

uv_loadavg()はdouble[3]を引数とするシンプルなインターフェース。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_loadavg()のAPI宣言（1736行目） |

**読解のコツ**: `UV_EXTERN void uv_loadavg(double avg[3]);` - 戻り値がvoidであり、エラーを通知しない点に注意。

#### Step 2: macOS/BSD実装を理解する

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

**主要処理フロー**:
- **141行目**: 関数エントリーポイント
- **144行目**: sysctl引数 `{CTL_VM, VM_LOADAVG}` 定義
- **146行目**: sysctl()呼び出し
- **148-150行目**: `info.ldavg[i] / info.fscale` によるスケーリング

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

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

**主要処理フロー**:
- **2451行目**: 関数エントリーポイント
- **2455-2457行目**: /proc/loadavgからの読み取りとsscanfパース
- **2459-2460行目**: フォールバックとしてsysinfo()を使用

#### Step 4: sysinfo汎用実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | sysinfo-loadavg.c | `src/unix/sysinfo-loadavg.c` | sysinfo()ベースの汎用実装 |

**主要処理フロー**:
- **28行目**: 関数エントリーポイント
- **31行目**: sysinfo()呼び出し
- **33-35行目**: `info.loads[i] / 65536.0` によるスケーリング

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | util.c | `src/win/util.c` | Windows版uv_loadavg()実装 |

**主要処理フロー**:
- **273行目**: 関数エントリーポイント
- **274-275行目**: `avg[0] = avg[1] = avg[2] = 0;` - 常に0を返す

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

```
uv_loadavg(avg[3])
    |
    +-- [macOS/BSD] sysctl(CTL_VM, VM_LOADAVG)
    |       +-- ldavg[i] / fscale
    |
    +-- [Linux] uv__slurp("/proc/loadavg")
    |       +-- sscanf(buf, "%lf %lf %lf")
    |       +-- [フォールバック] sysinfo(&info)
    |           +-- loads[i] / 65536.0
    |
    +-- [Other Unix] sysinfo(&info)
    |       +-- loads[i] / 65536.0
    |
    +-- [Windows] avg[0..2] = 0
```

### データフロー図

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

avg (double[3]) ----> uv_loadavg()                 ---> avg[0] (1分平均)
                      |                                  avg[1] (5分平均)
                      +-- sysctl / sysinfo /             avg[2] (15分平均)
                          /proc/loadavg
                          (プラットフォーム固有API)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | API宣言 |
| darwin.c | `src/unix/darwin.c` | ソース | macOS版uv_loadavg()実装 |
| linux.c | `src/unix/linux.c` | ソース | Linux版uv_loadavg()実装 |
| sysinfo-loadavg.c | `src/unix/sysinfo-loadavg.c` | ソース | sysinfo()ベースの汎用実装 |
| freebsd.c | `src/unix/freebsd.c` | ソース | FreeBSD版uv_loadavg()実装 |
| netbsd.c | `src/unix/netbsd.c` | ソース | NetBSD版uv_loadavg()実装 |
| openbsd.c | `src/unix/openbsd.c` | ソース | OpenBSD版uv_loadavg()実装 |
| aix.c | `src/unix/aix.c` | ソース | AIX版uv_loadavg()実装 |
| sunos.c | `src/unix/sunos.c` | ソース | Solaris版uv_loadavg()実装 |
| util.c | `src/win/util.c` | ソース | Windows版uv_loadavg()実装 |
