# 画面設計書 28-スレッド

## 概要

本ドキュメントは、libuvドキュメントサイトにおけるスレッドおよび同期プリミティブのAPIリファレンスページの画面設計書である。スレッド作成・管理、ミューテックス、読み書きロック、セマフォ、条件変数、バリア、ワンスガード、スレッドローカルストレージの各API定義を記載する。

### 本画面の処理概要

本ページは、libuvにおけるクロスプラットフォームのスレッドおよび同期プリミティブのAPIリファレンスを提供する。pthreads APIに概ね準拠したインターフェースで、スレッドの作成・結合・分離、CPU アフィニティ制御、優先度制御、スレッド名制御、及び各種同期機構（ミューテックス、読み書きロック、セマフォ、条件変数、バリア）を提供する。

**業務上の目的・背景**：マルチスレッドプログラミングはパフォーマンス向上に不可欠であるが、プラットフォームごとにAPIが異なる（pthreads vs Win32 Threads）。libuvはこれらを統一的に抽象化し、移植可能なスレッドプログラミングを可能にする。

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

**主要な操作・処理内容**：
1. スレッド作成・結合・分離（`uv_thread_create` / `join` / `detach`）のAPI仕様確認
2. スレッド識別（`uv_thread_self` / `equal`）のAPI仕様確認
3. CPUアフィニティ制御のAPI仕様確認
4. スレッド優先度制御のAPI仕様確認
5. スレッド名制御のAPI仕様確認
6. ミューテックス操作のAPI仕様確認
7. 読み書きロック操作のAPI仕様確認
8. セマフォ操作のAPI仕様確認
9. 条件変数操作のAPI仕様確認
10. バリア操作のAPI仕様確認
11. ワンスガード操作のAPI仕様確認
12. スレッドローカルストレージ操作のAPI仕様確認

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 関連：スレッドガイド（guide/threads.rst）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 125 | スレッド作成 | 主機能 | uv_thread_create()/create_ex()によるスレッド作成のAPI定義 |
| 126 | スレッド結合・分離 | 主機能 | uv_thread_join()/detach()によるスレッド結合・分離のAPI定義 |
| 127 | スレッド識別 | 主機能 | uv_thread_self()/equal()によるスレッドID取得・比較のAPI定義 |
| 128 | スレッドアフィニティ制御 | 主機能 | uv_thread_setaffinity()/getaffinity()によるCPUアフィニティ制御のAPI定義 |
| 129 | スレッド優先度制御 | 主機能 | uv_thread_setpriority()/getpriority()によるスレッド優先度制御のAPI定義 |
| 130 | スレッドCPU取得 | 主機能 | uv_thread_getcpu()による実行中CPU取得のAPI定義 |
| 131 | スレッド名制御 | 主機能 | uv_thread_setname()/getname()によるスレッド名制御のAPI定義 |
| 132 | ミューテックス | 主機能 | uv_mutex_init()/destroy()/lock()/trylock()/unlock()のAPI定義 |
| 133 | 読み書きロック | 主機能 | uv_rwlock_init()/destroy()/rdlock()/wrlock()等のAPI定義 |
| 134 | セマフォ | 主機能 | uv_sem_init()/destroy()/post()/wait()/trywait()のAPI定義 |
| 135 | 条件変数 | 主機能 | uv_cond_init()/destroy()/signal()/broadcast()/wait()のAPI定義 |
| 136 | バリア | 主機能 | uv_barrier_init()/destroy()/wait()によるバリア同期のAPI定義 |
| 137 | ワンスガード | 主機能 | uv_once()による一度だけ実行保証のAPI定義 |
| 138 | スレッドローカルストレージ | 主機能 | uv_key_create()/delete()/get()/set()によるTLSのAPI定義 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

| API関数 | パラメータ名 | 型 | 入出力 | 説明 |
|---------|-------------|-----|--------|------|
| uv_thread_create | tid | uv_thread_t* | 出力 | スレッドID |
| uv_thread_create | entry | uv_thread_cb | 入力 | スレッドエントリポイント |
| uv_thread_create | arg | void* | 入力 | スレッドに渡す引数 |
| uv_thread_create_ex | params | const uv_thread_options_t* | 入力 | スレッドオプション（スタックサイズ等） |
| uv_thread_setaffinity | cpumask | char* | 入力 | CPUマスク |
| uv_thread_setaffinity | oldmask | char* | 出力 | 以前のCPUマスク |
| uv_thread_setname | name | const char* | 入力 | スレッド名 |
| uv_thread_getname | name | char* | 出力 | スレッド名格納バッファ |
| uv_thread_getname | size | size_t* | 入出力 | バッファサイズ |
| uv_mutex_init | handle | uv_mutex_t* | 出力 | ミューテックスハンドル |
| uv_sem_init | sem | uv_sem_t* | 出力 | セマフォハンドル |
| uv_sem_init | value | unsigned int | 入力 | 初期値 |
| uv_barrier_init | barrier | uv_barrier_t* | 出力 | バリアハンドル |
| uv_barrier_init | count | unsigned int | 入力 | 参加スレッド数 |
| uv_key_create | key | uv_key_t* | 出力 | TLSキー |
| uv_key_set | value | void* | 入力 | TLS値 |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | Threading and synchronization utilities | ページタイトル |
| 概要説明 | libuv provides cross-platform implementations... | スレッドプリミティブの概要 |
| Data types | uv_thread_t, uv_key_t, uv_once_t, uv_mutex_t等 | 全データ型定義 |
| Threads | スレッド操作関数群 | 作成・結合・分離・アフィニティ・優先度・名前 |
| Thread-local storage | TLS関数群 | キー作成・削除・取得・設定 |
| Once-only initialization | uv_once | 一度だけ初期化 |
| Mutex locks | ミューテックス関数群 | 初期化・破棄・ロック・アンロック |
| Read-write locks | 読み書きロック関数群 | 読みロック・書きロック |
| Semaphores | セマフォ関数群 | 初期化・投稿・待機 |
| Conditions | 条件変数関数群 | シグナル・ブロードキャスト・待機 |
| Barriers | バリア関数群 | 初期化・待機 |

## イベント仕様

### 1-スレッドエントリポイント実行

`uv_thread_create`で作成されたスレッドは、指定されたuv_thread_cb関数をエントリポイントとして実行を開始する。argパラメータが関数に渡される。

### 2-バリア同期

`uv_barrier_wait`は指定された数のスレッドが全てwaitするまでブロックする。戻り値 > 0 の場合は「シリアライザー」スレッドを示し、クリーンアップ処理の担当者を示す。

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

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

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

## メッセージ仕様

| メッセージ種別 | 条件 | 内容 |
|--------------|------|------|
| note | スレッドアフィニティ | macOSでは非サポート。Windowsではアトミックではない |
| note | uv_thread_getcpu | 現在Windows, Linux, FreeBSDのみ実装 |
| note | uv_thread_setname | Windows Server 2016では非サポート（UV_ENOSYS） |
| note | TLS | 総TLSサイズに制限がある場合がある |
| note | 条件変数 | スプリアスウェイクアップへの対処が必要 |
| note | バリア | uv_barrier_waitの戻り値 > 0 はシリアライザースレッドを示す |
| versionadded | 各API | 各APIが追加されたlibuvバージョン |

## 例外処理

| エラーコード | 発生条件 | 説明 |
|-------------|---------|------|
| UV_E* | uv_thread_create失敗時 | v1.4.1以降UV_E*エラーコードを返す |
| UV_ENOSYS | Windows Server 2016でsetname/getname使用時 | 未サポートプラットフォーム |
| UV_ENOTSUP | macOSでsetaffinity/getaffinity使用時 | 未サポートプラットフォーム |

## 備考

- APIは概ねpthreads APIに準拠している
- uv_thread_create_exはv1.26.0で追加、スタックサイズの指定が可能
- uv_thread_detachはv1.50.0で追加
- スレッド名の最大長はプラットフォームにより異なる（Linux/IBM i: 16, macOS: 64, Windows: 32767, NetBSD: 32）
- uv_cond_timedwaitのタイムアウトは相対時間で指定（z/OSでは内部で絶対時間に変換）
- uv_barrier_waitの戻り値 > 0 は任意の1スレッドに返され、バリア破棄の責任を示す

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_thread_t, uv_mutex_t, uv_rwlock_t, uv_sem_t等の定義 |
| 1-2 | uv/unix.h | `include/uv/unix.h` | Unix系でのスレッドプリミティブ型定義（pthread_*へのtypedef） |
| 1-3 | uv/win.h | `include/uv/win.h` | Windows系でのスレッドプリミティブ型定義 |

**読解のコツ**: Unix系ではpthread_*型へのtypedef、Windows系ではHANDLEやCRITICAL_SECTIONへのtypedefになっている。

#### Step 2: スレッド操作の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | thread.c (Unix) | `src/unix/thread.c` | Unix系スレッド操作のpthreads呼び出し |
| 2-2 | thread.c (Win) | `src/win/thread.c` | Windows系スレッド操作の実装 |

#### Step 3: 同期プリミティブの実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | thread.c (Unix) | `src/unix/thread.c` | ミューテックス、セマフォ等のpthreads呼び出し |
| 3-2 | thread.c (Win) | `src/win/thread.c` | Windows同期プリミティブの呼び出し |

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

```
uv_thread_create() [src/unix/thread.c or src/win/thread.c]
    |
    +-- [Unix] pthread_create()
    +-- [Win] CreateThread()

uv_mutex_init() [src/unix/thread.c or src/win/thread.c]
    |
    +-- [Unix] pthread_mutex_init()
    +-- [Win] InitializeCriticalSection()

uv_sem_init() [src/unix/thread.c or src/win/thread.c]
    |
    +-- [Unix] sem_init() / dispatch_semaphore_create()
    +-- [Win] CreateSemaphore()

uv_cond_wait() [src/unix/thread.c or src/win/thread.c]
    |
    +-- [Unix] pthread_cond_wait()
    +-- [Win] SleepConditionVariableCS()

uv_barrier_wait() [src/unix/thread.c or src/win/thread.c]
    |
    +-- [Unix] pthread_barrier_wait() / カスタム実装
    +-- [Win] カスタム実装
```

### データフロー図

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

uv_thread_cb + arg --> uv_thread_create() -------> 新スレッド実行開始
                                                       |
                                                 uv_thread_cb(arg)
                                                       |
                       uv_thread_join() <---------- スレッド終了待ち

共有リソース --------> uv_mutex_lock() ---------> 排他制御
                       uv_mutex_unlock()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| threading.rst | `docs/src/threading.rst` | テンプレート | スレッドページのSphinxソース |
| uv.h | `include/uv.h` | ソース | スレッドプリミティブの公開API定義 |
| thread.c (Unix) | `src/unix/thread.c` | ソース | Unix系スレッド・同期プリミティブ実装 |
| thread.c (Win) | `src/win/thread.c` | ソース | Windows系スレッド・同期プリミティブ実装 |
| api.rst | `docs/src/api.rst` | テンプレート | API一覧ページ（遷移元） |
