# 機能設計書 29-リクエスト型情報取得

## 概要

本ドキュメントは、libuv の `uv_req_get_type()` および `uv_req_type_name()` API によるリクエストの型情報取得機能について、その設計仕様を記述する。

### 本機能の処理概要

本機能は2つの関数で構成される。`uv_req_get_type()` はリクエストインスタンスから型列挙値を取得し、`uv_req_type_name()` は型列挙値から人間可読な文字列名を取得する。

**業務上の目的・背景**：libuv のリクエストは `uv_req_t` の抽象基底型として統一的に扱われることが多い。`uv_cancel()` のようにリクエスト型に基づいて処理を分岐させる場合や、デバッグログでリクエスト情報を出力する場合に、リクエストの具体的な型を判定・表示する機能が必要となる。`uv_handle_get_type()`/`uv_handle_type_name()`（No.22）のリクエスト版に相当する。

**機能の利用シーン**：リクエスト型に基づく処理分岐、デバッグログへのリクエスト型情報出力、FFI バインディングでのリクエスト型識別に使用される。

**主要な処理内容**：
1. `uv_req_get_type()`: リクエスト構造体の `type` フィールドを直接返却する
2. `uv_req_type_name()`: `UV_REQ_TYPE_MAP` マクロによる switch 文でリクエスト型列挙値を文字列に変換する
3. 未知の型（UV_REQ_TYPE_MAX, UV_UNKNOWN_REQ、UV_REQ_TYPE_PRIVATE 範囲含む）の場合は NULL を返却する

**関連システム・外部連携**：特になし。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | リクエスト基底 | 主機能 | uv_req_get_type()/uv_req_type_name()による型情報取得のAPI定義 |

## 機能種別

データ参照（リクエスト型情報の取得）

## 入力仕様

### 入力パラメータ

#### uv_req_get_type()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| req | const uv_req_t* | Yes | 型情報を取得するリクエストへのポインタ | NULLでないこと |

#### uv_req_type_name()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | uv_req_type | Yes | 文字列名を取得したいリクエスト型列挙値 | UV_REQ_TYPE_MAP に含まれる型であること |

### 入力データソース

関数の引数として直接指定される。

## 出力仕様

### 出力データ

#### uv_req_get_type()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | uv_req_type | リクエストの型を示す列挙値 |

#### uv_req_type_name()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | const char* | リクエスト型の文字列名（例: "connect", "write", "fs"等）。未知の型の場合は NULL |

### 出力先

関数の戻り値として呼び出し元に返却される。

## 処理フロー

### 処理シーケンス

```
uv_req_get_type(req):
1. req->type を返却

uv_req_type_name(type):
1. switch(type) で分岐
   ├─ UV_REQ_TYPE_MAP(XX) 展開: 各型の文字列名を返却
   │   例: UV_CONNECT → "connect", UV_FS → "fs"
   ├─ UV_REQ_TYPE_MAX / UV_UNKNOWN_REQ → break (NULL返却)
   └─ default (UV_REQ_TYPE_PRIVATE含む) → break (NULL返却)
2. NULL を返却
```

### フローチャート

```mermaid
flowchart TD
    A[uv_req_type_name 呼び出し] --> B{type の判定}
    B -->|UV_REQ_TYPE_MAP の型| C["対応する文字列を返却"]
    B -->|UV_REQ_TYPE_MAX / UV_UNKNOWN_REQ| D["NULL を返却"]
    B -->|default| D
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-29-01 | 型文字列の命名規則 | 型名は小文字で返却される（例: "connect", "fs", "work"） | 常時 |
| BR-29-02 | PRIVATE型の処理 | UV_REQ_TYPE_PRIVATE 範囲の型にはNULLを返却する | default節に到達する場合 |
| BR-29-03 | breakによるNULL返却 | UV_HANDLE_TYPE_MAP版と異なり、switch文を break で抜けて末尾の return NULL に到達する | UV_UNKNOWN_REQ, UV_REQ_TYPE_MAX, default の場合 |

### 計算ロジック

`uv_req_get_type()` は構造体フィールドの直接参照。`uv_req_type_name()` は X マクロパターンにより `#lc` で型名を文字列に変換する。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NULL | 未知の型 | uv_req_type_name() に未知のリクエスト型が渡された場合 | 呼び出し元でNULLチェックを行う |

### リトライ仕様

リトライは不要。

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

該当なし。

## パフォーマンス要件

両関数ともO(1)で完了する。

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

特になし。

## 備考

- `uv_req_type_name()` が返却する文字列はリテラル文字列であり、呼び出し元で解放してはならない。
- `uv_handle_type_name()` と異なり、UV_FILE のような特別なcase文はない。
- UV_REQ_TYPE_PRIVATE はプラットフォーム固有のリクエスト型用に予約されている。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **179-190行目**: UV_REQ_TYPE_MAP マクロ定義。全リクエスト型を列挙 |
| 1-2 | uv.h | `include/uv.h` | **207-214行目**: uv_req_type 列挙型。UV_UNKNOWN_REQ, UV_REQ_TYPE_PRIVATE, UV_REQ_TYPE_MAX を含む |
| 1-3 | uv.h | `include/uv.h` | **432-439行目**: UV_REQ_FIELDS マクロ。type フィールドが含まれる |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | **493行目**: uv_req_get_type() の宣言 |
| 2-2 | uv.h | `include/uv.h` | **494行目**: uv_req_type_name() の宣言 |

#### Step 3: 実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | **52-63行目**: uv_req_type_name() の実装 |
| 3-2 | uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | **65-67行目**: uv_req_get_type() の実装 |

**主要処理フロー**:
- **52行目**: uv_req_type_name 関数開始
- **53行目**: switch(type)
- **54行目**: `#define XX(uc,lc) case UV_##uc: return #lc;` マクロで文字列化
- **55行目**: UV_REQ_TYPE_MAP(XX) で全型を展開
- **57-59行目**: UV_REQ_TYPE_MAX, UV_UNKNOWN_REQ, default の場合 break
- **62行目**: return NULL
- **65-67行目**: uv_req_get_type は req->type を直接返却

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

```
uv_req_get_type(req)
    └─ return req->type

uv_req_type_name(type)
    └─ switch(type)
           ├─ case UV_REQ:      return "req"
           ├─ case UV_CONNECT:  return "connect"
           ├─ case UV_WRITE:    return "write"
           ├─ case UV_FS:       return "fs"
           ├─ ... (他の型)
           └─ default:          return NULL
```

### データフロー図

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

uv_req_t* ────────▶ req->type 参照 ──────────▶ uv_req_type (列挙値)

uv_req_type ──────▶ switch + #lc 文字列化 ──▶ const char* (型名文字列)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | API宣言、UV_REQ_TYPE_MAP定義、uv_req_type列挙型定義 |
| uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | ソース | uv_req_get_type() / uv_req_type_name() の実装 |
