# 画面設計書 42-0.10→1.0.0マイグレーション

## 概要

libuv 0.10から1.0.0へのバージョンアップ時に必要なAPIマイグレーション手順を解説するドキュメントページに関する画面設計書。主要なAPI変更点と対応するコード修正方法をBefore/After形式で提示する。

### 本画面の処理概要

本画面は、libuvの0.10系から1.0.0への移行に伴う破壊的API変更を包括的に解説するマイグレーションガイドページである。9つのセクションに分かれた変更点について、旧API（0.10）と新API（1.0）のコード例を対比形式で示し、開発者が既存コードを効率的に移行できるようにする。

**業務上の目的・背景**：libuv 1.0.0は0.10から多数の破壊的変更が行われたメジャーバージョンアップである。ループの初期化・終了方法の変更、エラーハンドリングの完全な刷新、IPv4/IPv6 APIの統合、コールバックシグネチャの変更など、既存コードのほぼ全域に影響する変更が含まれている。本ページは、これらの変更点を体系的にドキュメント化し、Node.jsやその他のlibuvを利用するプロジェクトが安全にバージョンアップできるよう支援することを目的としている。特にuv_last_errorの廃止に伴うエラーハンドリングパターンの変更は、0.10系のコードベース全体に影響するため、開発者への周知が重要である。

**画面へのアクセス方法**：アップグレードガイド一覧ページ（upgrading.rst / No.41）のtoctreeリンクからアクセスする。また、APIリファレンスの各ページからSphinxのクロスリファレンス（`:ref:\`migration_010_100\``）を通じてリンクされる場合もある。

**主要な操作・処理内容**：
1. 「Loop initialization and closing」セクション：uv_loop_new/uv_loop_delete廃止とuv_loop_init/uv_loop_close導入の解説
2. 「Error handling」セクション：uv_last_error廃止と負のエラーコード直接返却方式への変更の解説
3. 「Threadpool changes」セクション：Windows/Unix統一スレッドプール実装とUV_THREADPOOL_SIZE環境変数の解説
4. 「Allocation callback API change」セクション：バッファ割り当てコールバックのシグネチャ変更の解説
5. 「Unification of IPv4 / IPv6 APIs」セクション：IPv4/IPv6分離APIからsockaddr*統一APIへの変更の解説
6. 「Streams / UDP data receive callback API change」セクション：受信コールバックのuv_buf_tポインタ化の解説
7. 「Receiving handles over pipes API change」セクション：uv_read2_start廃止とuv_pipe_pending_count/type導入の解説
8. 「Extracting the file descriptor out of a handle」セクション：uv_fileno関数導入の解説
9. 「uv_fs_readdir rename and API change」セクション：uv_fs_scandir/uv_fs_scandir_nextへの改名と逐次取得APIの解説

**画面遷移**：
- 遷移元：アップグレードガイド一覧（upgrading.rst / No.41）のtoctreeリンク
- 遷移先（クロスリファレンスによる参照先）：
  - イベントループ（loop.rst / No.6）: uv_loop_init、uv_loop_close
  - スレッドプール（threadpool.rst / No.25）: スレッドプール設定
  - パイプ（pipe.rst / No.19）: uv_pipe_pending_count、uv_pipe_pending_type
  - ハンドル基底（handle.rst / No.7）: uv_fileno
  - ファイルシステム操作（fs.rst / No.24）: uv_fs_scandir、uv_fs_scandir_next
  - TCP（tcp.rst / No.18）: uv_tcp_bind
  - その他ユーティリティ（misc.rst / No.29）: uv_ip4_addr、uv_ip6_addr

**権限による表示制御**：なし。本ドキュメントサイトは公開ページであり、全ユーザーが同一の内容を閲覧可能である。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | イベントループ初期化 | 補助機能 | uv_loop_init()へのAPI変更（0.10→1.0.0）の説明 |
| 3 | イベントループ実行 | 補助機能 | uv_run()のセマンティクス変更の説明 |
| 15 | ハンドルクローズ | 補助機能 | uv_close()の使用方法変更の説明 |

## 画面種別

詳細（マイグレーションガイド）

## URL/ルーティング

- Sphinxソースファイル: `docs/src/migration_010_100.rst`
- 生成後URL: `/migration_010_100.html`
- ReadTheDocs URL例: `https://docs.libuv.org/en/v1.x/migration_010_100.html`

## 入出力項目

本画面はSphinxで静的生成されるドキュメントページであり、動的な入力項目は存在しない。

| 項目名 | 入出力区分 | データ型 | 説明 |
|--------|-----------|---------|------|
| ページタイトル | 出力 | テキスト | 「libuv 0.10 -> 1.0.0 migration guide」固定 |
| 概要説明 | 出力 | テキスト | API変更の概要説明文 |
| セクション見出し×9 | 出力 | テキスト | 各変更点のカテゴリ見出し |
| コード例（0.10版）×9 | 出力 | コードブロック | 旧APIのサンプルコード |
| コード例（1.0版）×9 | 出力 | コードブロック | 新APIのサンプルコード |
| 注記（note）×2 | 出力 | テキスト | 補足情報 |
| クロスリファレンスリンク | 出力 | リンク | APIリファレンスページへの参照リンク |

## 表示項目

| 表示項目 | 内容 | 表示形式 |
|---------|------|---------|
| ページタイトル | libuv 0.10 -> 1.0.0 migration guide | h1見出し |
| 概要説明 | Some APIs changed quite a bit throughout the 1.0.0 development process... | 段落テキスト |
| Loop initialization and closing | uv_loop_new→uv_loop_init移行 | h2見出し + コードブロック×2 + 注記 |
| Error handling | エラーハンドリングの刷新 | h2見出し + コードブロック×2 |
| Threadpool changes | スレッドプール実装統一 | h2見出し + 説明テキスト |
| Allocation callback API change | alloc_cbシグネチャ変更 | h2見出し + コードブロック×2 |
| Unification of IPv4 / IPv6 APIs | IPv4/IPv6 API統合 | h2見出し + コードブロック×2 + 注記 |
| Streams / UDP data receive callback API change | 受信コールバック変更 | h2見出し + コードブロック×4 |
| Receiving handles over pipes API change | パイプハンドル受信API変更 | h2見出し + コードブロック×2 |
| Extracting the file descriptor out of a handle | uv_fileno導入 | h2見出し + コードブロック×1 |
| uv_fs_readdir rename and API change | uv_fs_scandir改名 | h2見出し + 説明テキスト |

## イベント仕様

### 1-クロスリファレンスリンクのクリック

ドキュメント内に埋め込まれたSphinxクロスリファレンス（`:c:func:\`uv_loop_init\``等）をクリックすると、対応するAPIリファレンスページへ遷移する。以下のクロスリファレンスが含まれている。

| リンクテキスト | 遷移先 |
|--------------|--------|
| `uv_loop_init` | イベントループ（loop.rst / No.6） |
| `uv_loop_close` | イベントループ（loop.rst / No.6） |
| threadpool | スレッドプール（threadpool.rst / No.25） |
| `uv_tcp_bind` | TCP（tcp.rst / No.18） |
| `uv_ip4_addr` | その他ユーティリティ（misc.rst / No.29） |
| `uv_ip6_addr` | その他ユーティリティ（misc.rst / No.29） |
| `uv_buf_t` | その他ユーティリティ（misc.rst / No.29） |
| `uv_pipe_pending_count` | パイプ（pipe.rst / No.19） |
| `uv_pipe_pending_type` | パイプ（pipe.rst / No.19） |
| `uv_fileno` | ハンドル基底（handle.rst / No.7） |
| `uv_fs_scandir` | ファイルシステム操作（fs.rst / No.24） |
| `uv_fs_scandir_next` | ファイルシステム操作（fs.rst / No.24） |

### 2-パンくずリスト・サイドバーナビゲーション

ReadTheDocsテーマにより自動生成されるパンくずリスト「トップページ > Upgrading > libuv 0.10 -> 1.0.0 migration guide」やサイドバーから、親ページ（upgrading.rst / No.41）やトップページ（index.rst / No.1）への遷移が可能。

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

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

該当なし。本画面はSphinxにより静的HTMLとして生成されるドキュメントページであり、データベースアクセスは発生しない。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | データベース操作なし |

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

該当なし。

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|--------------|
| 注記（note） | Loop initialization and closingセクション | Error handling was omitted for brevity. Check the documentation for uv_loop_init and uv_loop_close. |
| 注記（note） | Unification of IPv4 / IPv6 APIsセクション | This change applies to all functions that made a distinction between IPv4 and IPv6 addresses. |

## 例外処理

| 例外条件 | 表示・動作 |
|---------|-----------|
| ページが見つからない場合 | Webサーバーの404エラーページを表示 |
| クロスリファレンスのリンク切れ | Sphinxビルド時に警告を出力。HTMLではプレーンテキストとして表示される |
| Sphinx生成エラー | ビルド時にSphinxがエラーメッセージを出力（ユーザーには表示されない） |

## 備考

- 本ページは9つのAPIカテゴリ別変更セクションで構成されており、各セクションは「libuv 0.10」「libuv 1.0」の対比コード例を含む
- マイグレーションガイドで参照されている旧API（uv_loop_new、uv_loop_delete、uv_last_error、uv_read2_start等）は1.0では非推奨または削除されている
- 1.0のuv.hには後方互換のためuv_loop_new/uv_loop_deleteの宣言が残されているが、deprecated扱い（include/uv.h 296-304行目）
- rstファイル先頭の`.. _migration_010_100:`はSphinxのクロスリファレンス用ラベルであり、他のドキュメントから`:ref:\`migration_010_100\``で参照可能
- 139行目の`..note::`はSphinxの書式としては`.. note::`（スペース必要）が正しく、ビルド時に注記として正しくレンダリングされない可能性がある（原文rstの不具合の可能性）

---

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

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

### 推奨読解順序

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

本画面で解説されているAPI変更の対象となるデータ構造をまず確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_loop_t構造体の定義、uv_buf_t構造体の定義（alloc_cbの変更に関係）、エラーコード定義（UV_EADDRINUSE等）を確認する |
| 1-2 | uv.h | `include/uv.h` | 291-304行目: uv_loop_init/uv_loop_close（新API）とuv_loop_new/uv_loop_delete（旧API・deprecated）の宣言を確認する |

**読解のコツ**: uv.hは非常に大きなファイルだが、マイグレーションガイドで言及されている関数宣言の行番号を起点に読むとよい。旧APIは「deprecated」コメント付きで残されている。

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

本画面のソースファイルであるmigration_010_100.rstの全体構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | migration_010_100.rst | `docs/src/migration_010_100.rst` | 全245行、9つのセクション構成を確認する。各セクションは「0.10のコード例」→「1.0のコード例」の対比構造を持つ |

**主要処理フロー**:
1. **行1-2**: クロスリファレンスラベル `.. _migration_010_100:` の定義
2. **行4-9**: タイトルと概要説明
3. **行12-40**: Loop initialization and closing（uv_loop_new→uv_loop_init移行）
4. **行43-72**: Error handling（uv_last_error→直接エラーコード返却）
5. **行75-84**: Threadpool changes（プラットフォーム間統一）
6. **行87-106**: Allocation callback API change（戻り値→ポインタ引数）
7. **行109-141**: Unification of IPv4 / IPv6 APIs（sockaddr*統一）
8. **行144-184**: Streams / UDP data receive callback API change
9. **行187-218**: Receiving handles over pipes API change
10. **行221-231**: Extracting the file descriptor out of a handle
11. **行234-244**: uv_fs_readdir rename and API change

#### Step 3: 新API実装を確認する

マイグレーションガイドで導入された新APIの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | uv.h | `include/uv.h` | 291行目: `uv_loop_init`、292行目: `uv_loop_close`の宣言 |
| 3-2 | uv.h | `include/uv.h` | 425-429行目: `uv_strerror`、`uv_err_name`（新エラーハンドリングAPI）の宣言 |
| 3-3 | uv.h | `include/uv.h` | 509行目: `uv_fileno`の宣言 |
| 3-4 | uv.h | `include/uv.h` | 628行目: `uv_tcp_bind`（統合版）の宣言 |
| 3-5 | uv.h | `include/uv.h` | 899-900行目: `uv_pipe_pending_count`、`uv_pipe_pending_type`の宣言 |
| 3-6 | uv.h | `include/uv.h` | 1539-1544行目: `uv_fs_scandir`、`uv_fs_scandir_next`の宣言 |
| 3-7 | uv.h | `include/uv.h` | 1780-1781行目: `uv_ip4_addr`、`uv_ip6_addr`（新シグネチャ）の宣言 |
| 3-8 | threadpool.c | `src/threadpool.c` | 207行目: UV_THREADPOOL_SIZE環境変数の読み取り処理 |

#### Step 4: 親ページの構成を確認する

本画面の親ページであるupgrading.rstからの参照関係を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | upgrading.rst | `docs/src/upgrading.rst` | 11行目: toctreeにmigration_010_100が登録されていることを確認する |

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

```
index.rst (トップページ)
    |
    +-- upgrading.rst (アップグレードガイド一覧)
           |
           +-- migration_010_100.rst (本画面: 0.10→1.0.0マイグレーション)
                  |
                  +-- :c:func:`uv_loop_init` → loop.rst
                  +-- :c:func:`uv_loop_close` → loop.rst
                  +-- :c:ref:`threadpool` → threadpool.rst
                  +-- :c:func:`uv_tcp_bind` → tcp.rst
                  +-- :c:func:`uv_ip4_addr` → misc.rst
                  +-- :c:func:`uv_ip6_addr` → misc.rst
                  +-- :c:type:`uv_buf_t` → misc.rst
                  +-- :c:func:`uv_pipe_pending_count` → pipe.rst
                  +-- :c:func:`uv_pipe_pending_type` → pipe.rst
                  +-- :c:func:`uv_fileno` → handle.rst
                  +-- :c:func:`uv_fs_scandir` → fs.rst
                  +-- :c:func:`uv_fs_scandir_next` → fs.rst
```

### データフロー図

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

migration_010_100.rst ─────> Sphinxビルドエンジン ─────────> migration_010_100.html
                                 |
                                 +-- クロスリファレンス解決
                                 |     |
                                 |     +-- loop.rst → uv_loop_init/close リンク生成
                                 |     +-- tcp.rst → uv_tcp_bind リンク生成
                                 |     +-- pipe.rst → uv_pipe_pending_* リンク生成
                                 |     +-- handle.rst → uv_fileno リンク生成
                                 |     +-- fs.rst → uv_fs_scandir* リンク生成
                                 |     +-- misc.rst → uv_ip4/6_addr リンク生成
                                 |
                                 +-- コードブロックのシンタックスハイライト
                                 |
upgrading.rst ─────────────────+─────> パンくずリスト・ナビゲーション生成
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| migration_010_100.rst | `docs/src/migration_010_100.rst` | テンプレート（rst） | 本画面のソースファイル。9セクションのマイグレーションガイド |
| upgrading.rst | `docs/src/upgrading.rst` | テンプレート（rst） | 親ページ: アップグレードガイド一覧 |
| index.rst | `docs/src/index.rst` | テンプレート（rst） | トップページ: 最上位のナビゲーション |
| uv.h | `include/uv.h` | ソース（ヘッダ） | マイグレーションガイドで言及される全APIの宣言。新旧APIの共存を確認可能 |
| threadpool.c | `src/threadpool.c` | ソース（C） | UV_THREADPOOL_SIZE環境変数の読み取り実装（207行目） |
| loop.rst | `docs/src/loop.rst` | テンプレート（rst） | クロスリファレンス先: uv_loop_init/uv_loop_close APIリファレンス |
| handle.rst | `docs/src/handle.rst` | テンプレート（rst） | クロスリファレンス先: uv_fileno APIリファレンス |
| tcp.rst | `docs/src/tcp.rst` | テンプレート（rst） | クロスリファレンス先: uv_tcp_bind APIリファレンス |
| pipe.rst | `docs/src/pipe.rst` | テンプレート（rst） | クロスリファレンス先: uv_pipe_pending_count/type APIリファレンス |
| fs.rst | `docs/src/fs.rst` | テンプレート（rst） | クロスリファレンス先: uv_fs_scandir/uv_fs_scandir_next APIリファレンス |
| misc.rst | `docs/src/misc.rst` | テンプレート（rst） | クロスリファレンス先: uv_ip4_addr/uv_ip6_addr APIリファレンス |
| conf.py | `docs/src/conf.py` | 設定 | Sphinxビルド設定ファイル |
