# 画面設計書 15-シグナル

## 概要

本ドキュメントは、libuvドキュメントサイトにおける `uv_signal_t`（シグナルハンドル）APIリファレンスページの画面設計書である。Sphinxにより生成されるHTMLページとして、シグナルハンドルの型定義・API関数仕様・プラットフォーム固有の注意事項を表示する。

### 本画面の処理概要

シグナルハンドルは、UNIXスタイルのシグナル処理をイベントループベースで実装する。本ページでは、シグナルハンドルの初期化・監視開始（通常およびワンショット）・停止に関するAPIと、WindowsおよびUnixにおけるシグナル対応状況を詳細に解説する。

**業務上の目的・背景**：UNIXシグナルはプロセス間通信や異常終了処理の基本的なメカニズムであり、非同期I/Oフレームワークで適切に処理する必要がある。libuvのシグナルハンドルは、シグナルの受信をイベントループのコールバックとして安全に処理する手段を提供する。Ctrl+Cによるプログラム停止（SIGINT）、グレースフルシャットダウン（SIGTERM）、設定ファイルの再読み込み（SIGHUP）等の一般的なシグナル処理パターンを実装するための基盤となる。WindowsでのSIGINT/SIGBREAK/SIGHUP/SIGWINCHのエミュレーション対応についても詳細に文書化されている。

**画面へのアクセス方法**：トップページ → APIドキュメント一覧（api.rst） → シグナル（signal.rst）の順にナビゲーションリンクを辿ってアクセスする。

**主要な操作・処理内容**：
1. `uv_signal_t` 型と `uv_signal_cb` コールバック型の定義を閲覧する
2. Windows固有のシグナルエミュレーション動作の詳細を確認する
3. Unix固有のシグナル制限事項を確認する
4. `uv_signal_init()` / `uv_signal_start()` / `uv_signal_start_oneshot()` / `uv_signal_stop()` の各API仕様を確認する
5. パブリックメンバー `signum` の仕様を確認する
6. 基底ハンドル（`uv_handle_t`）の共通API関数へのリンクを辿る

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：ハンドル基底ページ（handle.rst）への参照リンク、TTYページ（tty.rst）への参照リンク
- 関連ページ：プロセスページ（process.rst）

**権限による表示制御**：なし（公開ドキュメントサイトのため、全ユーザーが同一内容を閲覧可能）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 93 | シグナルハンドル初期化 | 主機能 | uv_signal_init()によるシグナルハンドル初期化のAPI定義 |
| 94 | シグナル監視開始 | 主機能 | uv_signal_start()/uv_signal_start_oneshot()によるシグナル監視開始のAPI定義 |
| 95 | シグナル監視停止 | 主機能 | uv_signal_stop()によるシグナル監視停止のAPI定義 |

## 画面種別

APIリファレンス詳細ページ

## URL/ルーティング

`docs/src/signal.rst` → ビルド後: `/signal.html`

## 入出力項目

本ページはドキュメント表示ページのため、ユーザー入力項目はない。

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| ページコンテンツ | 出力 | HTML | rstファイルからSphinxによって生成されたHTML |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | `uv_signal_t` --- Signal handle | ページタイトル |
| 概要説明 | Signal handles implement Unix style signal handling... | シグナルハンドルの概要 |
| Windows notes | SIGINT, SIGBREAK, SIGHUP, SIGWINCHのエミュレーション詳細 | Windows固有の動作 |
| Unix notes | SIGKILL/SIGSTOP不可、SIGBUS等は未定義動作 | Unix固有の制限 |
| Data types | `uv_signal_t`, `uv_signal_cb` | 型定義 |
| Public members | `uv_signal_t.signum` (readonly) | 監視中のシグナル番号 |
| API - uv_signal_init | 初期化関数 | ハンドルの初期化 |
| API - uv_signal_start | 監視開始関数 | コールバック・シグナル番号指定 |
| API - uv_signal_start_oneshot | ワンショット監視開始 | v1.12.0追加、一度の受信でリセット |
| API - uv_signal_stop | 監視停止関数 | コールバック停止 |
| See also | uv_handle_t API functions | 基底ハンドルAPIへの参照 |

## イベント仕様

### 1-ページ内リンク遷移

`:c:type:`uv_handle_t`` へのリンクでハンドル基底ページに遷移。`:c:type:`uv_tty_t`` へのリンクでTTYページに遷移（SIGWINCHの説明内）。

### 2-シグナルコールバック実行（ランタイム動作）

`uv_signal_start()` で登録したシグナルが受信されると、コールバックがシグナル番号と共に呼び出される。`uv_signal_start_oneshot()` の場合は一度の受信後にハンドラがリセットされる。

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

本ページは静的ドキュメント表示のため、データベース操作は存在しない。

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | N/A | N/A | 静的HTMLドキュメントのためDB操作なし |

### テーブル別更新項目詳細

該当なし

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|--------------|
| 該当なし | - | API関数のエラー戻り値はドキュメント本文内で説明 |

## 例外処理

- ページが見つからない場合：Webサーバーの404エラーが表示される

## 備考

- `uv_signal_start_oneshot()` はv1.12.0で追加された
- SIGWINCHのWindows対応はv1.15.0で改善、v1.31.0で32-bit対応がロールバック
- WindowsではSIGILL/SIGABRT/SIGFPE/SIGSEGV/SIGTERM/SIGKILLのウォッチャーは作成可能だが受信されない
- Linuxでは SIGRT0/SIGRT1（32番、33番）はpthreadsが使用するため監視は推奨されない
- `uv_handle_t` の共通メンバーおよびAPI関数がそのまま適用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | `uv_signal_t` 構造体定義・`uv_signal_cb` コールバック型の宣言箇所 |
| 1-2 | signal.rst | `docs/src/signal.rst` | 1-102行目: ドキュメント全体・Windows/Unix notes・API仕様 |

**読解のコツ**: シグナルハンドルはグローバルなRBツリー（`uv__signal_tree`）で管理され、同一シグナルに対する複数ループのハンドラを管理する。Unix実装では、シグナルハンドラからパイプ経由でイベントループにメッセージを送信する2段構成になっている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | signal.c | `src/unix/signal.c` | 341-354行目: `uv_signal_init` - ループのシグナルインフラ初期化、ハンドル初期化 |
| 2-2 | signal.c | `src/unix/signal.c` | 362-364行目: `uv_signal_start` - `uv__signal_start` への委譲 |
| 2-3 | signal.c | `src/unix/signal.c` | 367-371行目: `uv_signal_start_oneshot` - oneshot=1で `uv__signal_start` 呼び出し |

**主要処理フロー**:
1. **341行目**: `uv_signal_init` - `uv__signal_loop_once_init` でループのシグナルパイプを初期化
2. **348行目**: `uv__handle_init` でハンドル初期化、`signum=0` に設定
3. **374行目**: `uv__signal_start` - シグナルマスクのブロック・ロック取得
4. **412行目**: RBツリーに最初のハンドラの場合、`uv__signal_register_handler` でシグナルハンドラ登録
5. **427行目**: RBツリーにハンドルを挿入

#### Step 3: シグナル受信からコールバック実行までを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | signal.c | `src/unix/signal.c` | 438-500行目: `uv__signal_event` - パイプからのシグナルメッセージ読み出しとコールバック実行 |
| 3-2 | signal.c | `src/unix/signal.c` | 533-537行目: `uv_signal_stop` - RBツリーからの削除とシグナルハンドラ解除 |

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

```
uv_signal_init(loop, handle) [src/unix/signal.c:341]
    |
    +-- uv__signal_loop_once_init(loop) [パイプ初期化]
    +-- uv__handle_init() [ハンドル初期化]

uv_signal_start(handle, cb, signum) [src/unix/signal.c:362]
    |
    +-- uv__signal_start(handle, cb, signum, 0) [src/unix/signal.c:374]
           |
           +-- uv__signal_block_and_lock() [シグナルブロック・ロック]
           +-- uv__signal_register_handler() [sigaction設定]
           +-- RB_INSERT() [RBツリー挿入]
           +-- uv__signal_unlock_and_unblock() [アンロック・アンブロック]
           +-- uv__handle_start() [ハンドル開始]

[シグナル受信時]
sigaction handler → write(signal_pipefd) → I/Oポーリング検出
    |
    +-- uv__signal_event() [src/unix/signal.c:438]
           |
           +-- read(signal_pipefd) [メッセージ読み出し]
           +-- handle->signal_cb(handle, signum) [コールバック実行]
```

### データフロー図

```
[シグナル発生]              [シグナルハンドラ]            [イベントループ]

OS signal (SIGINT等)  --->  sigaction handler       ---> write(pipe)
                            uv__signal_msg_t生成          |
                                                    I/Oポーリング検出
                                                          |
                                                    uv__signal_event()
                                                          |
                                                    signal_cb(handle, signum)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| signal.rst | `docs/src/signal.rst` | テンプレート | シグナルハンドルドキュメントのソース |
| uv.h | `include/uv.h` | ソース | uv_signal_t構造体・API関数宣言 |
| signal.c | `src/unix/signal.c` | ソース | Unix用signal init/start/stop/event/close実装 |
| signal.c | `src/win/signal.c` | ソース | Windows用signal実装 |
| process.c | `src/unix/process.c` | ソース | SIGCHLD監視でuv_signal_startを使用（1019行目） |
