# 機能設計書 82-exit関数

## 概要

本ドキュメントは、mrubyのmruby-exit gemが提供するKernel#exitおよびKernel#exit!メソッドの機能設計を記述する。これらのメソッドは、Rubyスクリプトの実行を終了させる機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：プログラムの正常終了や異常終了を制御するために、明示的なプロセス終了機能が必要である。exitはSystemExit例外を発生させることで、begin/rescueによるクリーンアップ処理の実行を可能にする。exit!は即座にプロセスを終了し、終了ハンドラを実行しない。

**機能の利用シーン**：コマンドラインツールの終了コード制御、エラー発生時の強制終了、シグナルハンドラからの終了処理、対話型シェル（mirb）からの終了等。

**主要な処理内容**：
1. `exit(status)` - SystemExit例外を発生させてRubyスクリプトを終了する。statusはtrue（成功）、false（失敗）、または整数で指定可能
2. `exit!(status)` - exit handlersを実行せず即座にプロセスを終了する。Cのexit()を直接呼び出す
3. SystemExitクラスの定義

**関連システム・外部連携**：Cランタイムのexit()関数、mrubyの例外処理システム

**権限による制御**：特になし。Kernelモジュールのプライベートメソッドとして全オブジェクトから利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI | 主画面 | mrubyスクリプト内でexit/exit!を呼び出す |

## 機能種別

システム制御処理（プロセス終了制御）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| status | Boolean/Integer | No | 終了ステータス。デフォルトはtrue（成功） | true=EXIT_SUCCESS, false=EXIT_FAILURE, 整数はそのまま使用 |

### 入力データソース

Ruby関数呼び出しの引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 終了ステータス | Integer | OSに返すプロセス終了コード |

### 出力先

OSのプロセス終了コード

## 処理フロー

### 処理シーケンス

```
1. exit(status)の場合
   ├─ get_status()でstatusを解釈
   │   ├─ 引数なし/true: EXIT_SUCCESS (0)
   │   ├─ false: EXIT_FAILURE (1)
   │   └─ 整数: mrb_as_int()で変換
   ├─ SystemExitオブジェクトを生成
   ├─ MRB_EXC_EXITフラグを設定
   ├─ statusをインスタンス変数@statusに設定
   └─ mrb_exc_raiseでSystemExitを送出

2. exit!(status)の場合
   ├─ get_status()でstatusを解釈
   └─ C言語のexit()を直接呼び出し（戻らない）
```

### フローチャート

```mermaid
flowchart TD
    A[exit/exit! 呼び出し] --> B[get_status で終了コード決定]
    B --> C{exit! ?}
    C -->|Yes| D[C exit 直接呼び出し]
    D --> E[プロセス即時終了]
    C -->|No| F[SystemExit例外生成]
    F --> G[MRB_EXC_EXITフラグ設定]
    G --> H[status インスタンス変数設定]
    H --> I[mrb_exc_raise で例外送出]
    I --> J{rescue される?}
    J -->|Yes| K[rescue ブロック実行]
    J -->|No| L[プロセス終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-82-1 | デフォルトステータス | 引数省略時はtrue（EXIT_SUCCESS=0）として扱う | 常時 |
| BR-82-2 | Boolean変換 | true→EXIT_SUCCESS(0)、false→EXIT_FAILURE(1) | Boolean引数時 |
| BR-82-3 | SystemExit捕捉可能 | exitはSystemExit例外としてrescue可能 | exit呼び出し時 |
| BR-82-4 | exit!は捕捉不可 | exit!はC exit()を直接呼び出し、rescue不可 | exit!呼び出し時 |

### 計算ロジック

`get_status` 関数のステータス変換:
- `mrb_true_p(status)` → EXIT_SUCCESS (0)
- `mrb_false_p(status)` → EXIT_FAILURE (1)
- その他 → `(int)mrb_as_int(mrb, status)` で整数変換

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | SystemExit | exit()が呼ばれた場合 | rescue SystemExitで捕捉可能 |
| - | TypeError | statusが変換不能な場合 | mrb_as_intが発生 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

特になし（プロセス終了処理）

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

exit!はexit handlersをスキップするため、クリーンアップ処理が実行されない可能性がある。

## 備考

- SystemExitクラスはExceptionクラスを直接継承する（StandardErrorではない）
- MRB_EXC_EXITフラグにより、mruby VMがexit例外を特別に扱える

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | mruby_exit.c | `mrbgems/mruby-exit/src/mruby_exit.c` | EXIT_SUCCESS/EXIT_FAILURE定数定義（7-13行目） |

**読解のコツ**: `MRB_EXC_EXIT` フラグは `mruby/error.h` で定義されている。このフラグがセットされた例外は、mruby VMにとってプロセス終了を意味する特別な例外として扱われる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | mruby_exit.c | `mrbgems/mruby-exit/src/mruby_exit.c` | `mrb_mruby_exit_gem_init`（72-78行目）でクラス・メソッド登録を確認 |

**主要処理フロー**:
1. **75行目**: `mrb_define_class_id` でSystemExitクラスをE_EXCEPTION（Exception）のサブクラスとして定義
2. **76行目**: `mrb_define_private_method_id` でKernel#exitを登録（引数0-1個）
3. **77行目**: `mrb_define_private_method_id` でKernel#exit!を登録（MRB_SYM_B = `exit!`）

#### Step 3: ステータス解析ヘルパーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | mruby_exit.c | `mrbgems/mruby-exit/src/mruby_exit.c` | `get_status`（15-24行目）でステータス変換ロジックを確認 |

**主要処理フロー**:
- **18行目**: デフォルト値としてmrb_true_value()を設定
- **20行目**: `mrb_get_args(mrb, "|o", &status)` でオプション引数取得
- **21行目**: trueならEXIT_SUCCESS返却
- **22行目**: falseならEXIT_FAILURE返却
- **23行目**: それ以外は `mrb_as_int()` で整数変換

#### Step 4: exit/exit!の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | mruby_exit.c | `mrbgems/mruby-exit/src/mruby_exit.c` | `f_exit`（41-52行目）でexit実装を確認 |
| 4-2 | mruby_exit.c | `mrbgems/mruby-exit/src/mruby_exit.c` | `f_exit_bang`（64-70行目）でexit!実装を確認 |

**主要処理フロー（f_exit）**:
- **44行目**: `get_status(mrb)` でステータスコード取得
- **45行目**: `mrb_obj_new` でSystemExitオブジェクト生成
- **47行目**: `MRB_EXC_EXIT` フラグを例外flagsに設定
- **48行目**: `mrb_iv_set` で@statusインスタンス変数にステータスコードを設定
- **49行目**: `mrb_exc_raise` でSystemExit例外を送出

**主要処理フロー（f_exit_bang）**:
- **67行目**: `exit(get_status(mrb))` でC言語のexit()を直接呼び出し

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

```
mrb_mruby_exit_gem_init
    │
    ├─ mrb_define_class_id(SystemExit)
    │
    ├─ mrb_define_private_method_id(exit) ──▶ f_exit
    │                                           ├─ get_status()
    │                                           ├─ mrb_obj_new(SystemExit)
    │                                           ├─ MRB_EXC_EXIT フラグ設定
    │                                           ├─ mrb_iv_set(@status)
    │                                           └─ mrb_exc_raise
    │
    └─ mrb_define_private_method_id(exit!) ──▶ f_exit_bang
                                                 ├─ get_status()
                                                 └─ exit() [Cランタイム]
```

### データフロー図

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

status(任意) ───▶ get_status() ───▶ 整数ステータスコード
                      │
                      ├─ f_exit: SystemExit例外送出
                      │   └─ rescue可能
                      │
                      └─ f_exit_bang: C exit()呼出
                          └─ 即時プロセス終了
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| mruby_exit.c | `mrbgems/mruby-exit/src/mruby_exit.c` | ソース | exit/exit!の実装 |
| mrbgem.rake | `mrbgems/mruby-exit/mrbgem.rake` | 設定 | gem仕様定義 |
