# 機能設計書 127-スレッド識別

## 概要

本ドキュメントは、libuvが提供するスレッド識別機能 `uv_thread_self()` / `uv_thread_equal()` の設計仕様を記述する。現在のスレッドIDの取得とスレッドIDの比較を行うためのクロスプラットフォームAPIである。

### 本機能の処理概要

**業務上の目的・背景**：マルチスレッドプログラミングにおいて、現在実行中のスレッドを識別したり、2つのスレッドIDが同一スレッドを指しているかを比較することは、デバッグやスレッドセーフティの実装に不可欠である。プラットフォームごとにスレッドID型や比較方法が異なるため、libuvは統一APIを提供する。

**機能の利用シーン**：特定の処理が特定のスレッド上で実行されていることを確認する場合、スレッドアフィニティの実装、ログ出力時のスレッド識別情報の取得、デバッグ時のスレッド同一性確認に使用される。

**主要な処理内容**：
1. `uv_thread_self()`: 現在のスレッドのスレッドIDを返却する
2. `uv_thread_equal()`: 2つのスレッドIDが同一スレッドを指すかを比較する

**関連システム・外部連携**：POSIX pthread_self()/pthread_equal()、Windows GetCurrentThread()/DuplicateHandle()。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 28 | スレッド | 主機能 | uv_thread_self()/equal()によるスレッドID取得・比較のAPI定義 |

## 機能種別

情報取得・比較処理

## 入力仕様

### 入力パラメータ

#### uv_thread_self()

パラメータなし。

#### uv_thread_equal()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| t1 | const uv_thread_t* | Yes | 比較対象スレッドID 1 | - |
| t2 | const uv_thread_t* | Yes | 比較対象スレッドID 2 | - |

### 入力データソース

ユーザーからの関数呼び出しパラメータ。スレッドIDは `uv_thread_create()` や `uv_thread_self()` から取得したもの。

## 出力仕様

### 出力データ

#### uv_thread_self()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | uv_thread_t | 現在のスレッドのスレッドID |

#### uv_thread_equal()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 非0:同一スレッド、0:異なるスレッド |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
■ uv_thread_self():
1. Unix: pthread_self()を呼び出して返却
2. Windows:
   a. TLSキーを初期化（uv_once()で一度だけ）
   b. TLSからスレッドハンドルを取得
   c. NULLの場合（uv_thread_create以外で作成されたスレッド）:
      └─ DuplicateHandle()で現在スレッドのハンドルを取得
      └─ TLSに保存
   d. ハンドルを返却

■ uv_thread_equal():
1. Unix: pthread_equal(*t1, *t2)を呼び出して返却
2. Windows: *t1 == *t2の直接比較
```

### フローチャート

```mermaid
flowchart TD
    subgraph self_unix [uv_thread_self Unix]
        A1[pthread_self] --> B1[uv_thread_t返却]
    end
    subgraph self_win [uv_thread_self Windows]
        A2[TLSキー初期化 uv_once] --> B2[TLSからハンドル取得]
        B2 --> C2{ハンドル != NULL?}
        C2 -->|Yes| D2[ハンドル返却]
        C2 -->|No| E2[DuplicateHandle]
        E2 --> F2[TLSに保存]
        F2 --> D2
    end
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-127-1 | Unix直接委譲 | Unix版はpthread_self()/pthread_equal()への直接委譲 | Unix |
| BR-127-2 | Windows TLS管理 | Windows版ではTLS（Thread Local Storage）でスレッドハンドルを管理する | Windows |
| BR-127-3 | Windows遅延初期化 | uv_thread_create()以外で作成されたスレッド（メインスレッド等）は、初回呼び出し時にDuplicateHandle()でハンドルを取得する | Windows |

### 計算ロジック

なし。

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

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | - | uv_thread_self()はエラーを返さない（Unix）。Windows版はDuplicateHandle失敗時にuv_fatal_error() | - |
| なし | - | uv_thread_equal()はエラーを返さない | - |

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

両関数とも即座に完了する。uv_thread_self()のWindows版は初回呼び出し時のみDuplicateHandle()のオーバーヘッドがある。

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

特になし。

## 備考

- Windows版のuv_thread_self()はスレッドハンドルを返すが、これはuv_thread_create()で作成されたハンドルと等価ではないことがある（DuplicateHandle()で取得されたもの）
- pthread_equal()は構造体型のpthread_tの比較を安全に行うが、Windows版では単純なポインタ比較で済む

---

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

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

### 推奨読解順序

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | thread.c | `src/unix/thread.c` | **290-292行目**: `uv_thread_self()`。pthread_self()を直接返却する1行関数 |
| 2-2 | thread.c | `src/unix/thread.c` | **299-301行目**: `uv_thread_equal()`。pthread_equal()を直接返却する1行関数 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | thread.c | `src/win/thread.c` | **58-68行目**: TLSキーの初期化とuv__current_thread_keyの管理 |
| 3-2 | thread.c | `src/win/thread.c` | **249-264行目**: Windows版`uv_thread_self()`。TLSからハンドル取得、なければDuplicateHandle()で遅延初期化 |
| 3-3 | thread.c | `src/win/thread.c` | **279-281行目**: Windows版`uv_thread_equal()`。ポインタの直接比較 |

**主要処理フロー（Windows版uv_thread_self）**:
- **251行目**: uv_once()でTLSキーの初回初期化
- **252行目**: TLSからスレッドハンドルを取得
- **253-261行目**: NULLの場合、DuplicateHandle()で現在スレッドのハンドルを取得しTLSに保存

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

```
uv_thread_self() [src/unix/thread.c:290]
    └── pthread_self() [libpthread]

uv_thread_self() [src/win/thread.c:249]
    +── uv_once() → uv__init_current_thread_key()
    +── uv_key_get(&uv__current_thread_key)
    +── DuplicateHandle() [Win32] ※初回のみ
    └── uv_key_set(&uv__current_thread_key)

uv_thread_equal() [src/unix/thread.c:299]
    └── pthread_equal(*t1, *t2) [libpthread]

uv_thread_equal() [src/win/thread.c:279]
    └── *t1 == *t2 直接比較
```

### データフロー図

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

(なし) ────────▶ uv_thread_self() ──▶ uv_thread_t（スレッドID）

t1, t2 ────────▶ uv_thread_equal() ──▶ int（0 or 非0）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | API宣言 |
| thread.c | `src/unix/thread.c` | ソース | Unix実装 |
| thread.c | `src/win/thread.c` | ソース | Windows実装 |
