# 画面設計書 8-リクエスト基底

## 概要

uv_req_tの基底APIリファレンスページ（request.rst）に関する画面設計書。全リクエスト型に共通する操作（キャンセル、サイズ取得、データ管理、型情報取得）のAPI定義を提供する。

### 本画面の処理概要

本画面はlibuvの全リクエスト型の基底となる `uv_req_t` のAPIリファレンスページである。リクエストのキャンセル、メタデータ取得、ユーザーデータ管理等の共通操作を定義する。

**業務上の目的・背景**：libuvのリクエストは短寿命の非同期操作を表す。ファイルI/O、DNS解決、スレッドプール実行等のリクエストに共通する操作（キャンセル、型情報取得等）を基底型APIとして提供することで、統一的なリクエスト管理を可能にする。ハンドルと異なりリクエストは完了時に自動的にクローズされるため、明示的なクローズ操作は不要である（uv_fs_tとuv_getaddrinfo_tの追加クリーンアップを除く）。

**画面へのアクセス方法**：APIドキュメント一覧ページ（api.rst）の "uv_req_t --- Base request" リンク押下、または `/request.html` に直接アクセスする。

**主要な操作・処理内容**：
1. データ型定義の参照 - uv_req_t, uv_any_req, uv_req_type
2. キャンセルAPI参照 - uv_cancel()によるリクエスト取り消し
3. サイズ取得API参照 - uv_req_size()
4. データアクセサAPI参照 - uv_req_get_data()/uv_req_set_data()
5. 型情報API参照 - uv_req_get_type()/uv_req_type_name()

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：Sphinx相互参照を通じてfs.rst, dns.rst, threadpool.rst等の関連APIページ

**権限による表示制御**：なし。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | リクエストキャンセル | 主機能 | uv_cancel()による未処理リクエストキャンセルのAPI定義 |
| 27 | リクエストサイズ取得 | 主機能 | uv_req_size()によるリクエスト型メモリサイズ取得のAPI定義 |
| 28 | リクエストデータ取得・設定 | 主機能 | uv_req_get_data()/uv_req_set_data()によるユーザーデータ関連付けのAPI定義 |
| 29 | リクエスト型情報取得 | 主機能 | uv_req_get_type()/uv_req_type_name()による型情報取得のAPI定義 |

## 画面種別

APIリファレンスページ（リクエスト基底）

## URL/ルーティング

- ソースファイル: `docs/src/request.rst`
- 生成先URL: `/request.html`
- Sphinxアンカー: `.. _request:`

## 入出力項目

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| ページタイトル | 出力 | テキスト | "uv_req_t --- Base request" |
| データ型定義 | 出力 | 型定義 | uv_req_t, uv_any_req, uv_req_type |
| パブリックメンバ | 出力 | メンバ定義 | data, type の2メンバ |
| API関数定義 | 出力 | 関数シグネチャ+説明 | 7個のAPI関数/マクロ |

## 表示項目

### Data types セクション

| データ型 | 説明 |
|----------|------|
| uv_req_t | 基底リクエスト型。全リクエストはこの型にキャスト可能 |
| uv_any_req | 全リクエスト型のユニオン |
| uv_req_type | リクエスト種別列挙型（UV_REQ, UV_CONNECT, UV_WRITE, UV_SHUTDOWN, UV_UDP_SEND, UV_FS, UV_WORK, UV_GETADDRINFO, UV_GETNAMEINFO等） |

### Public members セクション

| メンバ | 型 | 説明 |
|--------|-----|------|
| uv_req_t.data | void* | ユーザー定義データ。libuvは使用しない |
| uv_req_t.type | uv_req_type | リクエスト型（読み取り専用） |

### API セクション

| API関数 | シグネチャ | 説明 | バージョン |
|---------|-----------|------|-----------|
| UV_REQ_TYPE_MAP | `UV_REQ_TYPE_MAP(iter_macro)` | 全リクエスト型を列挙するマクロ | - |
| uv_cancel | `int uv_cancel(uv_req_t* req)` | 保留中リクエストのキャンセル | - |
| uv_req_size | `size_t uv_req_size(uv_req_type type)` | リクエストサイズ取得（FFI用） | - |
| uv_req_get_data | `void* uv_req_get_data(const uv_req_t* req)` | req->data取得 | v1.19.0 |
| uv_req_set_data | `void uv_req_set_data(uv_req_t* req, void* data)` | req->data設定 | v1.19.0 |
| uv_req_get_type | `uv_req_type uv_req_get_type(const uv_req_t* req)` | req->type取得 | v1.19.0 |
| uv_req_type_name | `const char* uv_req_type_name(uv_req_type type)` | 型名文字列取得 | v1.19.0 |

## イベント仕様

### 1-Sphinx相互参照リンク押下

`:c:type:` 参照リンク（uv_fs_t, uv_getaddrinfo_t, uv_work_t等）を押下すると、対応するAPIリファレンスページへ遷移する。

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | N/A | N/A | データベースアクセスなし |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| N/A | N/A | N/A | 静的HTMLのため動的メッセージなし |

## 例外処理

本画面は静的リファレンスドキュメントのため、画面固有の例外処理は存在しない。

## 備考

- uv_cancel()はuv_fs_t, uv_getaddrinfo_t, uv_getnameinfo_t, uv_random_t, uv_work_tのみサポート
- キャンセルされたリクエストのコールバックはstatus=UV_ECANCELEDで呼ばれる（uv_fs_tの場合はreq->result=UV_ECANCELED）
- コールバックが呼ばれるまでリクエストメモリの解放は安全でない
- リクエストは完了時に自動クローズされるため、ハンドルのようなuv_close()呼び出しは不要

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_req_type列挙型、UV_REQ_TYPE_MAPマクロの定義 |
| 1-2 | request.rst | `docs/src/request.rst` | リクエスト型の列挙値一覧（UV_REQ, UV_CONNECT等） |

**読解のコツ**: リクエスト型はハンドル型と比べて数が少ない。uv_req_type列挙型の各値がどのリクエスト構造体に対応するかを把握する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv-common.c | `src/uv-common.c` | uv_req_size()（174行目）- UV_REQ_TYPE_MAPマクロ展開によるサイズ計算 |

**主要処理フロー**:
1. **uv-common.c 174-180行目**: `uv_req_size()` - switch-caseでリクエスト型に対応するsizeof値を返却

#### Step 3: キャンセル処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | request.rst | `docs/src/request.rst` | uv_cancel()のAPI仕様。サポート対象型とキャンセル報告方法 |

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

```
uv_cancel(req) [ドキュメント定義]
    |
    +-- 対象リクエスト型の確認
    |       +-- uv_fs_t: req->result = UV_ECANCELED
    |       +-- uv_work_t: callback(status=UV_ECANCELED)
    |       +-- uv_getaddrinfo_t: callback(status=UV_ECANCELED)
    |       +-- uv_getnameinfo_t: callback(status=UV_ECANCELED)
    |       +-- uv_random_t: callback(status=UV_ECANCELED)
    |
    +-- 非サポート型: エラー返却

uv_req_size(type) [src/uv-common.c:174]
    |
    +-- UV_REQ_TYPE_MAP(XX) マクロ展開
            +-- case UV_REQ: return sizeof(uv_req_t)
            +-- case UV_CONNECT: return sizeof(uv_connect_t)
            +-- ...
```

### データフロー図

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

uv_req_t* req       --> uv_cancel()            --> int (0:成功, <0:エラー)
                         (キャンセル要求)

uv_req_type type    --> uv_req_size()           --> size_t (構造体サイズ)
                         (UV_REQ_TYPE_MAP展開)

uv_req_t* req       --> uv_req_get_data()       --> void* (ユーザーデータ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| request.rst | `docs/src/request.rst` | テンプレート | リクエスト基底ページのRSTソース |
| uv.h | `include/uv.h` | ソース | uv_req_t, uv_req_type等のパブリック型定義 |
| uv-common.c | `src/uv-common.c` | ソース | uv_req_size()等のクロスプラットフォーム実装 |
