# 機能設計書 126-スレッド結合・分離

## 概要

本ドキュメントは、libuvが提供するスレッド結合・分離機能 `uv_thread_join()` / `uv_thread_detach()` の設計仕様を記述する。作成済みスレッドの終了待機（join）またはリソースの自動解放設定（detach）を行うためのクロスプラットフォームAPIである。

### 本機能の処理概要

**業務上の目的・背景**：スレッドのライフサイクル管理において、スレッドの終了を待機して結果を受け取る（join）か、スレッドを独立して実行させてリソースを自動解放する（detach）かを選択する必要がある。libuvはこれらの操作に対してクロスプラットフォームな統一APIを提供する。

**機能の利用シーン**：ワーカースレッドの完了を待機してから次の処理に進む場合にjoinを使用する。バックグラウンドスレッドを独立して実行させ、その完了を気にしない場合にdetachを使用する。

**主要な処理内容**：
1. `uv_thread_join()`: 指定スレッドの終了を待機し、スレッドリソースを解放する
2. `uv_thread_detach()`: 指定スレッドをデタッチし、終了時にリソースが自動解放されるようにする

**関連システム・外部連携**：POSIX pthread_join()/pthread_detach()、Windows WaitForSingleObject()/CloseHandle()。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 28 | スレッド | 主機能 | uv_thread_join()/detach()によるスレッド結合・分離のAPI定義 |
| 36 | スレッド | 主機能 | uv_thread_join()を使ったスレッド結合の使用例 |

## 機能種別

リソース管理（OSスレッドライフサイクル管理）

## 入力仕様

### 入力パラメータ

#### uv_thread_join()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| tid | uv_thread_t* | Yes | 結合対象のスレッドID | - |

#### uv_thread_detach()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| tid | uv_thread_t* | Yes | 分離対象のスレッドID | - |

### 入力データソース

`uv_thread_create()` で取得したスレッドID。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 0:成功、負値:エラーコード |

### 出力先

関数の戻り値として返却。

## 処理フロー

### 処理シーケンス

```
■ uv_thread_join():
1. Unix: pthread_join(*tid, NULL)を呼び出し
   └─ スレッドの終了を待機
   └─ スレッドリソースを解放
   └─ エラー時はUV__ERR()で変換して返却
2. Windows: WaitForSingleObject(*tid, INFINITE)を呼び出し
   └─ 成功時: CloseHandle(*tid)でハンドル解放
   └─ *tid = 0に設定
   └─ MemoryBarrier()でメモリの可視性を保証

■ uv_thread_detach():
1. Unix: pthread_detach(*tid)を呼び出し
   └─ エラー時はUV__ERR()で変換して返却
2. Windows: CloseHandle(*tid)を呼び出し
   └─ エラー時はuv_translate_sys_error()で変換
```

### フローチャート

```mermaid
flowchart TD
    subgraph join [uv_thread_join]
        A1[開始] --> B1{プラットフォーム}
        B1 -->|Unix| C1[pthread_join tid NULL]
        B1 -->|Windows| D1[WaitForSingleObject INFINITE]
        D1 -->|成功| E1[CloseHandle + MemoryBarrier]
        D1 -->|失敗| F1[エラー返却]
        C1 --> G1[結果返却]
        E1 --> G1
    end
    subgraph detach [uv_thread_detach]
        A2[開始] --> B2{プラットフォーム}
        B2 -->|Unix| C2[pthread_detach tid]
        B2 -->|Windows| D2[CloseHandle tid]
        C2 --> G2[結果返却]
        D2 --> G2
    end
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-126-1 | joinの排他性 | 同一スレッドに対してjoinを複数回呼び出してはならない（未定義動作） | 常時 |
| BR-126-2 | join/detach排他 | join済みまたはdetach済みのスレッドに対して再度操作してはならない | 常時 |
| BR-126-3 | Windowsメモリバリア | Windows版joinではMemoryBarrier()を呼んでpthread_join()との機能的同等性を確保 | Windows |
| BR-126-4 | Windowsハンドルクリア | Windows版joinでは*tidを0に設定してハンドルの再利用を防止 | Windows |

### 計算ロジック

なし。

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

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_ESRCH | スレッド不在 | 指定スレッドが存在しない | スレッドIDを確認 |
| UV_EINVAL | パラメータエラー | スレッドがjoin不可（既にdetach済み等） | 操作順序を確認 |
| UV_EDEADLK | デッドロック | 自スレッドをjoinしようとした | 別スレッドからjoinする |

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

`uv_thread_join()` はスレッドの終了まで呼び出し元をブロックする。イベントループ上からの呼び出しは避けるべきである。

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

- joinしないスレッドはdetachしないとリソースリークが発生する
- スレッド終了前にdetachすると、スレッドの状態を把握できなくなる

## 備考

- libuvのスレッドプール終了時（uv__threadpool_cleanup）では、全ワーカースレッドに対してuv_thread_join()が呼ばれる

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **1923行目**: `uv_thread_join()`の関数シグネチャ |
| 1-2 | uv.h | `include/uv.h` | **1895行目**: `uv_thread_detach()`の関数シグネチャ |

#### Step 2: Unix実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | thread.c | `src/unix/thread.c` | **294-296行目**: `uv_thread_join()`。pthread_join()を呼び出しUV__ERR()で変換 |
| 2-2 | thread.c | `src/unix/thread.c` | **133-135行目**: `uv_thread_detach()`。pthread_detach()を呼び出しUV__ERR()で変換 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | thread.c | `src/win/thread.c` | **267-276行目**: Windows版`uv_thread_join()`。WaitForSingleObject()→CloseHandle()→MemoryBarrier() |
| 3-2 | thread.c | `src/win/thread.c` | **102-107行目**: Windows版`uv_thread_detach()`。CloseHandle()呼び出し |

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

```
uv_thread_join() [src/unix/thread.c:294]
    └── pthread_join(*tid, NULL) [libpthread]

uv_thread_join() [src/win/thread.c:267]
    +── WaitForSingleObject(*tid, INFINITE) [Win32]
    +── CloseHandle(*tid) [Win32]
    └── MemoryBarrier() [Win32]

uv_thread_detach() [src/unix/thread.c:133]
    └── pthread_detach(*tid) [libpthread]

uv_thread_detach() [src/win/thread.c:102]
    └── CloseHandle(*tid) [Win32]
```

### データフロー図

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

uv_thread_t* tid ──▶ uv_thread_join()
                          │
                     [スレッド終了待機]
                          │
                     [リソース解放] ──▶ int (0 or error)

uv_thread_t* tid ──▶ uv_thread_detach()
                          │
                     [デタッチ設定] ──▶ int (0 or error)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | API宣言 |
| thread.c | `src/unix/thread.c` | ソース | Unix実装 |
| thread.c | `src/win/thread.c` | ソース | Windows実装 |
| threadpool.c | `src/threadpool.c` | ソース | join()の内部利用箇所（スレッドプール終了時） |
