# 画面設計書 25-スレッドプール

## 概要

本ドキュメントは、libuvドキュメントサイトにおけるスレッドプール（`uv_work_t`）APIリファレンスページの画面設計書である。スレッドプールを使った非同期処理実行のAPI定義を記載する。

### 本画面の処理概要

本ページは、libuvのスレッドプール機能のAPIリファレンスを提供する。ユーザーコードをスレッドプール上で実行し、完了時にイベントループスレッドで通知を受ける仕組みのAPIを定義する。ファイルI/O操作やDNS解決も内部的にこのスレッドプールを使用している。

**業務上の目的・背景**：CPU集約的な処理やブロッキングI/O処理をイベントループスレッドから分離し、イベントループのブロッキングを防ぐ必要がある。libuvのスレッドプールはこのような非同期処理パターンを提供する。デフォルトサイズは4スレッドだが、UV_THREADPOOL_SIZE環境変数で最大1024まで変更可能である。

**画面へのアクセス方法**：トップページからAPIドキュメント一覧（api.rst）を経由し、スレッドプールリンクをクリックして本ページに遷移する。

**主要な操作・処理内容**：
1. ワークリクエストの投入（`uv_queue_work`）のAPI仕様確認
2. ワークコールバック（`uv_work_cb`）とアフターワークコールバック（`uv_after_work_cb`）の仕様確認
3. `uv_cancel`によるリクエストキャンセルの確認

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：リクエスト基底（request.rst）へのseealsoリンク
- 関連：スレッドガイド（guide/threads.rst）

**権限による表示制御**：なし（公開ドキュメント）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 124 | ワークキュー投入 | 主機能 | uv_queue_work()によるスレッドプール非同期実行のAPI定義 |
| 26 | リクエストキャンセル | 補助機能 | uv_cancel()によるワークリクエストキャンセルのAPI定義 |

## 画面種別

APIリファレンス（詳細表示）

## URL/ルーティング

`/docs/src/threadpool.rst` (Sphinx生成後: `/threadpool.html`)

## 入出力項目

| API関数 | パラメータ名 | 型 | 入出力 | 説明 |
|---------|-------------|-----|--------|------|
| uv_queue_work | loop | uv_loop_t* | 入力 | イベントループ |
| uv_queue_work | req | uv_work_t* | 入出力 | ワークリクエスト |
| uv_queue_work | work_cb | uv_work_cb | 入力 | スレッドプール上で実行されるコールバック |
| uv_queue_work | after_work_cb | uv_after_work_cb | 入力 | 完了後イベントループスレッドで実行されるコールバック |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | Thread pool work scheduling | ページタイトル |
| 概要説明 | libuv provides a threadpool... | スレッドプールの概要・サイズ設定・グローバル共有の説明 |
| Data types | uv_work_t, uv_work_cb, uv_after_work_cb | データ型の定義 |
| Public members | loop | 公開メンバー |
| API | uv_queue_work | ワーク投入関数 |
| note | スレッドセーフティ | 関数自体はスレッドセーフではない旨の注意 |

## イベント仕様

### 1-ワーク実行と完了通知

`uv_queue_work`で投入されたwork_cbがスレッドプール上で実行される。完了後、after_work_cbがイベントループスレッドで呼び出される。after_work_cbのstatusがUV_ECANCELEDの場合、uv_cancel()でキャンセルされたことを示す。

### 2-seealsoリンク遷移

ページ末尾の「See also」セクションから `uv_req_t` の基底APIリファレンスページへ遷移する。

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

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

該当なし（本プロジェクトはCライブラリであり、データベースは使用しない）

## メッセージ仕様

| メッセージ種別 | 条件 | 内容 |
|--------------|------|------|
| note | スレッドセーフティ | グローバルスレッドプールは全イベントループで共有されるが関数はスレッドセーフではない |
| versionchanged | v1.30.0 | UV_THREADPOOL_SIZE最大値が128から1024に拡大 |
| versionchanged | v1.45.0 | スレッドスタックサイズが8MBに変更 |
| versionchanged | v1.50.0 | スレッド名のデフォルトがlibuv-workerに変更 |

## 例外処理

| エラーコード | 発生条件 | 説明 |
|-------------|---------|------|
| UV_ECANCELED | uv_cancel()でキャンセル時 | after_work_cbのstatusに設定される |

## 備考

- スレッドプールはグローバルで全イベントループ間で共有される
- デフォルトサイズは4スレッド、UV_THREADPOOL_SIZE環境変数で最大1024まで設定可能
- v1.45.0以降スレッドスタックは8MBに設定される
- v1.50.0以降スレッド名のデフォルトはlibuv-worker
- ファイルI/O操作、getaddrinfo、getnameinfo は内部的にスレッドプールを使用
- libuvは起動時にUV_THREADPOOL_SIZEで指定された最大数のスレッドを事前割り当てする

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_work_t, uv_work_cb, uv_after_work_cbの定義 |

**読解のコツ**: uv_work_tはuv_req_tを継承しており、loopメンバーを持つ。

#### Step 2: スレッドプール実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | threadpool.c | `src/threadpool.c` | スレッドプールの初期化、ワーク投入、スレッド実行ループ |

**主要処理フロー**:
- `uv_queue_work()`: ワークリクエストの初期化とキュー投入
- `worker()`: スレッドプールのワーカースレッドメインループ
- ワーカースレッドがwork_cbを実行
- 完了後、イベントループにafter_work_cbの実行を通知

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

```
uv_queue_work() [src/threadpool.c]
    |
    +-- uv__work_submit()
           |
           +-- init_threads() [初回呼び出し時のみ]
           |       +-- uv_thread_create() x UV_THREADPOOL_SIZE
           |
           +-- キューにワーク追加
           +-- uv_cond_signal() [ワーカースレッドを起床]

worker() [スレッドプールワーカー]
    |
    +-- w->work() [= work_cb実行]
    +-- uv_async_send() [完了通知]

イベントループスレッド
    +-- after_work_cb() [ユーザーコールバック]
```

### データフロー図

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

work_cb, after_work_cb
         |
         v
uv_queue_work() -------> ワークキュー -------> ワーカースレッド
                                                    |
                                              work_cb実行
                                                    |
                                              完了通知(async)
                                                    |
                                              after_work_cb実行
                                              (イベントループスレッド)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| threadpool.rst | `docs/src/threadpool.rst` | テンプレート | スレッドプールページのSphinxソース |
| uv.h | `include/uv.h` | ソース | uv_work_t等の公開API定義 |
| threadpool.c | `src/threadpool.c` | ソース | スレッドプール実装 |
| api.rst | `docs/src/api.rst` | テンプレート | API一覧ページ（遷移元） |
| request.rst | `docs/src/request.rst` | テンプレート | リクエスト基底ページ（参照先） |
