# 画面設計書 33-基本事項

## 概要

libuvユーザーガイドの基本事項ページ（guide/basics.rst）に関する画面設計書。イベントループ・ハンドル・リクエストの基本的な使い方をサンプルコード付きで解説するページの構造と仕様を定義する。

### 本画面の処理概要

本ページはlibuvの中核概念であるイベントループ、ハンドル、リクエストの基本を解説する最重要ガイドページである。非同期・イベント駆動プログラミングの原理からHello Worldプログラムまでを段階的に説明する。

**業務上の目的・背景**：libuvプログラミングの基礎を習得するための最初のステップとなるページである。イベントループの動作原理、ブロッキングI/Oの問題点、非同期アプローチの利点を理解させ、実際のコード（helloworld、default-loop、idle-basic）を通じて実践的な理解を促す。ハンドルとリクエストの概念はlibuv全体の基盤であり、以降の全てのガイドで前提知識として必要となる。

**画面へのアクセス方法**：ユーザーガイド一覧（No.31 guide.rst）のtoctreeリンク、またはイントロダクション（No.32）からのPrevious/Nextナビゲーションでアクセスする。URLパスは `/guide/basics.html` となる。

**主要な操作・処理内容**：
1. イベントループの概念説明の表示（擬似コード付き）
2. 非同期ノンブロッキングI/Oの説明表示
3. Hello Worldサンプルコード（helloworld/main.c）の表示と解説
4. デフォルトループの使用方法（default-loop/main.c）の表示と解説
5. エラーハンドリングの説明表示
6. ハンドルとリクエストの型一覧と概念説明の表示
7. Idle handleの使用例（idle-basic/main.c）の表示と解説
8. コンテキストストア（void* data）パターンの説明

**画面遷移**：
- 遷移元：ユーザーガイド一覧（No.31）、イントロダクション（No.32）
- 遷移先：ファイルシステム（No.34）、イベントループAPIリファレンス（No.6）、ユーティリティ（No.39）
- 外部リンク：libuv公式ドキュメント、YouTubeビデオ

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | イベントループ初期化 | 主機能 | uv_loop_init()を使ったイベントループの基本的な使い方の解説 |
| 2 | デフォルトループ取得 | 主機能 | uv_default_loop()の使用方法の解説 |
| 3 | イベントループ実行 | 主機能 | uv_run()によるイベントループ実行の実践的な使い方の解説 |
| 5 | イベントループ終了 | 補助機能 | uv_loop_close()によるリソース解放の説明 |
| 15 | ハンドルクローズ | 補助機能 | uv_close()を使ったハンドルライフサイクル管理の説明 |
| 87 | Idle初期化・開始・停止 | 補助機能 | Idleハンドルのサンプルコードを使った基本動作の解説 |

## 画面種別

チュートリアル（サンプルコード付き解説）

## URL/ルーティング

- ソースファイル：`docs/src/guide/basics.rst`
- 生成先URL：`/guide/basics.html`
- Sphinxルーティング：guide.rstのtoctreeから参照

## 入出力項目

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

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| Event loops説明 | 出力 | テキスト/コードブロック | イベントループ概念の説明（擬似コード含む） |
| Hello Worldコード | 出力 | Cソースコード | helloworld/main.c の全文（行番号付き） |
| Default loopコード | 出力 | Cソースコード | default-loop/main.c の全文（行番号付き） |
| エラーハンドリング説明 | 出力 | テキスト | UV_E*定数とuv_strerror/uv_err_name |
| ハンドル/リクエスト型一覧 | 出力 | Cコード | 全ハンドル型・リクエスト型のtypedef一覧 |
| Idle handleコード | 出力 | Cソースコード | idle-basic/main.c（ハイライト行付き） |
| YouTubeビデオ | 出力 | iframe | Bert Belderのlibuv解説ビデオ |

## 表示項目

| 項目名 | 表示内容 | 備考 |
|--------|----------|------|
| セクションタイトル | "Basics of libuv" | ページ見出し（h1） |
| Event loops (h2) | イベントループの概念説明 | Pythonの擬似コード含む |
| Hello World (h2) | 最初のlibuvプログラム | helloworld/main.c、行番号付き |
| Default loop (h3) | デフォルトループの使用法 | default-loop/main.c、行番号付き |
| Error handling (h2) | エラーハンドリングの概要 | UV_E*定数への外部リンク |
| Handles and Requests (h2) | ハンドルとリクエストの概念 | uv_TYPE_t typedef一覧 |
| Idling (h3) | Idleハンドルの使用例 | idle-basic/main.c、ハイライト行あり |
| Storing context (h3) | void* dataパターン | コンテキスト保持の説明 |
| NOTEボックス | node.jsのデフォルトループ使用に関する注記 | Sphinx noteディレクティブ |
| NOTEボックス | バックグラウンドI/Oに関する注記 | Sphinx NOTEディレクティブ |
| YouTubeビデオ | Bert Belderのlibuv解説 | raw HTMLのiframe |

## イベント仕様

### 1-サンプルコードの表示

literalincludeディレクティブにより、`docs/code/` ディレクトリのCソースファイルが自動的に読み込まれ、シンタックスハイライト・行番号付きで表示される。

### 2-外部リンク遷移

libuv公式ドキュメント、エラー定数ページ、YouTubeビデオなどへの外部リンクをクリックすると対応するページに遷移する。

### 3-内部クロスリファレンス

`:doc:utilities` によりユーティリティページ（No.39）へのクロスリファレンスリンクが生成される。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | 静的HTMLページのため該当なし |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|---------|
| N-33-01 | 注記 | "node.js uses the default loop as its main loop..." | Default loopセクション |
| N-33-02 | 注記 | "How the I/O is run in the background is not of our concern..." | Event loopsセクション |
| N-33-03 | 脚注 | "Depending on the capacity of the hardware of course." | ページ末尾 |

## 例外処理

静的HTMLページのため、アプリケーションレベルの例外処理は発生しない。

## 備考

- 本ページで解説されるhelloworld、default-loop、idle-basicの3つのサンプルコードは `docs/code/` ディレクトリに実在する。
- ハンドル型とリクエスト型のtypedef一覧は、libuv v1.x APIの全型を網羅している。
- `.. _libuv-error-handling:` ラベルにより、他のページからエラーハンドリングセクションへのクロスリファレンスが可能。
- YouTubeビデオはraw HTMLディレクティブで埋め込まれており、Sphinxの標準機能では再現できない。

---

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

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

### 推奨読解順序

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

本ページで解説されるハンドル型・リクエスト型の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | basics.rst | `docs/src/guide/basics.rst` | 行136-187: ハンドル型(uv_handle_t等)・リクエスト型(uv_req_t等)のtypedef一覧を確認 |
| 1-2 | uv.h | `include/uv.h` | libuvのメインヘッダファイルで実際の型定義を確認 |

**読解のコツ**: basics.rstのコードブロック内のtypedefは、include/uv.hに定義されている実際の型を引用したものである。ハンドルは長寿命オブジェクト、リクエストは短寿命（1操作に対応）という区別を意識すること。

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

Hello Worldプログラムから始めて、イベントループの基本パターンを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | helloworld/main.c | `docs/code/helloworld/main.c` | 行5-15: uv_loop_init → uv_run → uv_loop_close → free の基本パターン |
| 2-2 | default-loop/main.c | `docs/code/default-loop/main.c` | 行4-12: uv_default_loop()を使った簡略パターン |

**主要処理フロー**:
1. **helloworld/main.c 行6**: `uv_loop_t *loop = malloc(sizeof(uv_loop_t))` -- ループ構造体のメモリ確保
2. **helloworld/main.c 行7**: `uv_loop_init(loop)` -- ループの初期化
3. **helloworld/main.c 行10**: `uv_run(loop, UV_RUN_DEFAULT)` -- イベントループ実行（即座に終了）
4. **helloworld/main.c 行12**: `uv_loop_close(loop)` -- ループの終了処理
5. **helloworld/main.c 行13**: `free(loop)` -- メモリ解放

#### Step 3: Idle handleの動作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | idle-basic/main.c | `docs/code/idle-basic/main.c` | 行6-11: wait_for_a_while コールバック（カウンタ10^6到達で停止） |
| 3-2 | idle-basic/main.c | `docs/code/idle-basic/main.c` | 行13-24: main関数（idle_init → idle_start → uv_run） |

**主要処理フロー**:
1. **idle-basic/main.c 行14**: `uv_idle_t idler` -- Idleハンドル宣言
2. **idle-basic/main.c 行16**: `uv_idle_init(uv_default_loop(), &idler)` -- Idleハンドル初期化
3. **idle-basic/main.c 行17**: `uv_idle_start(&idler, wait_for_a_while)` -- Idle監視開始
4. **idle-basic/main.c 行20**: `uv_run(uv_default_loop(), UV_RUN_DEFAULT)` -- ループ実行
5. **idle-basic/main.c 行10**: `uv_idle_stop(handle)` -- カウンタ到達でIdle停止 → ループ終了

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

```
helloworld/main.c
    |
    +-- malloc(sizeof(uv_loop_t))
    +-- uv_loop_init(loop)
    +-- uv_run(loop, UV_RUN_DEFAULT)
    +-- uv_loop_close(loop)
    +-- free(loop)

idle-basic/main.c
    |
    +-- uv_default_loop()
    +-- uv_idle_init(loop, &idler)
    +-- uv_idle_start(&idler, wait_for_a_while)
    |       +-- wait_for_a_while() [コールバック]
    |               +-- uv_idle_stop(handle) [counter >= 10e6時]
    +-- uv_run(loop, UV_RUN_DEFAULT)
    +-- uv_loop_close(loop)
```

### データフロー図

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

basics.rst            --> Sphinxビルド               --> basics.html
  literalinclude           Cソース読み込み              コードブロック
  code-block               シンタックスハイライト       ハイライト済みコード
  raw html                 iframe生成                  YouTube動画
helloworld/main.c     --> literalinclude            --> ソースコード表示
default-loop/main.c   --> literalinclude            --> ソースコード表示
idle-basic/main.c     --> literalinclude            --> ソースコード表示（ハイライト付き）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| basics.rst | `docs/src/guide/basics.rst` | テンプレート | 基本事項ページ本体 |
| guide.rst | `docs/src/guide.rst` | テンプレート | 親ページ（toctreeで参照） |
| helloworld/main.c | `docs/code/helloworld/main.c` | ソース | Hello Worldサンプルコード |
| default-loop/main.c | `docs/code/default-loop/main.c` | ソース | デフォルトループサンプルコード |
| idle-basic/main.c | `docs/code/idle-basic/main.c` | ソース | Idle handleサンプルコード |
| uv.h | `include/uv.h` | ソース | libuvメインヘッダ（型定義） |
| conf.py | `docs/src/conf.py` | 設定 | Sphinxビルド設定 |
