# 機能設計書 8-Classクラス

## 概要

本ドキュメントは、mrubyのClassクラスの設計を記述する。クラスとモジュールの定義・継承・メソッドテーブル管理・メソッド定義・メソッド探索を行う。

### 本機能の処理概要

Classクラスはmrubyのオブジェクト指向システムの基盤であり、クラスとモジュールの生成・継承階層の構築・メソッドテーブルの管理・メソッドの定義と探索を提供する。RClass構造体を用いたクラス階層と、mrb_mt_tblによるチェーン型メソッドテーブルが核心的なデータ構造である。

**業務上の目的・背景**：mrubyはRubyのオブジェクト指向モデルを忠実に再現しており、Class/Module/Objectの三位一体のクラス階層が全てのオブジェクト操作の基盤となる。メソッドテーブルのチェーン構造とROMテーブルサポートにより、組み込み環境でのメモリ効率を向上させている。

**機能の利用シーン**：クラス定義（`class Foo < Bar`）、モジュール定義（`module Baz`）、メソッド定義（`def method`）、モジュールインクルード（`include`）、メソッド探索（メソッド呼び出し時）。

**主要な処理内容**：
1. クラス・モジュールの定義（`mrb_define_class`, `mrb_define_module`）
2. メソッドテーブル（mrb_mt_tbl）の管理（作成・検索・挿入・削除）
3. メソッド定義（`mrb_define_method`, `mrb_define_class_method`等）
4. メソッド探索（`mrb_method_search_vm`, `mrb_vm_find_method`）
5. モジュールインクルード・プリペンド
6. クラス階層の走査

**関連システム・外部連携**：VM（メソッド呼び出し）、GC（メソッドテーブルのマーク・解放）、全組み込み型クラス。

**権限による制御**：メソッドの可視性（public/protected/private）を管理。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面機能マッピングにデータなし |

## 機能種別

オブジェクト管理処理（クラスシステム）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| mrb | mrb_state* | Yes | mrubyインタプリタ状態 | NULLでないこと |
| name | const char* / mrb_sym | Yes | クラス/メソッド名 | 定数名規則に準拠 |
| super | struct RClass* | No | 親クラス（デフォルトObject） | - |
| func | mrb_func_t | Yes | C関数ポインタ（メソッド定義時） | - |
| aspec | mrb_aspec | Yes | 引数仕様（メソッド定義時） | - |

### 入力データソース

Rubyソースコードからの定義リクエスト、C API経由でのメソッド/クラス定義。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| RClass* | struct RClass* | 定義されたクラス/モジュール |
| mrb_method_t | mrb_method_t | 探索されたメソッド |

### 出力先

呼び出し元への戻り値、mrb_stateの各クラスポインタ。

## 処理フロー

### 処理シーケンス

```
1. mrb_define_class() - クラス定義
   ├─ mrb_const_name_p() - 定数名チェック
   ├─ mrb_vm_define_class() - RClass生成・初期化
   └─ setup_class() - 外部名前空間への定数登録
2. メソッドテーブル操作
   ├─ mt_new() - 空テーブル生成
   ├─ mt_put() - エントリ挿入/更新（線形スキャン）
   ├─ mt_get() - エントリ検索（チェーン走査+線形スキャン）
   └─ mt_del() - エントリ削除（末尾スワップ）
3. メソッド探索
   └─ クラス階層を上方走査しながら各クラスのメソッドテーブルを検索
```

### フローチャート

```mermaid
flowchart TD
    A[mrb_define_class] --> B{定数名チェック}
    B -->|OK| C[mrb_vm_define_class]
    B -->|NG| D[NameError]
    C --> E[RClass生成]
    E --> F[継承設定]
    F --> G[setup_class: 定数登録]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | メソッドテーブルのチェーン構造 | ミュータブル層→ROM層のチェーンで探索 | メソッド探索時 |
| BR-02 | ROM テーブル | MRB_MT_READONLY_BITフラグ付きは変更不可 | ROMメソッド |
| BR-03 | 線形スキャン | メソッドテーブルは配列の線形スキャンで検索 | mt_get/mt_put時 |
| BR-04 | 初期テーブルサイズ | 初回成長時に8エントリ確保、以降2倍成長 | mt_put時 |

### 計算ロジック

特になし。

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NameError | 不正クラス名 | 大文字で始まらないクラス名 | 正しい定数名を使用 |
| TypeError | 型不正 | 不正な型のスーパークラス | 正しいクラスオブジェクトを指定 |

### リトライ仕様

リトライ機構なし。

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

該当なし

## パフォーマンス要件

- メソッドテーブルの線形スキャンはテーブルサイズに比例（小規模クラスでは高速）
- ROM テーブルのチェーン構造でメモリ共有を実現
- VMメソッドキャッシュとの連携で頻繁なメソッド探索を高速化

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

- メソッド可視性（public/protected/private）の強制
- フリーズされたクラスへのメソッド追加の防止

## 備考

- class.cは4394行の大規模ファイル
- メソッドテーブルはmrb_mt_tbl構造体で管理され、チェーン（next）で複数層をリンク
- ROM層（静的定義メソッド）とミュータブル層（動的追加メソッド）を分離

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | class.c | `src/class.c` | mt_new()（42-54行目）: mrb_mt_tblの生成（size=0, alloc=0, ptr=NULL） |
| 1-2 | class.c | `src/class.c` | mt_put()（57-83行目）: 線形スキャン→末尾追加、初期8エントリ→2倍成長 |
| 1-3 | class.c | `src/class.c` | mt_get()（88-104行目）: チェーン走査+線形スキャン |
| 1-4 | class.c | `src/class.c` | mt_del()（107-123行目）: 末尾スワップ削除 |

**読解のコツ**: mrb_mt_tblはnextポインタでチェーンされる。mt_readonly_p(t)がtrueのテーブルはROM層で変更不可。

#### Step 2: ROM テーブル初期化を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | class.c | `src/class.c` | mrb_mt_init_rom()（182-212行目）: ROM層の追加とmrb->rom_mtへの登録 |
| 2-2 | class.c | `src/class.c` | mt_copy()（140-160行目）: ROM層参照のコピー戦略 |
| 2-3 | class.c | `src/class.c` | mt_free()（166-175行目）: ミュータブル層のみ解放 |

**主要処理フロー**:
- **186-188行目**: ROMテーブルラッパー作成（MRB_MT_READONLY_BIT設定）
- **192-196行目**: mrb->rom_mtリストへの登録（mrb_close時に解放）
- **200-211行目**: クラスのメソッドテーブルチェーンにROM層を挿入

#### Step 3: クラス定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | class.c | `src/class.c` | setup_class()（344-348行目）: 定数登録 |
| 3-2 | class.c | `src/class.c` | mrb_class_name_class()（307-334行目）: クラス名の設定 |

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

```
mrb_define_class() / mrb_define_module()
    │
    ├─ mrb_const_name_p() ─── 名前チェック
    ├─ mrb_vm_define_class() ─── RClass生成・初期化
    │      ├─ mrb_obj_alloc() ─── RClass構造体割り当て
    │      └─ mt_new() ─── メソッドテーブル初期化
    └─ setup_class() ─── 定数登録

mrb_define_method_id()
    └─ mt_put() ─── メソッドテーブルへの追加

mrb_method_search_vm()
    └─ [クラス階層上方走査]
           └─ mt_get() ─── メソッドテーブル検索
```

### データフロー図

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

クラス名・親クラス ────────▶ mrb_define_class()          ──▶ struct RClass*
関数ポインタ・引数仕様 ───▶ mrb_define_method()         ──▶ メソッドテーブル更新
メソッド名・レシーバ ─────▶ mrb_method_search_vm()      ──▶ mrb_method_t
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| class.c | `src/class.c` | ソース | Classクラス本体（4394行） |
| class.h | `include/mruby/class.h` | ヘッダ | RClass構造体定義 |
| internal.h | `include/mruby/internal.h` | ヘッダ | mrb_mt_tbl, mrb_mt_entry構造体定義 |
| mruby.h | `include/mruby.h` | ヘッダ | mrb_method_t構造体定義 |
