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

## はじめに

このガイドラインは、libuvのコードベースを効率的に理解するための手引きです。
C言語に精通していないエンジニアでも、段階的に学習できるよう構成されています。

**対象読者:**
- プロジェクトに新規参画するエンジニア
- 他言語からの経験者
- コードレビューを行う担当者

**プロジェクト概要:**
libuv は非同期I/O対応のマルチプラットフォームライブラリです。Node.js、Luvit、Julia、uvloop等で使用されており、イベント駆動型の非同期プログラミングモデルを提供します。

---

## 1. 言語基礎

> このセクションでは、C言語の基本構文と libuv で多用される概念を解説します。

### 1.1 プログラム構造

libuv は C11 (GNU11拡張) で記述されています。ソースファイルは `.c`（実装）と `.h`（ヘッダ）で構成され、各ファイルはライセンスヘッダで始まり、`#include` ディレクティブでヘッダを取り込みます。

```c
// ファイル: src/unix/core.c:21-23
#include "uv.h"
#include "internal.h"
#include "strtok.h"
```

公開APIのヘッダは `include/uv.h` に集約されており、C++からも利用可能なよう `extern "C"` ガードが施されています。

```c
// ファイル: include/uv.h:24-28
#ifndef UV_H
#define UV_H
#ifdef __cplusplus
extern "C" {
#endif
```

### 1.2 データ型と変数

libuv では構造体の `typedef` を多用し、`uv_*_t` 形式で型名を統一しています。

```c
// ファイル: include/uv.h での typedef 例
typedef struct uv_loop_s uv_loop_t;      // イベントループ
typedef struct uv_handle_s uv_handle_t;  // ハンドル基底型
typedef struct uv_stream_s uv_stream_t;  // ストリーム基底型
typedef struct uv_tcp_s uv_tcp_t;        // TCPハンドル
typedef struct uv_timer_s uv_timer_t;    // タイマーハンドル
```

バッファは `uv_buf_t` 構造体で管理します。

```c
// include/uv.h でのバッファ定義
typedef struct {
  char* base;
  size_t len;
} uv_buf_t;
```

### 1.3 制御構造

libuv のイベントループ（`uv_run`）は `while` ループを中心に構成されています。各フェーズで処理を順番に実行します。

```c
// ファイル: src/unix/core.c:427-477
int uv_run(uv_loop_t* loop, uv_run_mode mode) {
  int timeout;
  int r;
  int can_sleep;

  r = uv__loop_alive(loop);
  if (!r)
    uv__update_time(loop);

  // タイマーの事前実行（後方互換性維持のため）
  if (mode == UV_RUN_DEFAULT && r != 0 && loop->stop_flag == 0) {
    uv__update_time(loop);
    uv__run_timers(loop);
  }

  while (r != 0 && loop->stop_flag == 0) {
    can_sleep =
        uv__queue_empty(&loop->pending_queue) &&
        uv__queue_empty(&loop->idle_handles);

    uv__run_pending(loop);    // 保留中のコールバック
    uv__run_idle(loop);       // idle ハンドラ
    uv__run_prepare(loop);    // prepare ハンドラ

    timeout = 0;
    if ((mode == UV_RUN_ONCE && can_sleep) || mode == UV_RUN_DEFAULT)
      timeout = uv__backend_timeout(loop);

    uv__io_poll(loop, timeout);  // I/Oポーリング

    uv__run_check(loop);          // check ハンドラ
    uv__run_closing_handles(loop); // クローズ処理

    uv__update_time(loop);
    uv__run_timers(loop);          // タイマー実行
    // ...
  }
}
```

### 1.4 関数/メソッド定義

libuv の公開API関数は `uv_` プレフィックスで始まり、内部関数は `uv__`（アンダースコア2つ）で始まります。関数は成功時に `0` を返し、失敗時に負のエラーコードを返します。

```c
// ファイル: src/timer.c:57-64（公開API）
int uv_timer_init(uv_loop_t* loop, uv_timer_t* handle) {
  uv__handle_init(loop, (uv_handle_t*)handle, UV_TIMER);
  handle->timer_cb = NULL;
  handle->timeout = 0;
  handle->repeat = 0;
  uv__queue_init(&handle->node.queue);
  return 0;
}
```

```c
// ファイル: src/unix/core.c:393-398（内部関数）
static int uv__loop_alive(const uv_loop_t* loop) {
  return uv__has_active_handles(loop) ||
         uv__has_active_reqs(loop) ||
         !uv__queue_empty(&loop->pending_queue) ||
         loop->closing_handles != NULL;
}
```

### 1.5 モジュール/インポート

C言語では `#include` ディレクティブでヘッダファイルを取り込みます。libuv は以下の階層でヘッダを管理しています。

```c
// ファイル: include/uv.h:54-55（公開サブヘッダの取り込み）
#include "uv/errno.h"
#include "uv/version.h"

// ファイル: include/uv.h:67-71（プラットフォーム別ヘッダの分岐取り込み）
#if defined(_WIN32)
# include "uv/win.h"
#else
# include "uv/unix.h"
#endif
```

内部ヘッダは `src/` 配下に配置され、共通処理の宣言を提供します。

```c
// ファイル: src/uv-common.h:27-39（内部共通ヘッダ）
#ifndef UV_COMMON_H_
#define UV_COMMON_H_
#include "uv.h"
#include "uv/tree.h"
#include "queue.h"
#include "strscpy.h"
```

---

## 2. プロジェクト固有の概念

> このセクションでは、libuv特有の概念を解説します。

### 2.1 フレームワーク固有の概念

libuv は独自のイベント駆動フレームワークであり、以下の中核概念があります。

**イベントループ (`uv_loop_t`):**
全ての非同期操作の中心。各ループは独立して動作し、ハンドルとリクエストを管理します。

**ハンドル (`uv_handle_t`):**
長期間存在するオブジェクト。アクティブな間、イベントループを維持します。TCP接続、タイマー、シグナルなどが該当します。ハンドルの型階層は以下の通りです。

```
uv_handle_t（基底）
  ├── uv_stream_t（ストリーム基底）
  │   ├── uv_tcp_t（TCP）
  │   ├── uv_pipe_t（パイプ）
  │   └── uv_tty_t（TTY）
  ├── uv_timer_t（タイマー）
  ├── uv_prepare_t / uv_check_t / uv_idle_t（ループフェーズハンドラ）
  ├── uv_async_t（非同期通知）
  ├── uv_process_t（プロセス）
  ├── uv_fs_event_t / uv_fs_poll_t（ファイル監視）
  ├── uv_signal_t（シグナル）
  ├── uv_poll_t（ポーリング）
  └── uv_udp_t（UDP）
```

**リクエスト (`uv_req_t`):**
短期間の操作を表すオブジェクト。ファイル読み書き、DNS解決、書き込み操作などが該当します。

```
uv_req_t（基底）
  ├── uv_write_t（書き込み）
  ├── uv_connect_t（接続）
  ├── uv_shutdown_t（シャットダウン）
  ├── uv_udp_send_t（UDP送信）
  ├── uv_fs_t（ファイルシステム操作）
  ├── uv_work_t（スレッドプール作業）
  ├── uv_getaddrinfo_t / uv_getnameinfo_t（DNS解決）
  └── uv_random_t（ランダムデータ）
```

**コールバック (`uv_*_cb`):**
非同期操作完了時に呼び出される関数ポインタ。操作の種類に応じた型が定義されています。

```c
// コールバック型の例
typedef void (*uv_read_cb)(uv_stream_t* stream, ssize_t nread, const uv_buf_t* buf);
typedef void (*uv_write_cb)(uv_write_t* req, int status);
typedef void (*uv_timer_cb)(uv_timer_t* handle);
typedef void (*uv_close_cb)(uv_handle_t* handle);
typedef void (*uv_connection_cb)(uv_stream_t* server, int status);
```

### 2.2 プロジェクト独自のパターン

**イベントループのフェーズ:**

libuv のイベントループは以下のフェーズを順に実行します。

```
┌─────────────────────────────────────────┐
│           uv_run() ループ開始            │
├─────────────────────────────────────────┤
│  1. uv__run_timers()      タイマー実行   │
│  2. uv__run_pending()     保留CB実行     │
│  3. uv__run_idle()        idle実行       │
│  4. uv__run_prepare()     prepare実行    │
│  5. uv__io_poll()         I/Oポーリング  │
│  6. uv__run_check()       check実行      │
│  7. uv__run_closing_handles() クローズ   │
│  8. uv__run_timers()      タイマー再実行 │
├─────────────────────────────────────────┤
│          ループ継続判定                   │
└─────────────────────────────────────────┘
```

**ハンドルのライフサイクル:**

```
init → start → [active] → stop → close → [closed]
```

すべてのハンドルは `uv_*_init()` で初期化し、`uv_close()` でクローズします。クローズコールバックが呼ばれるまでハンドルのメモリを解放してはいけません。

---

## 3. 命名規則

> このセクションでは、プロジェクト全体で使用される命名規則を解説します。

### 3.1 ファイル・ディレクトリ命名

| パターン | 意味 | 例 |
|---------|------|-----|
| `src/uv-*.c` | クロスプラットフォーム共通実装 | `uv-common.c`, `uv-data-getter-setters.c` |
| `src/unix/*.c` | Unix系プラットフォーム実装 | `core.c`, `tcp.c`, `stream.c` |
| `src/win/*.c` | Windows プラットフォーム実装 | `core.c`, `tcp.c`, `stream.c` |
| `src/*.h` | 内部ヘッダ（共通データ構造） | `queue.h`, `heap-inl.h` |
| `*-inl.h` | インライン関数定義ヘッダ | `heap-inl.h`, `handle-inl.h` |
| `include/uv/*.h` | プラットフォーム別公開ヘッダ | `unix.h`, `win.h`, `linux.h` |
| `test/test-*.c` | テストファイル | `test-timer.c`, `test-tcp-bind-error.c` |
| `test/benchmark-*.c` | ベンチマークファイル | `benchmark-ping-pongs.c` |

### 3.2 クラス・関数・変数命名

| プレフィックス/サフィックス | 意味 | 例 |
|---------------------------|------|-----|
| `uv_` | 公開API関数 | `uv_run()`, `uv_tcp_init()`, `uv_timer_start()` |
| `uv__` | 内部関数（非公開） | `uv__handle_init()`, `uv__io_poll()`, `uv__run_timers()` |
| `UV_` | 公開定数・列挙値 | `UV_TCP`, `UV_READABLE`, `UV_RUN_DEFAULT` |
| `UV__` | 内部定数・マクロ | `UV__ERR()`, `UV__EOF` |
| `_t` (サフィックス) | typedef された型名 | `uv_loop_t`, `uv_tcp_t`, `uv_buf_t` |
| `_s` (サフィックス) | 構造体タグ名 | `uv_loop_s`, `uv_handle_s` |
| `_cb` (サフィックス) | コールバック関数型 | `uv_read_cb`, `uv_timer_cb`, `uv_close_cb` |
| `UV_HANDLE_*` | ハンドルフラグ | `UV_HANDLE_ACTIVE`, `UV_HANDLE_CLOSING` |
| `UV_*_PRIVATE_FIELDS` | プラットフォーム固有フィールドマクロ | `UV_HANDLE_PRIVATE_FIELDS`, `UV_TCP_PRIVATE_FIELDS` |

### 3.3 プログラム分類一覧

| 分類 | プレフィックス/パターン | 説明 |
|------|----------------------|------|
| イベントループ | `uv_loop_*`, `uv_run` | ループの初期化・実行・停止 |
| ハンドル共通 | `uv_close`, `uv_ref`, `uv_unref`, `uv_is_active` | ハンドルの共通操作 |
| ストリーム | `uv_read_*`, `uv_write*`, `uv_listen`, `uv_accept` | ストリームI/O操作 |
| TCP | `uv_tcp_*` | TCP固有操作 |
| UDP | `uv_udp_*` | UDP固有操作 |
| パイプ | `uv_pipe_*` | パイプ固有操作 |
| TTY | `uv_tty_*` | TTY固有操作 |
| タイマー | `uv_timer_*` | タイマー操作 |
| ファイルシステム | `uv_fs_*` | 非同期ファイルシステム操作 |
| DNS | `uv_getaddrinfo`, `uv_getnameinfo` | 名前解決 |
| スレッド | `uv_thread_*`, `uv_mutex_*`, `uv_rwlock_*` | スレッド・同期プリミティブ |
| プロセス | `uv_spawn`, `uv_process_*` | プロセス管理 |
| シグナル | `uv_signal_*` | シグナルハンドリング |
| ユーティリティ | `uv_ip*_addr`, `uv_strerror`, `uv_err_name` | ヘルパー関数 |

---

## 4. ディレクトリ構造

> このセクションでは、プロジェクトのディレクトリ構造を解説します。

```
libuv-1.x/
├── include/              # 公開ヘッダファイル
│   ├── uv.h             #   メインヘッダ（全API）
│   └── uv/              #   サブヘッダ
│       ├── errno.h       #     エラーコード定義
│       ├── version.h     #     バージョン情報
│       ├── threadpool.h  #     スレッドプールAPI
│       ├── tree.h        #     ツリーデータ構造
│       ├── unix.h        #     Unix固有型定義
│       ├── win.h         #     Windows固有型定義
│       ├── linux.h       #     Linux固有定義
│       ├── darwin.h      #     macOS固有定義
│       └── ...           #     その他プラットフォーム固有
├── src/                  # ソースコード
│   ├── uv-common.c/h    #   クロスプラットフォーム共通実装
│   ├── timer.c           #   タイマー実装（共通）
│   ├── threadpool.c      #   スレッドプール実装（共通）
│   ├── queue.h           #   双方向リンクリスト
│   ├── heap-inl.h        #   最小ヒープ（タイマー用）
│   ├── unix/             #   Unix系プラットフォーム実装
│   │   ├── core.c        #     イベントループコア（uv_run）
│   │   ├── stream.c      #     ストリーム共通処理
│   │   ├── tcp.c         #     TCP実装
│   │   ├── udp.c         #     UDP実装
│   │   ├── pipe.c        #     パイプ実装
│   │   ├── fs.c          #     ファイルシステム実装
│   │   ├── process.c     #     プロセス管理
│   │   ├── signal.c      #     シグナル処理
│   │   ├── thread.c      #     スレッドAPI実装
│   │   ├── linux.c       #     Linux固有実装
│   │   ├── darwin.c      #     macOS固有実装
│   │   ├── kqueue.c      #     kqueue I/Oバックエンド
│   │   ├── internal.h    #     Unix内部ヘッダ
│   │   └── ...           #     その他OS固有実装
│   └── win/              #   Windows プラットフォーム実装
│       ├── core.c        #     IOCPベースイベントループ
│       ├── tcp.c         #     TCP実装
│       ├── pipe.c        #     名前付きパイプ実装
│       ├── internal.h    #     Windows内部ヘッダ
│       └── ...           #     その他Windows実装
├── test/                 # テストスイート
│   ├── run-tests.c       #   テストドライバーエントリポイント
│   ├── runner.c/h        #   テストランナー共通
│   ├── task.h            #   テストマクロ・アサーション
│   ├── test-list.h       #   テスト登録一覧
│   ├── test-*.c          #   個別テスト（177ファイル）
│   ├── benchmark-*.c     #   ベンチマーク（18ファイル）
│   └── fixtures/         #   テスト用補助ファイル
├── docs/                 # ドキュメント（Sphinx）
│   ├── src/              #   .rst ドキュメントソース
│   └── Makefile          #   ドキュメントビルド
├── cmake-toolchains/     # CMake クロスコンパイル設定
├── m4/                   # autotools マクロ
├── tools/                # ビルド・配布ツール
├── .github/              # GitHub Actions CI設定
├── CMakeLists.txt        # CMake ビルドシステム（推奨）
├── Makefile.am           # Autotools ビルド定義
├── configure.ac          # Autotools 設定
└── README.md             # プロジェクト概要
```

### 各ディレクトリの役割

| ディレクトリ | 役割 | 主要ファイル |
|-------------|------|-------------|
| `include/` | 公開API定義 | `uv.h`（全API集約） |
| `include/uv/` | プラットフォーム固有型定義 | `unix.h`, `win.h`, `errno.h` |
| `src/` | 共通ソースコード | `uv-common.c`, `timer.c`, `threadpool.c` |
| `src/unix/` | Unix系実装（54ファイル） | `core.c`, `stream.c`, `tcp.c` |
| `src/win/` | Windows実装（32ファイル） | `core.c`, `tcp.c`, `pipe.c` |
| `test/` | テストスイート | `test-list.h`（登録）, `task.h`（マクロ） |
| `docs/src/` | APIドキュメント | `loop.rst`, `tcp.rst` 等 |
| `.github/workflows/` | CI設定 | `CI-unix.yml`, `CI-win.yml` |

---

## 5. アーキテクチャ

> このセクションでは、プロジェクトのアーキテクチャパターンを解説します。

### 5.1 全体アーキテクチャ

libuv はプラットフォーム抽象化ライブラリであり、以下の階層構造を採用しています。

```mermaid
graph TB
    subgraph "ユーザーアプリケーション"
        APP[アプリケーションコード]
    end

    subgraph "公開API層"
        UV_H[include/uv.h]
        UV_UNIX_H[include/uv/unix.h]
        UV_WIN_H[include/uv/win.h]
    end

    subgraph "共通実装層"
        COMMON[src/uv-common.c]
        TIMER[src/timer.c]
        THREADPOOL[src/threadpool.c]
        QUEUE[src/queue.h]
        HEAP[src/heap-inl.h]
    end

    subgraph "プラットフォーム実装層"
        subgraph "Unix系"
            UNIX_CORE[src/unix/core.c]
            UNIX_STREAM[src/unix/stream.c]
            UNIX_TCP[src/unix/tcp.c]
            UNIX_FS[src/unix/fs.c]
        end
        subgraph "Windows"
            WIN_CORE[src/win/core.c]
            WIN_TCP[src/win/tcp.c]
            WIN_FS[src/win/fs.c]
        end
    end

    subgraph "OS固有層"
        LINUX[src/unix/linux.c]
        DARWIN[src/unix/darwin.c]
        KQUEUE[src/unix/kqueue.c]
        WINAPI[src/win/winapi.c]
    end

    APP --> UV_H
    UV_H --> UV_UNIX_H
    UV_H --> UV_WIN_H
    UV_H --> COMMON
    COMMON --> TIMER
    COMMON --> THREADPOOL
    COMMON --> QUEUE
    TIMER --> HEAP
    UV_UNIX_H --> UNIX_CORE
    UV_WIN_H --> WIN_CORE
    UNIX_CORE --> LINUX
    UNIX_CORE --> DARWIN
    UNIX_CORE --> KQUEUE
    WIN_CORE --> WINAPI
```

### 5.2 レイヤー構成

| レイヤー | 責務 | 代表的なファイル |
|---------|------|-----------------|
| 公開API | 型定義・関数宣言・定数定義 | `include/uv.h`, `include/uv/errno.h` |
| 共通実装 | プラットフォーム非依存ロジック | `src/uv-common.c`, `src/timer.c`, `src/threadpool.c` |
| プラットフォーム実装 | OS固有API呼び出しの抽象化 | `src/unix/core.c`, `src/win/core.c` |
| OS固有 | 特定OS向けの最適化・拡張 | `src/unix/linux.c`, `src/unix/darwin.c` |
| データ構造 | 汎用キュー・ヒープ・ツリー | `src/queue.h`, `src/heap-inl.h`, `include/uv/tree.h` |

### 5.3 データフロー

**非同期I/O操作のデータフロー:**

```
[ユーザー] → uv_write(req, stream, bufs, cb)
    ↓
[共通層] パラメータ検証、リクエスト初期化
    ↓
[プラットフォーム層] 書き込みキューに追加、I/Oウォッチャー登録
    ↓
[イベントループ] uv__io_poll() でFD準備完了を検知
    ↓
[プラットフォーム層] 実際の write() システムコール実行
    ↓
[共通層] コールバックキューに完了通知を追加
    ↓
[ユーザー] cb(req, status) コールバック呼び出し
```

**タイマーのデータフロー:**

```
[ユーザー] → uv_timer_start(handle, cb, timeout, repeat)
    ↓
[共通層] 最小ヒープにタイマーを挿入
    ↓
[イベントループ] uv__run_timers() でヒープから期限切れタイマーを取得
    ↓
[共通層] ready_queue に移動 → コールバック順次実行
    ↓
[ユーザー] cb(handle) コールバック呼び出し
```

---

## 6. 主要コンポーネント

> このセクションでは、主要なコンポーネントとその連携を解説します。

### 6.1 エントリーポイント

libuv はライブラリであり、単一のエントリーポイントはありません。利用者は `uv_loop_init()` でループを初期化し、`uv_run()` でイベントループを開始します。

```c
// 典型的な利用パターン
uv_loop_t loop;
uv_loop_init(&loop);

// ハンドルやリクエストの登録...

uv_run(&loop, UV_RUN_DEFAULT);  // イベントループ開始
uv_loop_close(&loop);           // クリーンアップ
```

イベントループのコア実装は以下のファイルにあります。

| プラットフォーム | ファイル | I/Oバックエンド |
|----------------|---------|----------------|
| Linux | `src/unix/core.c` + `src/unix/linux.c` | epoll |
| macOS/BSD | `src/unix/core.c` + `src/unix/kqueue.c` | kqueue |
| Windows | `src/win/core.c` | IOCP |
| SunOS | `src/unix/core.c` + `src/unix/sunos.c` | event ports |

### 6.2 ビジネスロジック

libuv のビジネスロジックは機能別にファイルが分割されています。

**ストリーム処理 (`src/unix/stream.c`):**
TCP、パイプ、TTYの共通ストリーム処理を実装。読み取り・書き込み・シャットダウンの統一インターフェースを提供します。

```c
// ファイル: src/unix/stream.c:81-116（ストリーム初期化）
void uv__stream_init(uv_loop_t* loop,
                     uv_stream_t* stream,
                     uv_handle_type type) {
  uv__handle_init(loop, (uv_handle_t*)stream, type);
  stream->read_cb = NULL;
  stream->alloc_cb = NULL;
  stream->close_cb = NULL;
  stream->connection_cb = NULL;
  stream->connect_req = NULL;
  stream->shutdown_req = NULL;
  stream->accepted_fd = -1;
  stream->queued_fds = NULL;
  stream->delayed_error = 0;
  uv__queue_init(&stream->write_queue);
  uv__queue_init(&stream->write_completed_queue);
  stream->write_queue_size = 0;
  // ...
  uv__io_init(&stream->io_watcher, UV__STREAM_IO, -1);
}
```

**タイマー処理 (`src/timer.c`):**
最小ヒープを用いたタイマー管理。プラットフォーム共通の実装です。

```c
// ファイル: src/timer.c:164-194（タイマー実行）
void uv__run_timers(uv_loop_t* loop) {
  struct heap_node* heap_node;
  uv_timer_t* handle;

  for (;;) {
    heap_node = heap_min(timer_heap(loop));
    if (heap_node == NULL)
      break;

    handle = container_of(heap_node, uv_timer_t, node.heap);
    if (handle->timeout > loop->time)
      break;

    uv_timer_stop(handle);
    uv__queue_insert_tail(&ready_queue, &handle->node.queue);
  }
  // ready_queue から順にコールバック実行
}
```

### 6.3 データアクセス

libuv のデータアクセスは、主に以下の内部データ構造で管理されます。

**双方向リンクリスト (`src/queue.h`):**
ハンドルキュー、書き込みキュー、保留キュー等に使用。

```c
// ファイル: src/queue.h:21-30
#define uv__queue_data(pointer, type, field) \
  ((type*) ((char*) (pointer) - offsetof(type, field)))

#define uv__queue_foreach(q, h) \
  for ((q) = (h)->next; (q) != (h); (q) = (q)->next)

static inline void uv__queue_init(struct uv__queue* q) {
  q->next = q;
  q->prev = q;
}
```

**最小ヒープ (`src/heap-inl.h`):**
タイマーの効率的な管理に使用。次に発火するタイマーをO(1)で取得できます。

**赤黒木 (`include/uv/tree.h`):**
シグナルハンドルの管理等に使用。

### 6.4 ユーティリティ/共通機能

**メモリ管理 (`src/uv-common.c:41-90`):**
カスタムアロケータに対応した統一メモリ管理。errno の保護機能付き。

```c
// ファイル: src/uv-common.c:41-53（カスタムアロケータ）
typedef struct {
  uv_malloc_func local_malloc;
  uv_realloc_func local_realloc;
  uv_calloc_func local_calloc;
  uv_free_func local_free;
} uv__allocator_t;

static uv__allocator_t uv__allocator = {
  malloc, realloc, calloc, free,
};
```

```c
// ファイル: src/uv-common.c:81-90（errno保護付きfree）
void uv__free(void* ptr) {
  int saved_errno;
  saved_errno = errno;
  uv__allocator.local_free(ptr);
  errno = saved_errno;
}
```

**エラーハンドリング (`src/uv-common.c:221-228`):**
マクロによるエラーコードの自動生成。

```c
// ファイル: src/uv-common.c:221-228
#define UV_ERR_NAME_GEN(name, _) case UV_ ## name: return #name;
const char* uv_err_name(int err) {
  switch (err) {
    UV_ERRNO_MAP(UV_ERR_NAME_GEN)
  }
  return uv__unknown_err_code(err);
}
#undef UV_ERR_NAME_GEN
```

---

## 7. よく使われるパターン

> このセクションでは、コード内で頻出するパターンを解説します。

### パターン一覧

| パターン | 説明 | 出現頻度 | 代表的なファイル |
|---------|------|---------|-----------------|
| XX マクロパターン | マクロで繰り返し処理を自動生成 | 高 | `include/uv.h`, `src/uv-common.c` |
| ハンドル初期化パターン | `uv__handle_init` による統一初期化 | 高 | `src/timer.c`, `src/unix/tcp.c` |
| container_of パターン | 埋め込みメンバから親構造体へアクセス | 高 | `src/timer.c`, `src/unix/stream.c` |
| コールバックキューパターン | キューに蓄積して一括実行 | 高 | `src/unix/stream.c` |
| errno 保護パターン | SAVE_ERRNO マクロでerrno退避・復元 | 中 | `src/unix/internal.h`, `src/uv-common.c` |
| プラットフォーム分岐パターン | #ifdef による条件コンパイル | 高 | `include/uv.h`, `src/uv-common.h` |
| スタックバッファ最適化 | 小規模データはスタック、大規模はヒープ | 中 | `src/unix/stream.c` |

### 各パターンの詳細

#### パターン1: XX マクロパターン

**目的:** 一度の定義で複数箇所での処理（文字列化、switch-case生成等）を自動化する。

**実装例:**
```c
// ファイル: include/uv.h:74-159
#define UV_ERRNO_MAP(XX)                                                      \
  XX(E2BIG, "argument list too long")                                         \
  XX(EACCES, "permission denied")                                             \
  XX(EADDRINUSE, "address already in use")                                    \
  // ... 80以上のエラーコード
```

```c
// ファイル: src/uv-common.c:221-228（エラー名取得に利用）
#define UV_ERR_NAME_GEN(name, _) case UV_ ## name: return #name;
const char* uv_err_name(int err) {
  switch (err) {
    UV_ERRNO_MAP(UV_ERR_NAME_GEN)
  }
  return uv__unknown_err_code(err);
}
```

**解説:** `UV_ERRNO_MAP` マクロに異なる `XX` マクロを渡すことで、同じエラー一覧から列挙値定義、文字列化、メッセージ取得など複数の処理を自動生成します。定義の追加・変更が1箇所で済み、一貫性を保証します。

#### パターン2: ハンドル初期化パターン

**目的:** 全ハンドル型の共通フィールドを一貫して初期化する。

**実装例:**
```c
// ファイル: src/timer.c:57-64
int uv_timer_init(uv_loop_t* loop, uv_timer_t* handle) {
  uv__handle_init(loop, (uv_handle_t*)handle, UV_TIMER);  // 共通初期化
  handle->timer_cb = NULL;    // タイマー固有フィールド
  handle->timeout = 0;
  handle->repeat = 0;
  uv__queue_init(&handle->node.queue);
  return 0;
}
```

**解説:** `uv__handle_init()` がハンドルキューへの追加、型の設定、参照カウント等の共通処理を行い、その後に各ハンドル固有のフィールドを初期化します。C言語での疑似的な継承パターンです。

#### パターン3: container_of パターン

**目的:** 構造体内に埋め込まれたメンバのポインタから、親構造体のポインタを取得する。

**実装例:**
```c
// ファイル: src/uv-common.h:58-59
#define container_of(ptr, type, member) \
  ((type *) ((char *) (ptr) - offsetof(type, member)))

// ファイル: src/timer.c:175（使用例）
handle = container_of(heap_node, uv_timer_t, node.heap);

// ファイル: src/unix/stream.c:512（使用例）
stream = container_of(w, uv_stream_t, io_watcher);
```

**解説:** Linuxカーネルでも使われる定番パターンです。libuv では、ヒープノードからタイマーハンドルへ、I/Oウォッチャーからストリームへのアクセスに多用されます。

#### パターン4: errno 保護パターン

**目的:** 内部処理で errno が上書きされるのを防ぐ。

**実装例:**
```c
// ファイル: src/unix/internal.h:121-127
#define SAVE_ERRNO(block) \
  do { \
    int _saved_errno = errno; \
    do { block; } while (0); \
    errno = _saved_errno; \
  } \
  while (0)

// 使用例
SAVE_ERRNO(uv__update_time(loop));
```

**解説:** libuv は非同期ライブラリのため、操作の成否をユーザーに正確に伝える必要があります。内部処理でerrnoが変更されないよう保護します。

#### パターン5: スタックバッファ最適化

**目的:** 小規模データではヒープ割り当てを避け、パフォーマンスを向上させる。

**実装例:**
```c
// ファイル: src/unix/stream.c:1362-1365
req->bufs = req->bufsml;  // スタック上の小規模バッファを使用
if (nbufs > ARRAY_SIZE(req->bufsml))
  req->bufs = uv__malloc(nbufs * sizeof(bufs[0]));  // 大規模時のみヒープ
```

**解説:** `uv_write_t` 構造体に埋め込まれた `bufsml` 配列を利用し、バッファ数が少ない場合はメモリ割り当てを回避します。高頻度な書き込み操作のパフォーマンスに寄与します。

---

## 8. 業務フロー追跡の実践例

> このセクションでは、実際の業務フローをコードで追跡する方法を解説します。

### 8.1 フロー追跡の基本手順

1. エントリーポイントを特定（`include/uv.h` でAPI関数を確認）
2. 処理の流れを追跡（共通層 → プラットフォーム層の呼び出し関係を追う）
3. データの変換を確認（リクエストオブジェクトの状態変化）
4. 最終的な出力を確認（コールバック呼び出し）

### 8.2 フロー追跡の実例

#### 例1: TCPサーバーの接続受付

**概要:** TCPサーバーがクライアント接続を受け付け、データを読み取るフロー

**処理フロー:**
```
uv_tcp_init() → uv_tcp_bind() → uv_listen() → [接続受付] → uv_accept() → uv_read_start()
```

**詳細な追跡:**

1. **TCP ハンドル初期化** (`src/unix/tcp.c`)
   ```c
   // uv_tcp_init() → uv_tcp_init_ex()
   int uv_tcp_init_ex(uv_loop_t* loop, uv_tcp_t* tcp, unsigned int flags) {
     // ストリーム共通初期化を呼び出し
     uv__stream_init(loop, (uv_stream_t*)tcp, UV_TCP);
     // ...
   }
   ```

2. **アドレスバインド** (`src/unix/tcp.c`)
   ```c
   // uv_tcp_bind() → uv__tcp_bind()
   // socket() でソケット作成 → bind() でアドレスバインド
   ```

3. **リッスン開始** (`src/unix/stream.c`)
   ```c
   // uv_listen() でコールバックを登録し、I/Oウォッチャーを有効化
   // listen() システムコール実行
   ```

4. **接続検知** (`src/unix/stream.c`)
   ```c
   // uv__io_poll() が POLLIN を検知
   // → uv__server_io() が呼ばれる
   // → connection_cb(server, 0) をユーザーに通知
   ```

5. **接続受付** (`src/unix/stream.c`)
   ```c
   // ユーザーが connection_cb 内で uv_accept() を呼ぶ
   // → accept() システムコール実行
   // → 新しいストリームにFDを設定
   ```

6. **データ読み取り開始** (`src/unix/stream.c`)
   ```c
   // uv_read_start() でI/Oウォッチャーを有効化
   // → データ到着時に alloc_cb → read_cb の順で呼ばれる
   ```

#### 例2: タイマーの発火

**概要:** タイマーを設定し、指定時間後にコールバックが呼ばれるフロー

**処理フロー:**
```
uv_timer_init() → uv_timer_start() → [イベントループ] → uv__run_timers() → timer_cb()
```

**詳細な追跡:**

1. **タイマー初期化** (`src/timer.c:57-64`)
   ```c
   int uv_timer_init(uv_loop_t* loop, uv_timer_t* handle) {
     uv__handle_init(loop, (uv_handle_t*)handle, UV_TIMER);
     handle->timer_cb = NULL;
     handle->timeout = 0;
     handle->repeat = 0;
     return 0;
   }
   ```

2. **タイマー開始** (`src/timer.c:69-97`)
   ```c
   int uv_timer_start(uv_timer_t* handle, uv_timer_cb cb,
                       uint64_t timeout, uint64_t repeat) {
     // 既に実行中なら停止
     if (uv__is_active(handle)) uv_timer_stop(handle);
     // タイムアウト時刻を計算
     handle->timeout = handle->loop->time + timeout;
     handle->timer_cb = cb;
     handle->repeat = repeat;
     // 最小ヒープに挿入
     heap_insert(timer_heap(handle->loop), ...);
     uv__handle_start(handle);
     return 0;
   }
   ```

3. **タイマー実行** (`src/timer.c:164-194`)
   ```c
   void uv__run_timers(uv_loop_t* loop) {
     // ヒープの最小値（最も早く期限切れするタイマー）を取得
     // 期限切れなら ready_queue に移動
     // ready_queue から順にコールバック実行: handle->timer_cb(handle)
   }
   ```

### 8.3 フロー追跡チェックリスト

- [ ] エントリーポイントを特定したか（`include/uv.h` で公開API確認）
- [ ] 共通層 (`src/uv-common.c`) での処理を確認したか
- [ ] プラットフォーム固有層（`src/unix/` or `src/win/`）での処理を確認したか
- [ ] データの変換ポイント（バッファ操作、キュー操作）を確認したか
- [ ] エラーハンドリング（`UV__ERR()` での変換）を確認したか
- [ ] コールバック呼び出しの条件と引数を確認したか

---

## 9. 設計書の参照順序

> このセクションでは、プロジェクト理解のための設計書参照順序を案内します。

### 9.1 目的別ロードマップ

#### 全体像を把握したい場合
1. `README.md` - プロジェクト概要と主要機能
2. `docs/src/design.rst` - 設計思想
3. `docs/src/guide.rst` - libuv ガイド
4. `include/uv.h` - 公開API全体

#### 特定機能を理解したい場合
1. `include/uv.h` - 対象機能のAPI宣言を確認
2. `docs/src/` 配下の対応 `.rst` ファイル（例: `tcp.rst`, `timer.rst`）
3. `src/uv-common.c` - 共通実装を確認
4. `src/unix/` or `src/win/` 配下の対応ソースファイル

#### 改修作業を行う場合
1. `include/uv.h` - 影響するAPIの確認
2. `src/uv-common.h` - 内部フラグ・マクロの確認
3. `src/unix/internal.h` or `src/win/internal.h` - プラットフォーム内部APIの確認
4. `test/test-*.c` - 対象機能のテストケースを確認
5. `CONTRIBUTING.md` - コーディング規約の確認

#### 新しいプラットフォームを追加したい場合
1. `SUPPORTED_PLATFORMS.md` - サポート対象の確認
2. `src/unix/linux.c` or `src/unix/darwin.c` - 既存のOS固有実装を参考
3. `CMakeLists.txt` - ビルド設定の追加方法を確認

### 9.2 ドキュメント一覧

| ドキュメント | 概要 | 参照タイミング |
|-------------|------|---------------|
| `README.md` | プロジェクト概要、ビルド方法、ライセンス | 最初に読む |
| `CONTRIBUTING.md` | 貢献ガイド、コーディング規約 | 開発参加時 |
| `SUPPORTED_PLATFORMS.md` | サポートプラットフォーム一覧 | プラットフォーム対応確認時 |
| `docs/src/design.rst` | 設計思想 | アーキテクチャ理解時 |
| `docs/src/guide.rst` | libuvガイド | 全体理解時 |
| `docs/src/loop.rst` | イベントループ詳細 | ループ動作理解時 |
| `docs/src/handle.rst` | ハンドル概要 | ハンドル概念理解時 |
| `docs/src/stream.rst` | ストリームAPI | ストリーム系操作時 |
| `docs/src/tcp.rst` | TCP API | TCP機能の開発時 |
| `docs/src/fs.rst` | ファイルシステムAPI | FS機能の開発時 |
| `docs/src/errors.rst` | エラーハンドリング | エラー処理実装時 |
| `docs/src/threading.rst` | スレッドAPI | スレッド関連開発時 |
| `docs/src/upgrading.rst` | アップグレードガイド | バージョン更新時 |

---

## 10. トラブルシューティング

> このセクションでは、コードリーディング時によくある問題と解決法を解説します。

### よくある疑問と回答

#### Q: `uv_` と `uv__` の違いは何ですか？
A: `uv_` プレフィックスは公開APIで、`include/uv.h` で宣言されています。`uv__` は内部関数で、外部から呼び出すべきではありません。内部関数は `src/uv-common.h`, `src/unix/internal.h`, `src/win/internal.h` 等で宣言されています。

#### Q: `container_of` マクロが理解できません
A: これは構造体メンバのポインタから、その構造体自体のポインタを逆算するマクロです。`offsetof` でメンバのオフセットを取得し、ポインタから差し引きます。例えば、`uv_timer_t` のヒープノードメンバから `uv_timer_t` 本体のポインタを得る際に使います（`src/uv-common.h:58-59`）。

#### Q: 同じ名前のファイルが `src/unix/` と `src/win/` にありますが、どちらが使われますか？
A: ビルドシステム（CMakeLists.txt）がプラットフォームに応じて適切なファイルを選択します。Unix系では `src/unix/` 配下のファイルが、Windowsでは `src/win/` 配下のファイルがコンパイルされます。両方が同時にコンパイルされることはありません。

#### Q: `UV_HANDLE_*` フラグはどのように管理されていますか？
A: `src/uv-common.h:80-141` で定義されています。下位ビット（0x00000001〜0x00010000）は全ハンドル共通フラグ、上位ビット（0x01000000〜）はハンドル型固有フラグです。同じビット位置が異なるハンドル型で異なる意味を持つことがあります（例: TCP の `UV_HANDLE_TCP_NODELAY` と UDP の `UV_HANDLE_UDP_PROCESSING` は同じ `0x01000000`）。

#### Q: テストの追加方法は？
A: 以下の手順で追加します。
1. `test/test-mytest.c` にテスト関数 `TEST_IMPL(mytest) { ... }` を実装
2. `test/test-list.h` の宣言セクションに `TEST_DECLARE(mytest)` を追加
3. `test/test-list.h` の登録セクションに `TEST_ENTRY(mytest)` を追加
4. `CMakeLists.txt` のテストソースリストに `test/test-mytest.c` を追加

### デバッグのヒント

**ビルド方法:**
```bash
# CMake（推奨）
mkdir build && cd build
cmake .. -DBUILD_TESTING=ON
cmake --build .

# テスト実行
./uv_run_tests           # 全テスト実行
./uv_run_tests timer     # 特定テスト実行
```

**サニタイザーの活用:**
CMake ビルドで AddressSanitizer 等を有効化できます。
```bash
cmake .. -DASAN=ON   # AddressSanitizer
cmake .. -DTSAN=ON   # ThreadSanitizer
cmake .. -DUBSAN=ON  # UndefinedBehaviorSanitizer
```

**デバッグ時に注目すべきファイル:**
- `src/uv-common.h` - ハンドルフラグとマクロ定義
- `src/unix/internal.h` - Unix内部マクロ（`SAVE_ERRNO`, `UNREACHABLE` 等）
- `test/task.h` - テスト用アサーションマクロ

---

## 付録

### A. 用語集

| 用語 | 説明 |
|-----|------|
| Handle（ハンドル） | 長期間存在するオブジェクト。アクティブな間イベントループを維持する |
| Request（リクエスト） | 短期間の操作を表すオブジェクト。完了時にコールバックが呼ばれる |
| Event Loop | ハンドルとリクエストを管理し、I/Oイベントを待機・処理するメインループ |
| Callback | 非同期操作完了時に呼び出される関数ポインタ |
| watcher | I/Oイベントを監視する内部構造体（`uv__io_t`） |
| epoll / kqueue / IOCP | OS固有のI/O多重化メカニズム（Linux / BSD・macOS / Windows） |
| TAP | Test Anything Protocol。テスト結果の出力フォーマット |
| container_of | 埋め込みメンバから親構造体のポインタを逆算するマクロ |
| XX マクロ | 高階マクロパターン。一覧定義から複数の処理を自動生成する技法 |

### B. ファイル一覧

| ファイル/ディレクトリ | 説明 | 主な内容 |
|---------------------|------|---------|
| `include/uv.h` | メインヘッダ | 全公開API・型・定数の宣言 |
| `include/uv/errno.h` | エラーコード | プラットフォーム共通エラー定義 |
| `include/uv/version.h` | バージョン情報 | メジャー/マイナー/パッチ番号 |
| `include/uv/unix.h` | Unix型定義 | pthread, fd等のtypedef |
| `include/uv/win.h` | Windows型定義 | HANDLE, SOCKET等のtypedef |
| `src/uv-common.c` | 共通実装 | メモリ管理、エラー変換、バッファ操作 |
| `src/uv-common.h` | 共通内部ヘッダ | フラグ定義、ユーティリティマクロ |
| `src/timer.c` | タイマー実装 | ヒープベースのタイマー管理 |
| `src/threadpool.c` | スレッドプール | ワーカースレッド管理 |
| `src/queue.h` | キューデータ構造 | 侵入型双方向リンクリスト |
| `src/heap-inl.h` | ヒープデータ構造 | 最小ヒープ（タイマー用） |
| `src/unix/core.c` | Unix イベントループ | `uv_run()` の実装 |
| `src/unix/stream.c` | ストリーム処理 | 読み書き・接続の共通処理 |
| `src/unix/tcp.c` | TCP実装 | ソケット作成・バインド・接続 |
| `src/unix/internal.h` | Unix内部ヘッダ | マクロ・内部関数宣言 |
| `src/win/core.c` | Windows イベントループ | IOCPベースの実装 |
| `test/task.h` | テストマクロ | `TEST_IMPL`, `ASSERT_*` 等 |
| `test/test-list.h` | テスト登録 | 全テストの宣言と登録 |
| `CMakeLists.txt` | CMakeビルド | ビルド設定・テスト設定 |

### C. 参考資料

- [libuv 公式ドキュメント](http://docs.libuv.org)
- [libuv GitHub リポジトリ](https://github.com/libuv/libuv)
- [An Introduction to libuv (公式ガイド)](http://docs.libuv.org/en/latest/guide.html)
- [libuv 設計思想](http://docs.libuv.org/en/latest/design.html)
- [C11 標準仕様](https://www.iso.org/standard/57853.html)
- [Semantic Versioning](https://semver.org/)
