# 機能設計書 250-SetAllocatorFunctions

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるSetAllocatorFunctions関数の機能設計について記述する。この関数はImGuiが使用するメモリアロケータ関数を設定するためのユーティリティ関数である。

### 本機能の処理概要

SetAllocatorFunctions関数は、ImGuiが内部で使用するメモリ割り当て（malloc相当）および解放（free相当）関数をカスタム関数に置き換える機能を提供する。DLL境界を跨ぐ場合や、独自のメモリ管理システムを使用する場合に必須となる。

**業務上の目的・背景**：大規模なアプリケーションでは、メモリ管理の一元化やデバッグ、パフォーマンス最適化のために独自のメモリアロケータを使用することが多い。また、DLLとしてImGuiを使用する場合、ヒープが分離されるため、同一のアロケータを使用することで問題を回避できる。この関数は、そのようなメモリ管理のカスタマイズを可能にする。

**機能の利用シーン**：DLLとしてImGuiを使用する場合のヒープ共有、カスタムメモリプールの使用、メモリ使用量のトラッキング、メモリリークの検出、特殊なアライメント要件への対応などに使用される。

**主要な処理内容**：
1. グローバルアロケータ関数ポインタを更新
2. グローバルフリー関数ポインタを更新
3. ユーザーデータポインタを更新

**関連システム・外部連携**：ImGuiの全てのメモリ割り当て（IM_ALLOC/IM_FREE）がこれらの関数を通じて行われる。CreateContext()前に呼び出す必要がある。

**権限による制御**：本機能に権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全機能 | 基盤機能 | メモリ割り当ての制御 |

## 機能種別

設定処理 / メモリ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| alloc_func | ImGuiMemAllocFunc | Yes | メモリ割り当て関数 | NULLでないこと |
| free_func | ImGuiMemFreeFunc | Yes | メモリ解放関数 | NULLでないこと |
| user_data | void* | No (デフォルト: NULL) | コールバックに渡すユーザーデータ | - |

### 関数シグネチャ

```cpp
typedef void* (*ImGuiMemAllocFunc)(size_t sz, void* user_data);
typedef void  (*ImGuiMemFreeFunc)(void* ptr, void* user_data);
```

### 入力データソース

- アプリケーションコードからの直接指定
- DLL境界を跨ぐ場合は呼び出し元モジュールのアロケータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | void | 戻り値なし |

### 出力先

- グローバル変数 GImAllocatorAllocFunc
- グローバル変数 GImAllocatorFreeFunc
- グローバル変数 GImAllocatorUserData

## 処理フロー

### 処理シーケンス

```
1. アロケート関数ポインタ設定
   └─ GImAllocatorAllocFunc = alloc_func
2. フリー関数ポインタ設定
   └─ GImAllocatorFreeFunc = free_func
3. ユーザーデータ設定
   └─ GImAllocatorUserData = user_data
```

### フローチャート

```mermaid
flowchart TD
    A[SetAllocatorFunctions呼び出し] --> B[GImAllocatorAllocFunc = alloc_func]
    B --> C[GImAllocatorFreeFunc = free_func]
    C --> D[GImAllocatorUserData = user_data]
    D --> E[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-250-1 | 呼び出しタイミング | CreateContext()前に呼び出す必要がある | 初回設定時 |
| BR-250-2 | DLL境界 | DLL境界を跨ぐ場合はSetCurrentContext()と共に呼び出す | DLL使用時 |
| BR-250-3 | コンテキスト非依存 | この関数はコンテキストに依存しない | 常時 |
| BR-250-4 | グローバル設定 | 全てのImGuiコンテキストで共有される | 常時 |

### 計算ロジック

特別な計算処理は行わない。関数ポインタの設定のみ。

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

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 未定義動作 | alloc_funcがNULLの場合 | 有効な関数ポインタを指定 |
| - | 未定義動作 | free_funcがNULLの場合 | 有効な関数ポインタを指定 |
| - | メモリリーク | 既存割り当て後に変更した場合 | CreateContext()前に設定 |

### リトライ仕様

リトライ処理は不要。

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

本機能はトランザクション処理を行わない。

## パフォーマンス要件

- 処理時間: O(1) - 単純な代入のみ
- メモリ使用: 追加のメモリ割り当てなし
- 呼び出し頻度: 通常はアプリケーション起動時に1回

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

- アロケータ関数が適切に実装されていることが前提
- 悪意のあるアロケータによるセキュリティリスク
- アロケータのスレッドセーフ性は実装者の責任

## 備考

- GetAllocatorFunctions()で現在の設定を取得可能
- デフォルトではmallocとfreeが使用される
- IMGUI_DISABLE_DEFAULT_ALLOCATORSでデフォルトアロケータを無効化可能
- MemAlloc()/MemFree()はこれらの関数を呼び出すラッパー

---

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

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

### 推奨読解順序

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

アロケータ関数の型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiMemAllocFunc/ImGuiMemFreeFunc型定義（288-289行目） |
| 1-2 | imgui.cpp | `imgui.cpp` | GImAllocatorAllocFunc等のグローバル変数（1433-1435行目） |

**読解のコツ**: ImGuiMemAllocFuncは`void* (*)(size_t sz, void* user_data)`型で、sizeとuser_dataを受け取りvoid*を返す関数ポインタ。

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

関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | SetAllocatorFunctions関数の実装（4061-4066行目） |

**主要処理フロー**:
1. **4063行目**: GImAllocatorAllocFunc = alloc_func
2. **4064行目**: GImAllocatorFreeFunc = free_func
3. **4065行目**: GImAllocatorUserData = user_data

#### Step 3: アロケータの使用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | MemAlloc関数（5041-5048行目）- アロケータの呼び出し |
| 3-2 | imgui.cpp | `imgui.cpp` | MemFree関数（5050-5060行目）- フリー関数の呼び出し |
| 3-3 | imgui.cpp | `imgui.cpp` | GetAllocatorFunctions関数（4069-4074行目）- 設定の取得 |

#### Step 4: デフォルトアロケータを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui.cpp | `imgui.cpp` | MallocWrapper/FreeWrapper関数（1426-1431行目）- デフォルト実装 |

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

```
SetAllocatorFunctions(alloc_func, free_func, user_data)
    │
    ├─ GImAllocatorAllocFunc = alloc_func
    │
    ├─ GImAllocatorFreeFunc = free_func
    │
    └─ GImAllocatorUserData = user_data

[以降、ImGui内部のメモリ操作で使用]

IM_ALLOC(size) / MemAlloc(size)
    │
    └─ (*GImAllocatorAllocFunc)(size, GImAllocatorUserData)

IM_FREE(ptr) / MemFree(ptr)
    │
    └─ (*GImAllocatorFreeFunc)(ptr, GImAllocatorUserData)
```

### データフロー図

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

アプリケーション            SetAllocatorFunctions()        グローバル変数
    │                            │                            │
    ├─ alloc_func ──────────────▶ GImAllocatorAllocFunc ─────▶ MemAlloc()で使用
    │                            │                            │
    ├─ free_func ───────────────▶ GImAllocatorFreeFunc ──────▶ MemFree()で使用
    │                            │                            │
    └─ user_data ───────────────▶ GImAllocatorUserData ──────▶ コールバックに渡される
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言、型定義 |
| imgui.cpp | `imgui.cpp` | ソース | SetAllocatorFunctions/MemAlloc/MemFree実装 |
| imconfig.h | `imconfig.h` | 設定 | IMGUI_DISABLE_DEFAULT_ALLOCATORS設定 |
