# 帳票設計書 11-空きメモリ量

## 概要

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

### 本帳票の処理概要

uv_get_free_memory() APIは、現在のシステムで利用可能な空き物理メモリの量をバイト単位で返却する関数である。

**業務上の目的・背景**：システム監視やリソース管理において、現在の空きメモリ量を把握することは不可欠である。Node.jsをはじめとするlibuvベースのアプリケーションでは、メモリリソースの状況に応じて動的に処理を制御する必要がある。本APIはプラットフォーム間の差異を吸収し、統一的なインターフェースで空きメモリ情報を提供する。

**帳票の利用シーン**：アプリケーションがメモリ集約的な処理を開始する前のリソース確認、システム監視ダッシュボードへの情報提供、メモリ不足時の早期警告システム、負荷分散の判断材料として利用される。

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

**帳票の出力タイミング**：アプリケーションコードからuv_get_free_memory()を呼び出した時点で即座に値を返却する。同期的に動作し、コールバックやイベントループへの登録は不要である。

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

## 帳票種別

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

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | C API呼び出し | N/A | uv_get_free_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 |

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

データベースへの参照は行わない。OS提供のシステムコールまたはAPIを直接使用する。

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

| プラットフォーム | データソース | 備考 |
|----------------|-------------|------|
| Linux | /proc/meminfo（MemAvailable:）、sysinfo() | MemAvailableを優先し、取得できない場合はsysinfo()のfreeramにフォールバック |
| macOS/Darwin | host_statistics(HOST_VM_INFO) | vm_statistics_data_tのfree_count * ページサイズ |
| Windows | GlobalMemoryStatusEx() | MEMORYSTATUSEX.ullAvailPhys |
| その他Unix系 | sysinfo() | sysinfo構造体のfreeram * mem_unit |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| 空きメモリ量(Linux/sysinfo) | info.freeram * info.mem_unit | なし（整数演算） | sysinfo()使用時 |
| 空きメモリ量(macOS) | info.free_count * sysconf(_SC_PAGESIZE) | なし（整数演算） | host_statistics使用時 |
| 空きメモリ量(Windows) | memory_status.ullAvailPhys | なし（整数値そのまま） | GlobalMemoryStatusEx使用時 |

## 処理フロー

### 出力フロー

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

## エラー処理

### エラーケース一覧

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

## パフォーマンス要件

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

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

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

## 備考

- Linux環境では、/proc/meminfoのMemAvailable:を優先的に使用する。これはカーネル3.14以降で利用可能であり、MemFreeよりもアプリケーションが実際に使用可能なメモリ量に近い値を返す。
- 取得失敗時は0を返却する（エラーコードは返さない）。
- uv_get_available_memory()との違い：uv_get_free_memoryはOS報告の空きメモリ量をそのまま返すのに対し、uv_get_available_memoryはcgroup等のメモリ制約を考慮した利用可能量を返す。

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: UV_EXTERNマクロはDLL export/import制御用であり、関数のシグネチャに影響しない。

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

プラットフォーム別に実装が分かれている。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | linux.c | `src/unix/linux.c` | 2058行目: Linux固有実装。/proc/meminfoからMemAvailableを読取り、フォールバックとしてsysinfo()を使用 |
| 2-2 | darwin.c | `src/unix/darwin.c` | 98行目: macOS固有実装。host_statistics()でvm_statistics_data_tを取得 |
| 2-3 | util.c (win) | `src/win/util.c` | 279行目: Windows固有実装。GlobalMemoryStatusEx()を使用 |
| 2-4 | sysinfo-memory.c | `src/unix/sysinfo-memory.c` | 28行目: 汎用Unix実装。sysinfo()を使用（Hurd等向け） |

**主要処理フロー（Linux）**:
1. **2058行目**: uv_get_free_memory関数定義開始
2. **2062行目**: uv__read_proc_meminfo("MemAvailable:")を呼び出し
3. **2064-2065行目**: 値が0でなければその値を返却
4. **2067-2068行目**: フォールバック：sysinfo()のfreeram * mem_unitを返却
5. **2070行目**: 全て失敗時は0を返却

#### Step 3: Linux固有の補助関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | linux.c | `src/unix/linux.c` | uv__read_proc_meminfo関数: /proc/meminfoから指定キーの値を読み取りkBからバイトに変換 |

**主要処理フロー**:
- /proc/meminfoファイルを読み込み、指定されたキー（"MemAvailable:"）を検索
- sscanfでuint64_t値を読み取り、1024を乗じてバイト単位に変換

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

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

uv_get_free_memory()  [macOS]
    │
    └─ host_statistics(mach_host_self(), HOST_VM_INFO, ...)
           └─ info.free_count * sysconf(_SC_PAGESIZE)

uv_get_free_memory()  [Windows]
    │
    └─ GlobalMemoryStatusEx(&memory_status)
           └─ memory_status.ullAvailPhys
```

### データフロー図

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

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

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | API宣言（1831行目） |
| linux.c | `src/unix/linux.c` | ソース | Linux固有実装（2058行目） |
| darwin.c | `src/unix/darwin.c` | ソース | macOS固有実装（98行目） |
| util.c | `src/win/util.c` | ソース | Windows固有実装（279行目） |
| sysinfo-memory.c | `src/unix/sysinfo-memory.c` | ソース | 汎用Unix実装（28行目） |
| freebsd.c | `src/unix/freebsd.c` | ソース | FreeBSD固有実装 |
| openbsd.c | `src/unix/openbsd.c` | ソース | OpenBSD固有実装 |
| netbsd.c | `src/unix/netbsd.c` | ソース | NetBSD固有実装 |
| aix.c | `src/unix/aix.c` | ソース | AIX固有実装 |
| sunos.c | `src/unix/sunos.c` | ソース | SunOS固有実装 |
