# 通知設計書 21-TimeoutException

## 概要

本ドキュメントは、HH\Lib\OS\TimeoutException クラスの設計仕様を定義する。TimeoutExceptionは、操作がタイムアウトした際にスローされる例外クラスであり、C言語のerrno値 ETIMEDOUT（Connection timed out）に対応する。

### 本通知の処理概要

TimeoutExceptionは、ネットワーク接続やI/O操作などにおいてタイムアウトが発生した際に、呼び出し元に対してエラー状態を通知するための例外クラスである。

**業務上の目的・背景**：ネットワーク通信やファイルI/Oなどの非同期操作において、応答が一定時間内に返ってこない場合、無限に待機し続けることはシステムリソースの浪費や処理のハングアップにつながる。TimeoutExceptionは、このようなタイムアウト状態を明確に通知し、呼び出し元が適切なエラーハンドリング（リトライ、フォールバック、ユーザーへの通知など）を行えるようにする目的で設計されている。

**通知の送信タイミング**：TimeoutExceptionは以下のような状況でスローされる：
- TCPソケット接続時に指定したタイムアウト時間を超過した場合
- 非同期読み取り操作（readAllAsync）でタイムアウトが発生した場合
- 非同期書き込み操作でタイムアウトが発生した場合
- その他、OSレベルでETIMEDOUTが報告される操作

**通知の受信者**：例外をキャッチする呼び出し元コード（アプリケーション層）が受信者となる。開発者はcatch文でTimeoutExceptionを捕捉し、適切な処理を行う。

**通知内容の概要**：例外メッセージとして「ETIMEDOUT(110): {操作の説明}」形式のエラーメッセージが含まれる。getErrno()メソッドでErrno::ETIMEDOUTを取得可能。

**期待されるアクション**：
- リトライ処理の実行（ネットワーク一時障害の場合）
- タイムアウト値の調整
- ユーザーへのエラー通知
- 代替処理（フォールバック）の実行

## 通知種別

例外（Exception） - プログラム実行時のエラー通知

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（throw文による例外スロー） |
| 優先度 | 高（処理を中断） |
| リトライ | 呼び出し元の実装に依存 |

### 送信先決定ロジック

例外はコールスタックを遡って伝播し、最初にマッチするcatchブロックで捕捉される。捕捉されない場合はプログラムが異常終了する。

## 通知テンプレート

### 例外メッセージ形式

| 項目 | 内容 |
|-----|------|
| フォーマット | `ETIMEDOUT({errno値}): {操作説明}` |
| 例 | `ETIMEDOUT(110): connect` |

### 本文テンプレート

```
ETIMEDOUT(110): {operation_description}
```

### 添付ファイル

なし（例外オブジェクトとしてスタックトレースを含む）

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| errno | エラー番号（ETIMEDOUT） | OS\Errno::ETIMEDOUT | Yes |
| operation_description | 操作の説明 | 呼び出し元から渡されるメッセージ | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| システム呼び出し | socket_connect_async | 接続タイムアウト | TCPソケット接続がタイムアウト |
| API呼び出し | readAllAsync | タイムアウトパラメータ超過 | 読み取り操作のタイムアウト |
| API呼び出し | writeAllAsync | タイムアウトパラメータ超過 | 書き込み操作のタイムアウト |
| システム呼び出し | その他OSレベル操作 | ETIMEDOUT発生 | OSがタイムアウトを報告 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| タイムアウト未指定 | タイムアウトがnullの場合は無期限待機 |
| 正常完了 | 操作が正常に完了した場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[操作開始] --> B[タイムアウト監視開始]
    B --> C{操作完了?}
    C -->|Yes| D[正常終了]
    C -->|No| E{タイムアウト?}
    E -->|No| C
    E -->|Yes| F[TimeoutException生成]
    F --> G[例外スロー]
    G --> H[呼び出し元でキャッチ]
```

## データベース参照・更新仕様

### 参照テーブル一覧

なし（例外クラスはデータベースを参照しない）

### 更新テーブル一覧

なし（例外クラスはデータベースを更新しない）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| TimeoutException | ETIMEDOUT発生時 | 呼び出し元でキャッチして処理 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 呼び出し元の実装に依存 |
| リトライ間隔 | 呼び出し元の実装に依存 |
| リトライ対象エラー | TimeoutException |

## 配信設定

### レート制限

なし（例外の発生頻度に制限なし）

### 配信時間帯

なし（例外は発生時即座にスロー）

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

- 例外メッセージに機密情報を含めない
- スタックトレースのログ出力時は注意が必要
- 本番環境では詳細なエラー情報をユーザーに表示しない

## 備考

- TimeoutExceptionはOS\ErrnoExceptionを継承している
- ETIMEDOUT（110）はPOSIX標準のエラーコード
- Linuxでは110、macOSでは60がETIMEDOUTの値となる

---

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

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

### 推奨読解順序

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

まず、Errno列挙型とErrnoExceptionクラスの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Errno.php | `src/os/Errno.php` | Errno列挙型の定義、特にETIMEDOUTの値（行153） |
| 1-2 | ErrnoException.php | `src/os/ErrnoException.php` | 基底クラスErrnoExceptionの構造（行52-76） |

**読解のコツ**: Hackの列挙型（enum）はPHPと異なり型安全である。Errno::ETIMEDOUTで値を取得できる。

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

TimeoutExceptionがどこで生成・スローされるかを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ErrnoException.php | `src/os/ErrnoException.php` | TimeoutExceptionクラスの定義（行226-234） |
| 2-2 | Errno.php | `src/os/_Private/Errno.php` | throw_errno関数でのTimeoutException選択ロジック（行27、70-85） |

**主要処理フロー**:
1. **行226-228**: TimeoutExceptionのコンストラクタ、メッセージを親クラスに渡す
2. **行231-233**: _getValidErrno()でErrno::ETIMEDOUTを返す

#### Step 3: 例外スロー箇所を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | socket_connect_async.php | `src/network/_Private/socket_connect_async.php` | 接続タイムアウト時のスロー（行44） |
| 3-2 | ReadHandleConvenienceMethodsTrait.php | `src/io/ReadHandleConvenienceMethodsTrait.php` | 読み取りタイムアウト（行42） |
| 3-3 | WriteHandleConvenienceMethodsTrait.php | `src/io/WriteHandleConvenienceMethodsTrait.php` | 書き込みタイムアウト（行41） |

**主要処理フロー**:
- **socket_connect_async.php 行44**: `_OS\throw_errno(OS\Errno::ETIMEDOUT, 'connect');`

#### Step 4: テストコードを参照する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | PipeTest.php | `tests/io/PipeTest.php` | TimeoutExceptionのテスト（行147-152） |

**主要処理フロー**:
- **行147-152**: readAllAsyncでタイムアウトを1ナノ秒に設定し、TimeoutExceptionがスローされることを検証

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

```
アプリケーションコード
    │
    ├─ IO\ReadHandle::readAllAsync($timeout)
    │      │
    │      └─ ReadHandleConvenienceMethodsTrait
    │             └─ TimeoutException スロー (ETIMEDOUT)
    │
    ├─ Network\_Private\socket_connect_async()
    │      │
    │      └─ _OS\throw_errno(Errno::ETIMEDOUT, ...)
    │             │
    │             └─ _Private\_OS\get_throw_errno_impl()
    │                    │
    │                    └─ TimeoutException スロー
    │
    └─ その他ETIMEDOUT発生箇所
           │
           └─ TimeoutException スロー
```

### データフロー図

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

タイムアウト発生 ───▶ ETIMEDOUT検出 ───▶ TimeoutException生成
                           │
                           ▼
                    throw_errno()呼び出し
                           │
                           ▼
                    適切な例外クラス選択
                           │
                           ▼
                    TimeoutException スロー ───▶ 呼び出し元でcatch
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ErrnoException.php | `src/os/ErrnoException.php` | ソース | TimeoutExceptionクラス定義（行226-234） |
| Errno.php | `src/os/Errno.php` | ソース | ETIMEDOUT定数定義（行153） |
| Errno.php | `src/os/_Private/Errno.php` | ソース | throw_errno関数、例外マッピング |
| socket_connect_async.php | `src/network/_Private/socket_connect_async.php` | ソース | 接続タイムアウト時のスロー箇所 |
| ReadHandleConvenienceMethodsTrait.php | `src/io/ReadHandleConvenienceMethodsTrait.php` | ソース | 読み取りタイムアウト時のスロー箇所 |
| WriteHandleConvenienceMethodsTrait.php | `src/io/WriteHandleConvenienceMethodsTrait.php` | ソース | 書き込みタイムアウト時のスロー箇所 |
| PipeTest.php | `tests/io/PipeTest.php` | テスト | TimeoutExceptionのテストコード |
