# 帳票設計書 12-総メモリ量

## 概要

本ドキュメントは、libuvライブラリが提供するシステムの総物理メモリ量取得機能（uv_get_total_memory）の帳票設計書である。

### 本帳票の処理概要

uv_get_total_memory() APIは、システムに搭載されている総物理メモリ量をバイト単位で返却する関数である。

**業務上の目的・背景**：アプリケーションがシステムのメモリ容量を把握することは、バッファサイズの決定やキャッシュ戦略の策定において重要である。本APIはプラットフォーム間の差異を吸収し、統一的なインターフェースで総メモリ情報を提供する。メモリ使用率の算出（空きメモリ量/総メモリ量）の分母としても利用される。

**帳票の利用シーン**：アプリケーション起動時のリソース確認、メモリ使用率の算出、キャッシュサイズの動的決定、システム情報レポートの生成。

**主要な出力内容**：
1. 総物理メモリ量（uint64_t型、バイト単位）

**帳票の出力タイミング**：アプリケーションコードからuv_get_total_memory()を呼び出した時点で即座に値を返却する。同期的に動作する。

**帳票の利用者**：libuvを利用するアプリケーション開発者、システム監視ツール開発者、Node.jsランタイム内部

## 帳票種別

数値レポート（スカラー値返却型）

## 利用画面

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

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | メモリ上の数値（uint64_t） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（関数戻り値） |
| 出力方法 | 関数戻り値 |
| 文字コード | N/A |

## 帳票レイアウト

### レイアウト概要

本帳票は単一のuint64_t値を返却するシンプルな構造である。

```
┌─────────────────────────────────────┐
│  総物理メモリ量（バイト単位）         │
│  型: uint64_t                       │
│  範囲: 0 〜 UINT64_MAX             │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| N/A | N/A | ヘッダー部は存在しない | N/A | N/A |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | 総物理メモリ量 | システムの総物理メモリ量 | OS API（プラットフォーム依存） | uint64_t（バイト） | 8バイト |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| N/A | N/A | フッター部は存在しない | N/A | N/A |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| なし | 引数不要。システム搭載の総物理メモリ量を返却 | N/A |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| N/A | N/A | N/A |

### 改ページ条件

改ページは発生しない（単一スカラー値の返却）。

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

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| N/A | データベースは参照しない | N/A |

### テーブル別参照項目詳細

#### プラットフォーム別データソース

| プラットフォーム | データソース | 備考 |
|----------------|-------------|------|
| Linux | /proc/meminfo（MemTotal:）、sysinfo() | MemTotalを優先し、取得できない場合はsysinfo()のtotalramにフォールバック |
| macOS/Darwin | sysctl(CTL_HW, HW_MEMSIZE) | HW_MEMSIZEでuint64_t値を取得 |
| Windows | GlobalMemoryStatusEx() | MEMORYSTATUSEX.ullTotalPhys |
| その他Unix系 | sysinfo() | sysinfo構造体のtotalram * mem_unit |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| 総メモリ量(Linux/sysinfo) | info.totalram * info.mem_unit | なし（整数演算） | sysinfo()使用時 |
| 総メモリ量(macOS) | sysctl(HW_MEMSIZE)の返却値 | なし（整数値そのまま） | sysctl使用時 |
| 総メモリ量(Windows) | memory_status.ullTotalPhys | なし（整数値そのまま） | GlobalMemoryStatusEx使用時 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[uv_get_total_memory 呼び出し] --> B{プラットフォーム判定}
    B -->|Linux| C[/proc/meminfo から MemTotal: 読取]
    B -->|macOS| D[sysctl CTL_HW HW_MEMSIZE 呼び出し]
    B -->|Windows| E[GlobalMemoryStatusEx 呼び出し]
    B -->|その他Unix| F[sysinfo 呼び出し]
    C --> G{MemTotal 取得成功?}
    G -->|Yes| H[値を返却]
    G -->|No| F
    D --> I{成功?}
    I -->|Yes| J[info値を返却]
    I -->|No| K[0 を返却]
    E --> L{成功?}
    L -->|Yes| M[ullTotalPhys を返却]
    L -->|No| K
    F --> N{sysinfo 成功?}
    N -->|Yes| O[totalram * mem_unit を返却]
    N -->|No| K
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 取得失敗 | OS APIの呼び出しが失敗した場合 | なし（戻り値0） | 0が返却される。呼び出し側で0の場合のエラーハンドリングが必要 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1件（スカラー値） |
| 目標出力時間 | マイクロ秒オーダー |
| 同時出力数上限 | 制限なし（スレッドセーフ） |

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

本APIはシステムのメモリ情報を返却するため、セキュリティ上の特別な配慮は不要である。ただし、コンテナ環境等では返却される値がホストマシン全体の値となる場合がある。

## 備考

- 総メモリ量はシステム起動後に変化しない値であるため、キャッシュして利用することが推奨される。
- uv_get_free_memory()との組み合わせでメモリ使用率を算出できる。
- コンテナ環境でのメモリ制限を考慮する場合はuv_get_constrained_memory()を併用する。

---

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

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

### 推奨読解順序

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

本APIは構造体を使用せず、uint64_t型のスカラー値を直接返却する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | 1832行目: uv_get_total_memory()の宣言。引数なし、uint64_t返却 |

**読解のコツ**: UV_EXTERNマクロは関数のシグネチャに影響しない。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | linux.c | `src/unix/linux.c` | 2074行目: Linux固有実装。/proc/meminfoからMemTotalを読取り |
| 2-2 | darwin.c | `src/unix/darwin.c` | 111行目: macOS固有実装。sysctl(CTL_HW, HW_MEMSIZE)を使用 |
| 2-3 | util.c (win) | `src/win/util.c` | 291行目: Windows固有実装。GlobalMemoryStatusEx()を使用 |
| 2-4 | sysinfo-memory.c | `src/unix/sysinfo-memory.c` | 36行目: 汎用Unix実装。sysinfo()のtotalramを使用 |

**主要処理フロー（Linux）**:
1. **2074行目**: uv_get_total_memory関数定義開始
2. **2078行目**: uv__read_proc_meminfo("MemTotal:")を呼び出し
3. **2080-2081行目**: 値が0でなければその値を返却
4. **2083-2084行目**: フォールバック：sysinfo()のtotalram * mem_unitを返却
5. **2086行目**: 全て失敗時は0を返却

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | darwin.c | `src/unix/darwin.c` | 111-120行目: sysctl()でHW_MEMSIZEを取得。uint64_t型で直接返却 |

**主要処理フロー**:
- **113行目**: CTL_HW, HW_MEMSIZEをsysctlに渡す
- **116行目**: sysctl呼び出し。失敗時は0を返却
- **119行目**: 取得した値をそのまま返却

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

```
uv_get_total_memory()  [Linux]
    │
    ├─ uv__read_proc_meminfo("MemTotal:")
    │      └─ uv__slurp("/proc/meminfo", ...)
    │
    └─ (フォールバック) sysinfo(&info)
           └─ info.totalram * info.mem_unit

uv_get_total_memory()  [macOS]
    │
    └─ sysctl({CTL_HW, HW_MEMSIZE}, ...)

uv_get_total_memory()  [Windows]
    │
    └─ GlobalMemoryStatusEx(&memory_status)
           └─ memory_status.ullTotalPhys
```

### データフロー図

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

(引数なし)   ───▶  OS API呼び出し       ───▶  uint64_t (バイト単位)
                   ├─ /proc/meminfo
                   ├─ sysctl(HW_MEMSIZE)
                   ├─ GlobalMemoryStatusEx()
                   └─ sysinfo()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | API宣言（1832行目） |
| linux.c | `src/unix/linux.c` | ソース | Linux固有実装（2074行目） |
| darwin.c | `src/unix/darwin.c` | ソース | macOS固有実装（111行目） |
| util.c | `src/win/util.c` | ソース | Windows固有実装（291行目） |
| sysinfo-memory.c | `src/unix/sysinfo-memory.c` | ソース | 汎用Unix実装（36行目） |
