# libuv 業務運用マニュアル

## 目次

**【基本操作】**
1. [システム概要](#1-システム概要)
2. [インストール・セットアップ手順](#2-インストールセットアップ手順)
3. [トップページ（ドキュメントサイト）](#3-トップページドキュメントサイト)

**【業務フローに沿った機能】**
4. [【STEP1】環境構築（ビルド・導入）](#4-step1環境構築ビルド導入)
5. [【STEP2-3】基本API利用（イベントループ・ハンドル・リクエスト）](#5-step2-3基本api利用イベントループハンドルリクエスト)
6. [【STEP3-4】ネットワーク・ファイルI/O（TCP/UDP/ファイル操作）](#6-step3-4ネットワークファイルiotcpudpファイル操作)
7. [【STEP4-5】応用機能・パフォーマンス確認（スレッド・プロセス・メトリクス）](#7-step4-5応用機能パフォーマンス確認スレッドプロセスメトリクス)

**【サポート機能】**
8. [エラーハンドリング](#8-エラーハンドリング)
9. [ドキュメントサイトの活用](#9-ドキュメントサイトの活用)
10. [ユーティリティ機能](#10-ユーティリティ機能)

**【運用ガイド】**
11. [日常業務の流れ](#11-日常業務の流れ)
12. [よくある質問と対処法](#12-よくある質問と対処法)
13. [トラブルシューティング](#13-トラブルシューティング)

---

## 1. システム概要

### 1.1 libuvとは

libuv は、非同期I/O処理に焦点を当てたマルチプラットフォーム対応のCライブラリです。元々 Node.js のために開発され、現在は Luvit、Julia、uvloop など多くのプロジェクトで利用されています。Linux では epoll、macOS/BSD では kqueue、Windows では IOCP（I/O Completion Ports）をバックエンドとしたイベント駆動型の非同期I/Oモデルを提供します。現在のバージョンは 1.52.1-dev（開発版）です。

> **注記**: 本プロジェクトはGUIを持つWebアプリケーションではなく、C言語のシステムライブラリです。本マニュアルでは、開発者がlibuvを利用・開発する際の業務フローを中心に記載しています。「画面」はSphinxで生成されるドキュメントWebサイトのページを指します。

### 1.2 本システムで行う主要業務

本ライブラリは、主に以下の業務を支援します：

| 業務カテゴリ | 具体的な業務内容 |
|------------|----------------|
| **非同期ネットワークI/O** | TCP/UDPソケット通信、パイプ（IPC）、DNS解決 |
| **非同期ファイルI/O** | ファイル読み書き、ディレクトリ操作、ファイル監視 |
| **イベント駆動制御** | イベントループの初期化・実行・管理、タイマー、シグナル処理 |
| **スレッド・並行処理** | スレッド生成・管理、スレッドプール、同期プリミティブ |
| **プロセス管理** | 子プロセス生成・管理、標準入出力リダイレクト |
| **システム情報取得** | CPU情報、メモリ使用量、ネットワークインターフェース、環境変数操作 |

### 1.3 業務フロー概要

本ライブラリを用いた開発は、以下の流れで進行します：

```
┌─────────────────────────────────────────────────────────────────┐
│                        開発業務フロー                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  【STEP 1】開発者がlibuv環境を構築（ビルド・インストール）         │
│      ↓                                                          │
│  【STEP 2】イベントループ・ハンドル・リクエストの基本を理解         │
│      ↓                                                          │
│  【STEP 3】アプリケーションにAPI（ネットワーク/ファイルI/O等）を組込│
│      ↓                                                          │
│  【STEP 4】テスト・デバッグ・パフォーマンス確認                    │
│      ↓                                                          │
│  【STEP 5】本番環境へのデプロイ・運用                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

**役割別の業務概要：**

| 役割 | 主な業務 |
|------|---------|
| **ライブラリ利用開発者** | libuvのインストール、APIを使ったアプリケーション開発、テスト実行、デバッグ |
| **libuvコントリビュータ** | ソースコードの修正・機能追加、テストスイート実行、ドキュメント更新、プルリクエスト作成 |

### 1.4 主な機能

| 機能 | 説明 | 業務フローでの位置 |
|------|------|------------------|
| イベントループ | epoll/kqueue/IOCPを抽象化したクロスプラットフォームイベントループ | STEP 2（基本理解） |
| TCP/UDPソケット | 非同期ネットワーク通信 | STEP 3（API組込） |
| パイプ・IPC | プロセス間通信 | STEP 3（API組込） |
| ファイルシステム | 非同期ファイルI/O操作 | STEP 3（API組込） |
| ファイル監視 | ファイル変更イベント検知 | STEP 3（API組込） |
| DNS解決 | 非同期DNSアドレス解決 | STEP 3（API組込） |
| プロセス管理 | 子プロセスの生成・管理 | STEP 3（API組込） |
| シグナル処理 | UNIXシグナルの非同期ハンドリング | STEP 3（API組込） |
| スレッドプール | ワーカースレッドによる非同期タスク実行 | STEP 3-4（API組込・性能確認） |
| スレッド・同期プリミティブ | ミューテックス、セマフォ、条件変数等 | STEP 3-4（API組込・性能確認） |
| タイマー | ミリ秒精度のタイマースケジューリング | STEP 3（API組込） |
| メトリクス | イベントループのパフォーマンス計測 | STEP 4（性能確認） |

### 1.5 ユーザー種別

システムには以下のユーザー種別があります：

| ユーザー種別 | 説明 |
|-------------|------|
| ライブラリ利用開発者 | 自身のアプリケーションにlibuvを組み込んで利用する開発者 |
| libuvコントリビュータ | libuv本体のソースコードに貢献する開発者（バグ修正・機能追加等） |
| ドキュメント閲覧者 | APIリファレンスやユーザーガイドを参照してlibuvの使い方を学習するユーザー |

### 1.6 対応プラットフォーム

libuvは以下のプラットフォームに対応しています：

| ティア | プラットフォーム |
|--------|----------------|
| Tier 1（CI自動テスト） | GNU/Linux（glibc 2.17+, Linux 3.10+）、macOS 11+、Windows 10+ |
| Tier 2（公式サポート） | FreeBSD 12+、AIX 6+、IBM i 7.2+、z/OS V2R2+、Linux musl 1.0+ |
| Tier 3（コミュニティ） | Android（NDK r15b+）、MinGW-w64 |

**ビルド要件：**
- C11対応コンパイラ（GCC 4.8+、Clang、MSVC 2017+、Apple Clang）
- CMake 3.10以上 または Autotools（automake、autoconf、libtool）

---

## 2. インストール・セットアップ手順

### 2.1 ソースコードからのビルド（CMake方式・推奨）

1. ソースコードを取得します

```bash
git clone https://github.com/libuv/libuv.git
cd libuv
git checkout v1.x
```

2. CMakeでビルドを実行します

```bash
cmake -B build -DBUILD_TESTING=ON
cmake --build build
```

3. テストを実行して動作を確認します

```bash
cd build && ctest -C Debug --output-on-failure
```

4. システムにインストールします

```bash
cmake --install build
```

### 2.2 ソースコードからのビルド（Autotools方式・UNIX系）

1. autogen.shを実行してビルドスクリプトを生成します

```bash
sh autogen.sh
```

2. configureとmakeを実行します

```bash
./configure
make
make install
```

### 2.3 パッケージマネージャによるインストール

パッケージマネージャを使用して簡単にインストールできます：

| パッケージマネージャ | コマンド |
|---------------------|---------|
| Homebrew（macOS） | `brew install --HEAD libuv` |
| vcpkg（Windows） | `vcpkg install libuv` |
| Conan | `conan install --requires="libuv/[*]" --build=missing` |

### 2.4 クロスコンパイル（MinGW-w64の例）

Windows向けクロスコンパイルを行う場合は以下のようにCMakeを構成します：

```bash
cmake ../.. \
  -DCMAKE_SYSTEM_NAME=Windows \
  -DCMAKE_SYSTEM_VERSION=6.1 \
  -DCMAKE_C_COMPILER=i686-w64-mingw32-gcc
```

### 2.5 プロジェクトへの組み込み

libuvをアプリケーションプロジェクトに組み込むには、CMakeLists.txtに以下を追加します：

```cmake
find_package(libuv REQUIRED)
target_link_libraries(your_app PRIVATE uv)
```

ヘッダファイルをインクルードします：

```c
#include <uv.h>
```

---

## 3. トップページ（ドキュメントサイト）

### 3.1 ドキュメントサイト概要

libuvのドキュメントはSphinx（RST形式）で生成されるWebサイトとして提供されます。トップページ（`docs/src/index.rst`）から全ドキュメントにアクセスできます。

**ドキュメント構成：**

```
トップページ (index.rst)
├── 設計概要 (design.rst) ─── アーキテクチャ・設計思想の説明
├── APIドキュメント一覧 (api.rst) ─── 27件のAPIリファレンスページ
├── ユーザーガイド一覧 (guide.rst) ─── 9件の実践ガイドページ
└── アップグレードガイド (upgrading.rst) ─── バージョン間移行ガイド
```

### 3.2 ドキュメントのローカルビルド

ドキュメントをローカル環境でビルド・閲覧するには以下の手順を実行します：

1. docsディレクトリに移動します
2. 以下のコマンドでビルドします

```bash
cd docs
make html      # HTMLドキュメント生成
make man       # manページ生成
make livehtml  # ホットリロード付きプレビュー（開発中に推奨）
```

3. 生成されたHTMLは `docs/_build/html/` に出力されます

---

## 4. 【STEP1】環境構築（ビルド・導入）

> **業務フローでの位置**: 開発者がlibuvの開発環境を構築し、ライブラリのビルドとインストールを完了するステップです。

### 4.1 ライブラリ利用開発者向け：環境構築

**業務シーン**: 自分のアプリケーションにlibuvを組み込みたい

**前提条件**:
- C11対応コンパイラがインストールされていること
- CMake 3.10以上がインストールされていること

**やるべきこと**:
1. libuvをインストールする
2. プロジェクトのビルドシステムにlibuvの依存を追加する
3. ヘッダファイル `<uv.h>` をインクルードできることを確認する

**システムでの操作手順**:

1. パッケージマネージャまたはソースコードからlibuvをインストールします（[2章](#2-インストールセットアップ手順)参照）
2. CMakeLists.txtに依存関係を追加します：

```cmake
find_package(libuv REQUIRED)
target_link_libraries(your_app PRIVATE uv)
```

3. テストプログラムをコンパイルして動作確認します：

```c
#include <stdio.h>
#include <uv.h>

int main() {
    uv_loop_t *loop = uv_default_loop();
    printf("libuv version: %s\n", uv_version_string());
    uv_run(loop, UV_RUN_DEFAULT);
    return 0;
}
```

**関連ドキュメント**: 「設計概要」（design.rst）、「基本事項」ガイド（guide/basics.rst）

**注意点・Tips**:
- 静的リンク（`libuv_a`）と動的リンク（`libuv`）を正しく区別してください
- Windows環境で共有ライブラリを使用する場合は `USING_UV_SHARED` マクロを定義してください

**次のステップ**: STEP2（イベントループの基本理解）へ進みます

### 4.2 コントリビュータ向け：開発環境構築

**業務シーン**: libuv本体のバグ修正・機能追加を行いたい

**前提条件**:
- GitHubアカウントがあること
- C11コンパイラ、CMake 3.10+がインストールされていること

**やるべきこと**:
1. リポジトリをフォークしてクローンする
2. テスト付きでビルドする
3. テストが全て通ることを確認する

**システムでの操作手順**:

1. リポジトリをフォーク・クローンします：

```bash
git clone https://github.com/<your-username>/libuv.git
cd libuv
git checkout v1.x
```

2. テスト有効でビルドします：

```bash
cmake -B build -DBUILD_TESTING=ON
cmake --build build
```

3. テストを実行します：

```bash
cd build && ctest -C Debug --output-on-failure
```

4. サニタイザー付きビルドで品質を確認します：

```bash
cmake -B build -DASAN=ON    # AddressSanitizer
cmake -B build -DTSAN=ON    # ThreadSanitizer
```

**注意点・Tips**:
- コード規約はGoogle C/C++スタイルガイドに準拠（2スペースインデント、行幅80文字）
- 公開APIは `uv_` / `UV_` プレフィックス、内部関数は `uv__` プレフィックスを使用
- CONTRIBUTING.md を事前に確認してください

---

## 5. 【STEP2-3】基本API利用（イベントループ・ハンドル・リクエスト）

> **業務フローでの位置**: 開発者がlibuvの基本概念（イベントループ、ハンドル、リクエスト）を理解し、基本的なAPIの利用を開始するステップです。

### 5.1 イベントループの基本操作

libuvの全ての非同期処理はイベントループ上で動作します。

**主要API一覧：**

| 操作 | API関数 | 説明 |
|------|---------|------|
| 初期化 | `uv_loop_init()` | イベントループを初期化する |
| デフォルトループ取得 | `uv_default_loop()` | デフォルトのイベントループを取得する |
| 実行 | `uv_run()` | イベントループを実行する（DEFAULT/ONCE/NOWAITモード） |
| 停止 | `uv_stop()` | イベントループを停止する |
| 終了 | `uv_loop_close()` | イベントループを終了しリソースを解放する |
| 設定 | `uv_loop_configure()` | ループオプションを設定する |
| 存続確認 | `uv_loop_alive()` | アクティブなハンドル・リクエストの有無を確認する |

**基本的な使い方：**

```c
#include <uv.h>

int main() {
    uv_loop_t *loop = uv_default_loop();

    // ここでハンドルの初期化・登録を行う

    uv_run(loop, UV_RUN_DEFAULT);

    uv_loop_close(loop);
    return 0;
}
```

**イベントループのイテレーション順序：**

1. 内部時刻の更新
2. タイマーコールバックの実行
3. ループの存続判定
4. 保留中のI/Oコールバック実行
5. Idleハンドルコールバック実行
6. Prepareハンドルコールバック実行
7. I/Oポーリングのタイムアウト計算
8. I/Oポーリング（ブロック）
9. Checkハンドルコールバック実行
10. Closeコールバック実行
11. 時刻再更新・タイマー実行
12. イテレーション終了判定

**注意点・Tips**:
- `uv_default_loop()` はシングルスレッドアプリケーションで推奨されます
- マルチスレッドで複数ループを使う場合は `uv_loop_init()` で個別に初期化してください
- イベントループは**スレッドセーフではありません**（明記されている場合を除く）

### 5.2 ハンドルの基本操作

ハンドル（`uv_handle_t`）は長寿命のオブジェクトで、アクティブな間は特定の操作を実行できます。

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

1. `uv_TYPE_init()` でハンドルを初期化する
2. `uv_TYPE_start()` で監視・処理を開始する（一部のハンドル型のみ）
3. 必要に応じて `uv_TYPE_stop()` で停止する
4. `uv_close()` でハンドルをクローズする（**必須**）
5. クローズコールバック内またはその後にメモリを解放する

**主要なハンドル型：**

| ハンドル型 | 用途 |
|-----------|------|
| `uv_tcp_t` | TCPソケット通信 |
| `uv_udp_t` | UDPソケット通信 |
| `uv_pipe_t` | パイプ・IPC通信 |
| `uv_tty_t` | ターミナル制御 |
| `uv_timer_t` | タイマー |
| `uv_signal_t` | シグナル処理 |
| `uv_process_t` | 子プロセス管理 |
| `uv_fs_event_t` | ファイル変更監視 |
| `uv_fs_poll_t` | ファイルポーリング |
| `uv_poll_t` | ファイルディスクリプタ監視 |
| `uv_prepare_t` | I/Oポーリング前コールバック |
| `uv_check_t` | I/Oポーリング後コールバック |
| `uv_idle_t` | アイドル時コールバック |
| `uv_async_t` | スレッド間通知 |

**重要なルール：**
- `uv_foo_init()` が成功したら、必ず `uv_close()` を呼んでください
- ハンドルのメモリは `uv_close_cb` の中またはその後でのみ再利用・解放できます

### 5.3 リクエストの基本操作

リクエスト（`uv_req_t`）は短寿命の操作を表し、通常1回のI/O操作に対応します。

**主要なリクエスト型：**

| リクエスト型 | 用途 |
|-------------|------|
| `uv_write_t` | ストリームへの書き込み |
| `uv_connect_t` | 接続要求 |
| `uv_shutdown_t` | シャットダウン要求 |
| `uv_udp_send_t` | UDPデータグラム送信 |
| `uv_fs_t` | ファイルシステム操作 |
| `uv_work_t` | スレッドプールワーク |
| `uv_getaddrinfo_t` | DNS正引き |
| `uv_getnameinfo_t` | DNS逆引き |

**注意点・Tips**:
- リクエストは完了時またはキャンセル時に自動的にクローズされます
- `uv_fs_t` は使用後に `uv_fs_req_cleanup()` を呼ぶ必要があります
- `uv_getaddrinfo_t` は使用後に `uv_freeaddrinfo()` を呼ぶ必要があります

### 5.4 タイマーの利用

**基本的なタイマーの使い方：**

```c
uv_timer_t timer;
uv_timer_init(uv_default_loop(), &timer);

// 1000ms後に発火、500ms間隔でリピート
uv_timer_start(&timer, timer_callback, 1000, 500);

// タイマーの停止
uv_timer_stop(&timer);
uv_close((uv_handle_t*)&timer, NULL);
```

---

## 6. 【STEP3-4】ネットワーク・ファイルI/O（TCP/UDP/ファイル操作）

> **業務フローでの位置**: 開発者がネットワーク通信やファイル操作のAPIをアプリケーションに組み込み、動作を検証するステップです。

### 6.1 TCPサーバーの構築

**業務シーン**: TCPベースのサーバーアプリケーションを作成したい

**操作手順：**

1. `uv_tcp_init()` でTCPハンドルを初期化します
2. `uv_ip4_addr()` または `uv_ip6_addr()` でアドレスを変換します
3. `uv_tcp_bind()` でソケットをバインドします
4. `uv_listen()` で接続待ち受けを開始します
5. 接続コールバック内で `uv_accept()` を呼び出します
6. `uv_read_start()` でデータの読み取りを開始します
7. `uv_write()` でデータを書き込みます

**TCPサーバーのオプション設定：**

| オプション | API関数 | 説明 |
|-----------|---------|------|
| Nagle無効化 | `uv_tcp_nodelay()` | 低遅延通信のためNagleアルゴリズムを無効化 |
| キープアライブ | `uv_tcp_keepalive()` | 接続の生存確認を有効化 |
| 同時接続受入 | `uv_tcp_simultaneous_accepts()` | 複数接続の同時受入を制御 |
| ポート再利用 | `uv_tcp_bind()` + `UV_TCP_REUSEPORT` | ポートの再利用を有効化 |

### 6.2 TCPクライアントの構築

**業務シーン**: TCPベースのクライアントアプリケーションを作成したい

**操作手順：**

1. `uv_tcp_init()` でTCPハンドルを初期化します
2. `uv_tcp_connect()` で非同期接続を開始します
3. 接続コールバック内で `uv_read_start()` と `uv_write()` を使用します

### 6.3 UDP通信の実装

**業務シーン**: UDPベースのデータ送受信を行いたい

**操作手順：**

1. `uv_udp_init()` でUDPハンドルを初期化します
2. `uv_udp_bind()` でソケットをバインドします
3. `uv_udp_recv_start()` で受信を開始します
4. `uv_udp_send()` でデータグラムを送信します

**マルチキャスト対応：**

| 操作 | API関数 |
|------|---------|
| グループ参加 | `uv_udp_set_membership()` |
| ソースSSMグループ参加 | `uv_udp_set_source_membership()` |
| マルチキャストループ制御 | `uv_udp_set_multicast_loop()` |
| マルチキャストTTL設定 | `uv_udp_set_multicast_ttl()` |
| ブロードキャスト有効化 | `uv_udp_set_broadcast()` |

### 6.4 パイプ・IPCの利用

**業務シーン**: プロセス間通信（IPC）を行いたい

**操作手順：**

1. `uv_pipe_init()` でパイプハンドルを初期化します（IPC=1でファイルディスクリプタの受け渡し対応）
2. サーバー側は `uv_pipe_bind()` → `uv_listen()` → `uv_accept()`
3. クライアント側は `uv_pipe_connect()` で接続します
4. `uv_write2()` でハンドルの受け渡しが可能です

### 6.5 非同期ファイル操作

**業務シーン**: ファイルの読み書き・管理を非同期で行いたい

**主要な操作と対応API：**

| 操作 | API関数 | 説明 |
|------|---------|------|
| ファイルオープン | `uv_fs_open()` | ファイルを非同期でオープン |
| ファイル読み取り | `uv_fs_read()` | ファイルを非同期で読み取り |
| ファイル書き込み | `uv_fs_write()` | ファイルを非同期で書き込み |
| ファイルクローズ | `uv_fs_close()` | ファイルを非同期でクローズ |
| ファイルコピー | `uv_fs_copyfile()` | ファイルを非同期でコピー |
| ファイル削除 | `uv_fs_unlink()` | ファイルを非同期で削除 |
| ファイル情報取得 | `uv_fs_stat()` | ファイルのステータス情報を取得 |
| ディレクトリ作成 | `uv_fs_mkdir()` | ディレクトリを非同期で作成 |
| ディレクトリ走査 | `uv_fs_scandir()` | ディレクトリ内容を走査 |

**注意点・Tips**:
- ファイルI/Oはスレッドプール上で実行されます（ネットワークI/Oと異なり、プラットフォーム固有の非同期APIがないため）
- `uv_fs_t` リクエスト使用後は必ず `uv_fs_req_cleanup()` を呼んでください
- コールバックにNULLを渡すと同期的に実行されます

### 6.6 ファイル変更の監視

**業務シーン**: ファイルやディレクトリの変更を検知したい

**2つの方式：**

| 方式 | ハンドル | 特徴 |
|------|---------|------|
| FSイベント | `uv_fs_event_t` | OS固有の通知機構（inotify/fsevents）を利用。高速だがプラットフォーム差あり |
| FSポーリング | `uv_fs_poll_t` | stat()による定期ポーリング。クロスプラットフォームで安定動作 |

---

## 7. 【STEP4-5】応用機能・パフォーマンス確認（スレッド・プロセス・メトリクス）

> **業務フローでの位置**: 開発者がスレッド・プロセス管理等の応用機能を利用し、アプリケーションのパフォーマンスを確認・最適化するステップです。

### 7.1 スレッドプールの活用

**業務シーン**: CPU集約的な処理を非同期で実行したい

**操作手順：**

1. `uv_queue_work()` でワークをスレッドプールに投入します
2. ワーク関数（スレッドプール上で実行される）とコールバック関数（イベントループスレッドで実行される）を指定します

```c
uv_work_t req;
req.data = /* ユーザーデータ */;
uv_queue_work(loop, &req, work_fn, after_work_fn);
```

**注意点・Tips**:
- デフォルトのスレッドプールサイズは4です。環境変数 `UV_THREADPOOL_SIZE` で変更できます（最大1024）
- ファイルI/O、DNS解決もスレッドプールを共有するため、プールサイズの調整を検討してください

### 7.2 スレッドと同期プリミティブ

**業務シーン**: マルチスレッドプログラミングを行いたい

**利用可能な同期プリミティブ：**

| プリミティブ | API | 説明 |
|-------------|-----|------|
| ミューテックス | `uv_mutex_*()` | 排他的ロック |
| 読み書きロック | `uv_rwlock_*()` | 読み取り共有・書き込み排他 |
| セマフォ | `uv_sem_*()` | カウンティングセマフォ |
| 条件変数 | `uv_cond_*()` | 条件待ち合わせ |
| バリア | `uv_barrier_*()` | スレッド同期バリア |
| ワンスガード | `uv_once()` | 一度だけ実行を保証 |
| TLS | `uv_key_*()` | スレッドローカルストレージ |

### 7.3 子プロセスの管理

**業務シーン**: 外部プログラムを子プロセスとして実行したい

**操作手順：**

1. `uv_process_options_t` 構造体でプロセスの設定を行います
2. `uv_spawn()` で子プロセスを生成します
3. 終了コールバックでプロセスの終了を検知します
4. 必要に応じて `uv_process_kill()` でシグナルを送信します

**設定可能なオプション：**
- 実行ファイルパスと引数
- 環境変数
- 作業ディレクトリ
- 標準入出力のリダイレクト（パイプ、ファイル、継承）
- UID/GID（UNIX系）

### 7.4 シグナルハンドリング

**業務シーン**: UNIXシグナル（SIGINT、SIGTERM等）を適切に処理したい

**操作手順：**

1. `uv_signal_init()` でシグナルハンドルを初期化します
2. `uv_signal_start()` でシグナルの監視を開始します
3. コールバック内でシグナルに応じた処理を実行します
4. `uv_signal_start_oneshot()` で一度だけシグナルを受信することもできます

### 7.5 DNS解決

**業務シーン**: ホスト名からIPアドレスを非同期で解決したい

**操作手順：**

1. `uv_getaddrinfo()` で非同期DNS正引きを行います
2. コールバック内で `struct addrinfo` を受け取り処理します
3. 使用後は `uv_freeaddrinfo()` でメモリを解放します
4. 逆引きは `uv_getnameinfo()` を使用します

### 7.6 メトリクスによるパフォーマンス確認

**業務シーン**: イベントループのパフォーマンスを計測したい

**操作手順：**

1. `uv_loop_configure()` で `UV_METRICS_IDLE_TIME` を有効にします
2. `uv_metrics_info()` でメトリクス情報を取得します
3. `uv_metrics_idle_time()` でイベントループのアイドル時間を確認します

### 7.7 テスト実行（コントリビュータ向け）

**操作手順：**

```bash
# 全テスト実行
cd build && ctest -C Debug --output-on-failure

# 直接テストランナーを実行
build/uv_run_tests_a

# 特定テストの実行
build/uv_run_tests_a TEST_NAME

# タイムアウト倍率の調整
UV_TEST_TIMEOUT_MULTIPLIER=2 build/uv_run_tests

# ベンチマーク実行
build/uv_run_benchmarks_a
```

---

## 8. エラーハンドリング

### 8.1 エラーコードの基本

libuvのエラーコードは `UV_E*` 定数として定義されています（170以上のエラーコード）。

**エラー処理の基本ルール：**
- 初期化関数や同期関数はエラー時に負の値を返します
- 非同期関数はコールバックの `status` パラメータでエラーを通知します
- I/O読み取りコールバックでは `nread < 0` がエラーを示します（`UV_EOF` はファイル終端）

### 8.2 エラー情報の取得

| 操作 | API関数 | 説明 |
|------|---------|------|
| エラーメッセージ取得 | `uv_strerror()` / `uv_strerror_r()` | エラーコードから説明文字列を取得 |
| エラー名取得 | `uv_err_name()` / `uv_err_name_r()` | エラーコードから名前文字列を取得 |
| システムエラー変換 | `uv_translate_sys_error()` | OSエラーコードをlibuvエラーに変換 |

### 8.3 よく使うエラーコード

| エラーコード | 説明 |
|-------------|------|
| `UV_EOF` | ストリームの終端に到達 |
| `UV_ECONNREFUSED` | 接続が拒否された |
| `UV_ECONNRESET` | 接続がリセットされた |
| `UV_ETIMEDOUT` | 操作がタイムアウト |
| `UV_EADDRINUSE` | アドレスが既に使用中 |
| `UV_ENOENT` | ファイルまたはディレクトリが存在しない |
| `UV_EACCES` | パーミッションが不足 |
| `UV_ENOMEM` | メモリ不足 |
| `UV_EAGAIN` | リソースが一時的に利用不可 |
| `UV_ECANCELED` | 操作がキャンセルされた |

---

## 9. ドキュメントサイトの活用

### 9.1 APIリファレンスの参照方法

APIリファレンスは「APIドキュメント一覧」（api.rst）から各カテゴリにアクセスできます。

**カテゴリ一覧：**

| カテゴリ | ドキュメント | 対応機能数 |
|---------|------------|-----------|
| エラーコード | errors.rst | 3機能 |
| バージョン情報 | version.rst | 1機能 |
| イベントループ | loop.rst | 13機能 |
| ハンドル基底 | handle.rst | 12機能 |
| リクエスト基底 | request.rst | 4機能 |
| タイマー | timer.rst | 6機能 |
| Prepare/Check/Idle | prepare.rst, check.rst, idle.rst | 各1機能 |
| Async | async.rst | 2機能 |
| Poll | poll.rst | 2機能 |
| シグナル | signal.rst | 3機能 |
| プロセス | process.rst | 3機能 |
| ストリーム | stream.rst | 9機能 |
| TCP | tcp.rst | 9機能 |
| パイプ | pipe.rst | 10機能 |
| TTY | tty.rst | 5機能 |
| UDP | udp.rst | 14機能 |
| ファイルシステムイベント | fs_event.rst | 3機能 |
| ファイルシステムポーリング | fs_poll.rst | 3機能 |
| ファイルシステム操作 | fs.rst | 19機能 |
| スレッドプール | threadpool.rst | 1機能 |
| DNS | dns.rst | 3機能 |
| 共有ライブラリ | dll.rst | 3機能 |
| スレッド | threading.rst | 14機能 |
| その他ユーティリティ | misc.rst | 43機能 |
| メトリクス | metrics.rst | 2機能 |

### 9.2 ユーザーガイドの活用

実践的な使い方を学ぶには「ユーザーガイド一覧」（guide.rst）を参照してください。

| ガイド | 内容 | 推奨対象 |
|-------|------|---------|
| イントロダクション | libuvの背景と概要 | 全ユーザー |
| 基本事項 | イベントループ・ハンドル・リクエストの基本 | 初心者 |
| ファイルシステム | ファイルI/O操作のサンプル | ファイル操作を行う開発者 |
| ネットワーク | TCP/UDPプログラミングのサンプル | ネットワーク開発者 |
| スレッド | スレッドプール・同期プリミティブ | 並行処理開発者 |
| プロセス | 子プロセス・シグナル処理 | プロセス管理を行う開発者 |
| イベントループ応用 | 複数ループ・他ライブラリ統合 | 上級者 |
| ユーティリティ | タイマー・アイドル等のユーティリティ | 全開発者 |

---

## 10. ユーティリティ機能

### 10.1 システム情報取得

| 操作 | API関数 |
|------|---------|
| CPU情報取得 | `uv_cpu_info()` |
| メモリ情報取得 | `uv_get_free_memory()` / `uv_get_total_memory()` |
| ネットワークインターフェース一覧 | `uv_interface_addresses()` |
| OS情報取得 | `uv_os_uname()` |
| ホスト名取得 | `uv_os_gethostname()` |
| システム稼働時間 | `uv_uptime()` |
| ロードアベレージ | `uv_loadavg()` |

### 10.2 環境変数操作

| 操作 | API関数 |
|------|---------|
| 全環境変数取得 | `uv_os_environ()` |
| 個別取得 | `uv_os_getenv()` |
| 設定 | `uv_os_setenv()` |
| 削除 | `uv_os_unsetenv()` |

### 10.3 時刻・タイミング

| 操作 | API関数 | 精度 |
|------|---------|------|
| 高精度時刻 | `uv_hrtime()` | ナノ秒 |
| クロック時刻 | `uv_clock_gettime()` | ナノ秒（MONOTONIC/REALTIME） |
| 現在時刻 | `uv_gettimeofday()` | マイクロ秒 |
| スリープ | `uv_sleep()` | ミリ秒 |

### 10.4 動的ライブラリ

| 操作 | API関数 |
|------|---------|
| ライブラリ読み込み | `uv_dlopen()` |
| シンボル検索 | `uv_dlsym()` |
| ライブラリ解放 | `uv_dlclose()` |
| エラー取得 | `uv_dlerror()` |

### 10.5 その他のユーティリティ

| 操作 | API関数 |
|------|---------|
| IPアドレス変換 | `uv_ip4_addr()` / `uv_ip6_addr()` |
| IPアドレス文字列化 | `uv_ip4_name()` / `uv_ip6_name()` |
| バージョン取得 | `uv_version()` / `uv_version_string()` |
| カスタムアロケータ | `uv_replace_allocator()` |
| ライブラリシャットダウン | `uv_library_shutdown()` |
| 乱数生成 | `uv_random()` |
| バッファ初期化 | `uv_buf_init()` |
| 文字コード変換 | `uv_utf16_to_wtf8()` / `uv_wtf8_to_utf16()` |

---

## 11. 日常業務の流れ

本セクションでは、業務フローに沿った日常業務の流れを説明します。

```
開発業務フロー概要（再掲）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【STEP 1】開発者がlibuv環境を構築（ビルド・インストール） → 4章参照
    ↓
【STEP 2】イベントループ・ハンドル・リクエストの基本を理解 → 5章参照
    ↓
【STEP 3】アプリケーションにAPI（ネットワーク/ファイルI/O等）を組込 → 6章参照
    ↓
【STEP 4】テスト・デバッグ・パフォーマンス確認 → 7章参照
    ↓
【STEP 5】本番環境へのデプロイ・運用 → 7章参照
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### 11.1 【利用開発者】STEP1: 環境構築

開発開始時に、libuvのビルド・インストールを行います。

1. プラットフォームに応じたコンパイラとCMakeをインストールします
2. libuvをソースコードまたはパッケージマネージャからインストールします（[2章](#2-インストールセットアップ手順)参照）
3. テストプログラムをコンパイルして動作確認します
4. プロジェクトのビルドシステムにlibuvの依存を追加します

### 11.2 【利用開発者】STEP2: 基本概念の理解

libuvの基本概念を理解します。

1. ドキュメントサイトの「設計概要」ページを確認します
2. ユーザーガイドの「基本事項」を読んで、Hello Worldプログラムを作成します
3. イベントループの動作原理を理解します（[5章](#5-step2-3基本api利用イベントループハンドルリクエスト)参照）
4. ハンドルとリクエストのライフサイクルルールを確認します

### 11.3 【利用開発者】STEP3: API組込

要件に応じてAPIをアプリケーションに組み込みます。

1. ユーザーガイドの該当章を参考にサンプルコードを試します
2. APIリファレンスで詳細な仕様を確認します
3. アプリケーションにAPIを組み込み、コンパイル・リンクします
4. 単体テストを作成して動作を検証します

### 11.4 【利用開発者】STEP4-5: テスト・デプロイ・運用

アプリケーションのテスト・最適化を行い、本番環境にデプロイします。

1. サニタイザー付きビルドでメモリリークやデータ競合を検出します
2. メトリクスAPIでイベントループのパフォーマンスを確認します
3. `UV_THREADPOOL_SIZE` 等の環境変数で性能を調整します
4. 本番環境にデプロイし、エラーログを監視します

---

## 12. よくある質問と対処法

### 12.1 ビルド・インストールに関するQ&A

**Q: CMakeビルドで `libuv not found` エラーが出ます**

A: 以下を確認してください：
- libuvがシステムにインストールされているか確認します（`pkg-config --libs libuv`）
- CMakeの `CMAKE_PREFIX_PATH` にlibuvのインストール先を指定します
- パッケージマネージャでインストールした場合は、開発パッケージ（`-dev` / `-devel`）もインストールされているか確認します

**Q: Windowsでビルドエラーが発生します**

A: 以下を確認してください：
- MSVC 2017以上を使用しているか確認します
- 共有ライブラリを使用する場合は `USING_UV_SHARED` マクロを定義します
- `BUILDING_UV_SHARED` と `USING_UV_SHARED` を同時に定義していないか確認します

### 12.2 イベントループに関するQ&A

**Q: イベントループがすぐに終了してしまいます**

A: イベントループはアクティブなハンドルまたはリクエストがない場合、即座に終了します。ハンドルを初期化して `start` 関数を呼んでいるか確認してください。

**Q: イベントループが終了しません**

A: 全てのハンドルが `uv_close()` でクローズされているか確認してください。`uv_print_all_handles()` を使って残っているハンドルを調査できます。

**Q: マルチスレッドでイベントループを使いたいです**

A: イベントループはスレッドセーフではありません。スレッドごとに別々のイベントループを作成してください。スレッド間通知には `uv_async_t` を使用します。

### 12.3 ファイルI/Oに関するQ&A

**Q: ファイル操作が遅いです**

A: ファイルI/Oはスレッドプールで実行されます。デフォルトのプールサイズは4です。環境変数 `UV_THREADPOOL_SIZE` でプールサイズを増やすことを検討してください（最大1024）。

---

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

### 13.1 エラーメッセージと対処法

| エラー/症状 | 原因 | 対処法 |
|------------|------|--------|
| `UV_EADDRINUSE` | ポートが既に使用中 | 別のポートを使用するか、`SO_REUSEADDR` / `UV_TCP_REUSEPORT` を設定する |
| `UV_ECONNREFUSED` | 接続先がリスンしていない | サーバーが起動しているか、ポート番号が正しいか確認する |
| `UV_EACCES` | パーミッション不足 | 特権ポート（1024未満）を使用している場合はroot権限で実行するか、別のポートを使用する |
| `UV_ENOENT` | ファイルが見つからない | パスが正しいか、ファイルが存在するか確認する |
| `UV_ENOMEM` | メモリ不足 | メモリリークがないか確認する。`uv_fs_req_cleanup()` や `uv_close()` の呼び忘れがないか確認する |
| メモリリーク | ハンドル/リクエストの未解放 | AddressSanitizer（`-DASAN=ON`）でビルドして検出する。`uv_close()` と `uv_fs_req_cleanup()` の呼び出しを確認する |
| データ競合 | スレッド間の不正なデータアクセス | ThreadSanitizer（`-DTSAN=ON`）でビルドして検出する。同期プリミティブを使用する |
| イベントループのハング | 同期処理がイベントループをブロック | CPU集約的な処理は `uv_queue_work()` でスレッドプールに移す |

### 13.2 デバッグ手法

**ハンドルのデバッグ：**
- `uv_print_all_handles(loop, stderr)`: 全ハンドルの情報を出力
- `uv_print_active_handles(loop, stderr)`: アクティブなハンドルのみ出力

**サニタイザーによる品質チェック：**

| サニタイザー | CMakeフラグ | 検出対象 |
|-------------|------------|---------|
| AddressSanitizer | `-DASAN=ON` | メモリリーク、バッファオーバーフロー、use-after-free |
| ThreadSanitizer | `-DTSAN=ON` | データ競合、デッドロック |
| UndefinedBehaviorSanitizer | `-DUBSAN=ON` | 未定義動作 |
| MemorySanitizer | `-DMSAN=ON` | 未初期化メモリの使用 |

### 13.3 サポートへの連絡方法

- **GitHubイシュー**: バグ報告・機能要望は [GitHub Issues](https://github.com/libuv/libuv/issues) に投稿してください
- **メーリングリスト**: libuv開発者コミュニティへの問い合わせ
- **ドキュメントの誤り**: ドキュメントの誤りはプルリクエストで修正を提案できます

---

## 改訂履歴

| 版数 | 改訂日 | 改訂内容 |
|-----|--------|---------|
| 1.0 | 2026-02-22 | 初版作成 |

---

*本マニュアルは、libuvのエンドユーザー（開発者）向け業務運用マニュアルです。*
*ライブラリの更新により、APIや動作が変更される場合があります。*
