# 機能設計書：並行処理管理

## 1. 機能概要

### 1.1 機能名
並行処理管理（Concurrency Manager）

### 1.2 機能説明
複数のタスクを並列実行するための統一インターフェースを提供する機能。Fork、Process、Syncの3つのドライバを通じて、様々な並行処理戦略をサポートし、アプリケーションの性能向上を実現する。

### 1.3 関連画面
- なし（バックエンド専用機能）

## 2. 機能詳細

### 2.1 処理フロー

```
[アプリケーション]
       |
       v
[ConcurrencyManager] ──選択──> [ForkDriver]    ─> pcntl_fork による並列処理
       |                       [ProcessDriver] ─> Artisan コマンドによる並列処理
       |                       [SyncDriver]    ─> 同期的な順次実行
       v
[Driver Interface]
       |
       v
[結果の収集・統合]
```

### 2.2 クラス構成

| クラス名 | 役割 |
|---------|------|
| ConcurrencyManager | ドライバの管理・選択を行うマネージャー |
| ConcurrencyServiceProvider | サービスコンテナへの登録 |
| ForkDriver | pcntl_fork を使用したプロセスフォーク |
| ProcessDriver | Artisan コマンドを使用した並列実行 |
| SyncDriver | 同期的な順次実行（フォールバック） |
| Driver（Contract） | ドライバの共通インターフェース |

### 2.3 主要メソッド

#### ConcurrencyManager

| メソッド | 説明 | 引数 | 戻り値 |
|---------|------|------|--------|
| `driver()` | 指定ドライバまたはデフォルトドライバを取得 | `$name = null` | `Driver` |
| `createForkDriver()` | Fork ドライバを生成 | - | `ForkDriver` |
| `createProcessDriver()` | Process ドライバを生成 | - | `ProcessDriver` |
| `createSyncDriver()` | Sync ドライバを生成 | - | `SyncDriver` |
| `getDefaultDriver()` | デフォルトドライバ名を取得 | - | `string` |

#### Driver Interface

| メソッド | 説明 | 引数 | 戻り値 |
|---------|------|------|--------|
| `run()` | 複数のタスクを並列実行 | `Closure\|array $tasks` | `array` |
| `defer()` | タスクを遅延実行キューに追加 | `Closure $task` | `void` |

### 2.4 ビジネスルール

1. **ドライバ選択ルール**
   - デフォルトドライバは設定ファイル `concurrency.default` で指定
   - Fork ドライバは `pcntl` 拡張が必要
   - 拡張が利用できない環境では Sync ドライバにフォールバック

2. **並列実行ルール**
   - `run()` メソッドは全タスク完了まで待機
   - 各タスクの結果は配列で返却
   - エラーは例外としてスロー

3. **遅延実行ルール**
   - `defer()` はタスクをキューに追加するのみ
   - 実際の実行はアプリケーション終了時

## 3. 入出力仕様

### 3.1 入力

| 項目 | 型 | 説明 |
|-----|-----|------|
| tasks | `Closure[]` | 実行するタスクの配列 |
| driver | `string` | 使用するドライバ名（オプション） |

### 3.2 出力

| 項目 | 型 | 説明 |
|-----|-----|------|
| results | `array` | 各タスクの実行結果の配列 |

## 4. 依存関係

### 4.1 内部依存

| パッケージ | 用途 |
|-----------|------|
| Illuminate\Support\Manager | マネージャーパターンの基底クラス |
| Illuminate\Contracts\Concurrency\Driver | ドライバインターフェース |
| Illuminate\Process | プロセス実行 |

### 4.2 外部依存

| パッケージ | 用途 |
|-----------|------|
| spatie/fork | ForkDriver の実装基盤 |
| ext-pcntl | プロセスフォーク |

## 5. エラー処理

| エラー種別 | 発生条件 | 処理内容 |
|-----------|---------|---------|
| InvalidArgumentException | 不明なドライバ指定 | 例外スロー |
| RuntimeException | pcntl 拡張未インストール | Sync ドライバにフォールバック |
| ProcessException | 子プロセスの異常終了 | 例外スロー |

## 6. 設定項目

```php
// config/concurrency.php
return [
    'default' => env('CONCURRENCY_DRIVER', 'process'),
];
```

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

### 7.1 推奨読解順序

1. **Driver インターフェース** (`Contracts/Concurrency/Driver.php`)
   - **1-20行目**: 並行処理ドライバが実装すべき2つのメソッド `run()` と `defer()` を定義

2. **ConcurrencyManager** (`Concurrency/ConcurrencyManager.php`)
   - **16-25行目**: マネージャークラスの定義とデフォルトドライバの取得
   - **27-35行目**: `createForkDriver()` - Spatie Fork を使用したドライバ生成
   - **37-45行目**: `createProcessDriver()` - Artisan コマンドを使用したドライバ生成
   - **47-52行目**: `createSyncDriver()` - 同期ドライバ生成

3. **ForkDriver** (`Concurrency/ForkDriver.php`)
   - **15-30行目**: `run()` メソッド - Spatie Fork を使用した並列実行
   - **32-45行目**: `defer()` メソッド - 遅延実行の登録

4. **ProcessDriver** (`Concurrency/ProcessDriver.php`)
   - **20-60行目**: `run()` メソッド - Artisan コマンドを並列起動
   - **62-80行目**: シリアライズされたクロージャの実行

5. **SyncDriver** (`Concurrency/SyncDriver.php`)
   - **10-25行目**: `run()` メソッド - 単純な順次実行
   - **27-35行目**: `defer()` メソッド - 即時実行

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

```
Concurrency::run($tasks)
└── ConcurrencyManager::driver()
    └── ConcurrencyManager::createXxxDriver()
        └── XxxDriver::run($tasks)
            ├── [ForkDriver] Fork::new()->run(...)
            ├── [ProcessDriver] Process::pool(...)->start()->wait()
            └── [SyncDriver] array_map($task, $tasks)
```

### 7.3 データフロー図

```
[タスク配列]
    |
    v
[ConcurrencyManager]
    |
    +-- ドライバ選択 --> [設定ファイル参照]
    |
    v
[選択されたDriver]
    |
    +-- ForkDriver: pcntl_fork でプロセス分岐
    +-- ProcessDriver: php artisan concurrency:invoke で子プロセス起動
    +-- SyncDriver: 同一プロセスで順次実行
    |
    v
[各タスクの実行結果]
    |
    v
[結果配列として返却]
```

### 7.4 読解のコツ

- **Manager パターン**: Laravel の標準的なマネージャーパターンを使用。`createXxxDriver()` メソッドでドライバを遅延生成
- **Contract 活用**: `Driver` インターフェースにより、全ドライバが同一のメソッドシグネチャを保証
- **シリアライズ**: ProcessDriver では `Laravel\SerializableClosure` を使用してクロージャをシリアライズ

### 7.5 関連ファイル一覧

| ファイルパス | 種別 | 役割 |
|------------|------|------|
| `src/Illuminate/Concurrency/ConcurrencyManager.php` | Manager | ドライバ管理・生成 |
| `src/Illuminate/Concurrency/ConcurrencyServiceProvider.php` | ServiceProvider | サービス登録 |
| `src/Illuminate/Concurrency/ForkDriver.php` | Driver | Fork ベースの並列処理 |
| `src/Illuminate/Concurrency/ProcessDriver.php` | Driver | Process ベースの並列処理 |
| `src/Illuminate/Concurrency/SyncDriver.php` | Driver | 同期実行（フォールバック） |
| `src/Illuminate/Contracts/Concurrency/Driver.php` | Contract | ドライバインターフェース |
| `src/Illuminate/Concurrency/Console/InvokeSerializedClosureCommand.php` | Command | シリアライズされたクロージャ実行コマンド |

## 8. 使用例

```php
use Illuminate\Support\Facades\Concurrency;

// 複数タスクの並列実行
$results = Concurrency::run([
    fn () => $this->fetchUserData(),
    fn () => $this->fetchOrderHistory(),
    fn () => $this->fetchRecommendations(),
]);

// 特定ドライバの使用
$results = Concurrency::driver('fork')->run($tasks);

// 遅延実行
Concurrency::defer(fn () => $this->sendNotification());
```

## 9. 改版履歴

| バージョン | 日付 | 変更内容 |
|-----------|------|---------|
| 1.0.0 | - | 初版作成 |
