# 画面設計書 21-UDP

## 概要

本ドキュメントは、libuvドキュメントサイトにおけるUDP（`uv_udp_t`）APIリファレンスページの画面設計書である。UDPハンドルを使ったデータグラム通信に関するAPI定義、データ型、列挙型、コールバック仕様を網羅的に記載する。

### 本画面の処理概要

本ページは、libuvにおけるUDPソケット通信機能の全APIリファレンスを提供するドキュメントページである。クライアント・サーバー双方のUDP通信を包括的にカバーし、開発者がUDPデータグラムの送受信を実装する際に必要となるすべてのAPI情報を提示する。

**業務上の目的・背景**：UDPはTCPと異なりコネクションレスな通信プロトコルであり、低遅延が求められるアプリケーション（DNS、ストリーミング、ゲーム通信など）で広く使用される。libuvはクロスプラットフォームでUDP通信を抽象化するAPIを提供しており、本ページはその完全なリファレンスとして、開発者がUDP関連機能を正しく使用するために不可欠なドキュメントである。

**画面へのアクセス方法**：トップページ（index.rst）からAPIドキュメント一覧（api.rst）を経由し、UDPリンクをクリックして本ページに遷移する。直接URL指定でもアクセス可能である。

**主要な操作・処理内容**：
1. UDPハンドルの初期化（`uv_udp_init` / `uv_udp_init_ex`）のAPI仕様確認
2. UDPソケットのバインド（`uv_udp_bind`）と接続（`uv_udp_connect`）のAPI仕様確認
3. データグラム送信（`uv_udp_send` / `uv_udp_try_send` / `uv_udp_try_send2`）のAPI仕様確認
4. データグラム受信（`uv_udp_recv_start` / `uv_udp_recv_stop`）のAPI仕様確認
5. マルチキャスト制御（メンバーシップ設定、ループ、TTL、インターフェース）のAPI仕様確認
6. ブロードキャスト設定、TTL設定のAPI仕様確認
7. 送信キュー情報取得のAPI仕様確認
8. アドレス取得（`uv_udp_getsockname` / `uv_udp_getpeername`）のAPI仕様確認

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：ハンドル基底（handle.rst）へのseealsoリンク
- 関連ページ：ネットワークガイド（guide/networking.rst）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 48 | UDP初期化 | 主機能 | uv_udp_init()/uv_udp_init_ex()によるUDPハンドル初期化のAPI定義 |
| 49 | UDPバインド | 主機能 | uv_udp_bind()によるUDPソケットバインドのAPI定義 |
| 50 | UDP接続 | 主機能 | uv_udp_connect()によるUDPリモートアドレス接続のAPI定義 |
| 51 | UDP既存ソケットオープン | 主機能 | uv_udp_open()/uv_udp_open_ex()による既存OSソケット関連付けのAPI定義 |
| 52 | UDP送信 | 主機能 | uv_udp_send()による非同期UDPデータグラム送信のAPI定義 |
| 53 | UDP同期送信試行 | 主機能 | uv_udp_try_send()/uv_udp_try_send2()による同期的UDP送信試行のAPI定義 |
| 54 | UDP受信開始・停止 | 主機能 | uv_udp_recv_start()/uv_udp_recv_stop()によるUDP受信制御のAPI定義 |
| 55 | UDPアドレス取得 | 主機能 | uv_udp_getsockname()/uv_udp_getpeername()によるアドレス取得のAPI定義 |
| 56 | マルチキャスト制御 | 主機能 | uv_udp_set_membership()/uv_udp_set_source_membership()によるマルチキャスト制御のAPI定義 |
| 57 | マルチキャストオプション設定 | 主機能 | uv_udp_set_multicast_loop()/ttl()/interface()によるマルチキャスト設定のAPI定義 |
| 58 | ブロードキャスト設定 | 主機能 | uv_udp_set_broadcast()によるブロードキャスト有効・無効のAPI定義 |
| 59 | UDP TTL設定 | 主機能 | uv_udp_set_ttl()によるUDPパケットTTL設定のAPI定義 |
| 60 | UDP送信キュー情報取得 | 主機能 | uv_udp_get_send_queue_size()/count()による送信キュー情報取得のAPI定義 |
| 61 | recvmmsg使用判定 | 主機能 | uv_udp_using_recvmmsg()によるrecvmmsg使用状態判定のAPI定義 |

## 画面種別

APIリファレンス（詳細表示）

## URL/ルーティング

`/docs/src/udp.rst` (Sphinx生成後: `/udp.html`)

## 入出力項目

本ページはAPIリファレンスドキュメントであり、ユーザー入力項目は存在しない。以下はAPIとして定義される入出力パラメータの一覧である。

| API関数 | パラメータ名 | 型 | 入出力 | 説明 |
|---------|-------------|-----|--------|------|
| uv_udp_init | loop | uv_loop_t* | 入力 | イベントループ |
| uv_udp_init | handle | uv_udp_t* | 出力 | 初期化されるUDPハンドル |
| uv_udp_init_ex | flags | unsigned int | 入力 | ソケットドメイン・フラグ |
| uv_udp_bind | addr | const struct sockaddr* | 入力 | バインドするアドレスとポート |
| uv_udp_bind | flags | unsigned int | 入力 | UV_UDP_IPV6ONLY等のフラグ |
| uv_udp_connect | addr | const struct sockaddr* | 入力 | リモートアドレス（NULLで切断） |
| uv_udp_send | bufs | const uv_buf_t[] | 入力 | 送信バッファ配列 |
| uv_udp_send | nbufs | unsigned int | 入力 | バッファ数 |
| uv_udp_send | addr | const struct sockaddr* | 入力 | 送信先アドレス |
| uv_udp_send | send_cb | uv_udp_send_cb | 入力 | 送信完了コールバック |
| uv_udp_recv_start | alloc_cb | uv_alloc_cb | 入力 | バッファ割り当てコールバック |
| uv_udp_recv_start | recv_cb | uv_udp_recv_cb | 入力 | 受信コールバック |
| uv_udp_getsockname | name | struct sockaddr* | 出力 | ローカルアドレス情報 |
| uv_udp_getpeername | name | struct sockaddr* | 出力 | リモートアドレス情報 |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | `uv_udp_t` --- UDP handle | ページタイトル |
| 概要説明 | UDP handles encapsulate... | UDPハンドルの概要 |
| Data types | uv_udp_t, uv_udp_send_t, uv_udp_flags等 | データ型・列挙型の定義 |
| コールバック型 | uv_udp_send_cb, uv_udp_recv_cb | コールバック関数型の定義 |
| Public members | send_queue_size, send_queue_count, handle | 公開メンバーフィールド |
| API | 全20関数 | 初期化・バインド・接続・送受信・マルチキャスト等の全API |
| seealso | uv_handle_t API参照 | 基底ハンドルAPIへの参照 |

## イベント仕様

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

ページ内の各セクション（Data types、Public members、API）へのアンカーリンクによるスクロール遷移。Sphinxが自動生成するリンクIDに基づく。

### 2-seealsoリンク遷移

ページ末尾の「See also」セクションから `uv_handle_t` の基底APIリファレンスページ（handle.rst）へ遷移する。

### 3-バージョン注記表示

各API関数に付与された `versionadded` / `versionchanged` ディレクティブにより、APIの追加・変更バージョンが注記として表示される。

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

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

該当なし（本プロジェクトはCライブラリであり、データベースは使用しない）

## メッセージ仕様

| メッセージ種別 | 条件 | 内容 |
|--------------|------|------|
| note | recvmmsg使用時 | recvmmsg使用時のバッファサイズ制約に関する注意 |
| note | 受信コールバック | nread==0かつaddr==NULLの場合の動作説明 |
| note | UV_UDP_REUSEPORT | プラットフォーム対応状況（Linux 3.9+等）に関する注意 |
| versionadded | 各API | 各APIが追加されたlibuvバージョン |
| versionchanged | 各API | 各APIが変更されたlibuvバージョン |

## 例外処理

| エラーコード | 発生条件 | 説明 |
|-------------|---------|------|
| UV_EISCONN | 接続済みハンドルで再接続試行時 | uv_udp_connect()で既に接続済みの場合 |
| UV_ENOTCONN | 未接続ハンドルで切断試行時 | uv_udp_connect(NULL)で未接続の場合 |
| UV_EDESTADDRREQ | 未接続ハンドルでaddr=NULL送信時 | uv_udp_send()でアドレス未指定 |
| UV_EAGAIN | 即座に送信不可時 | uv_udp_try_send()で送信バッファフル |
| UV_ENOTSUP | 非対応プラットフォームでREUSEPORT使用時 | uv_udp_bind()でUV_UDP_REUSEPORT指定 |
| UV_ENOBUFS | バッファサイズ不足時 | uv_udp_getsockname()等でバッファ不足 |

## 備考

- UDPハンドルはクライアント・サーバー双方のUDP通信をカプセル化する
- uv_udp_init()では実際のソケットは遅延作成される（初期化時にはソケットを作成しない）
- recvmmsg(2)のサポートはv1.37.0以降で明示的にUV_UDP_RECVMMSGフラグを指定する必要がある
- UV_UDP_MMSG_FREEフラグはv1.40.0で追加された
- uv_udp_try_send2()はsendmmsg(2)の軽量抽象化であり、v1.50.0で追加された
- 接続済みUDPハンドルではsend時にaddrをNULLにする必要がある

---

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

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

### 推奨読解順序

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

まず、UDPハンドルに関連するデータ構造と列挙型を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_udp_t, uv_udp_send_t, uv_udp_flags, uv_membership等の定義 |
| 1-2 | uv/unix.h | `include/uv/unix.h` | Unix系でのuv_udp_tプラットフォーム固有メンバー |
| 1-3 | uv/win.h | `include/uv/win.h` | Windows系でのuv_udp_tプラットフォーム固有メンバー |

**読解のコツ**: uv.hではUV_HANDLE_FIELDSマクロとUV_UDP_PRIVATE_FIELDSマクロにより構造体が構成されている。プラットフォーム固有部分はunix.h/win.hで定義される。

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

共通初期化処理の起点となるファイルを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv-common.c | `src/uv-common.c` | uv_udp_init()の実装（uv_udp_init_exへの委譲、370行目付近） |

**主要処理フロー**:
1. **370行目**: `uv_udp_init()` が `uv_udp_init_ex(loop, handle, AF_UNSPEC)` を呼び出す
2. 以降、プラットフォーム固有の初期化処理に分岐する

#### Step 3: Unix系プラットフォーム実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | udp.c | `src/unix/udp.c` | Unix系でのUDP実装全体（init_ex, bind, send, recv等） |
| 3-2 | core.c | `src/unix/core.c` | uv_udp_tのクローズ処理等の共通処理 |
| 3-3 | stream.c | `src/unix/stream.c` | ストリーム系の共通基盤処理 |

**主要処理フロー**:
- `uv__udp_init_ex()`: ソケット作成とハンドル初期化
- `uv__udp_bind()`: sockaddrへのバインド処理
- `uv__udp_send()`: sendmsg(2)による非同期送信
- `uv__udp_recv_start()`: イベントループへのポーリング登録

#### Step 4: Windows系プラットフォーム実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | udp.c | `src/win/udp.c` | Windows系でのUDP実装全体 |
| 4-2 | core.c | `src/win/core.c` | Windows共通基盤処理 |
| 4-3 | handle.c | `src/win/handle.c` | Windowsハンドル管理 |

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

```
uv_udp_init() [src/uv-common.c:370]
    |
    +-- uv_udp_init_ex() [src/uv-common.c]
           |
           +-- [Unix] uv__udp_init_ex() [src/unix/udp.c]
           |      +-- uv__handle_init() [マクロ]
           |      +-- socket() [ソケット作成]
           |
           +-- [Win] uv__udp_init_ex() [src/win/udp.c]

uv_udp_bind() [src/uv-common.c]
    +-- [Unix] uv__udp_bind() [src/unix/udp.c]
    +-- [Win] uv_udp_bind() [src/win/udp.c]

uv_udp_send() [src/uv-common.c]
    +-- [Unix] uv__udp_send() [src/unix/udp.c]
    |      +-- sendmsg() / sendmmsg()
    +-- [Win] uv_udp_send() [src/win/udp.c]
           +-- WSASendTo()

uv_udp_recv_start() [src/uv-common.c]
    +-- [Unix] uv__udp_recv_start() [src/unix/udp.c]
    |      +-- uv__io_start() [ポーリング登録]
    +-- [Win] uv_udp_recv_start() [src/win/udp.c]
```

### データフロー図

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

アプリケーション          uv_udp_init()                  初期化済みUDPハンドル
コード                        |
                              v
送信データ(uv_buf_t) --> uv_udp_send()              --> OSソケット経由で
                              |                          ネットワーク送信
                              v
                         sendmsg(2)/WSASendTo()

                         uv_udp_recv_start()         --> uv_udp_recv_cbコールバック
                              |                          で受信データ通知
                              v
ネットワーク受信データ   recvmsg(2)/recvmmsg(2)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| udp.rst | `docs/src/udp.rst` | テンプレート | UDPページのSphinxソース |
| uv.h | `include/uv.h` | ソース | uv_udp_t等の公開API定義 |
| uv-common.c | `src/uv-common.c` | ソース | プラットフォーム共通のUDP初期化処理 |
| udp.c (Unix) | `src/unix/udp.c` | ソース | Unix系UDPハンドル実装 |
| udp.c (Win) | `src/win/udp.c` | ソース | Windows系UDPハンドル実装 |
| core.c (Unix) | `src/unix/core.c` | ソース | Unix共通基盤（ハンドルクローズ等） |
| core.c (Win) | `src/win/core.c` | ソース | Windows共通基盤 |
| handle.c (Win) | `src/win/handle.c` | ソース | Windowsハンドル管理 |
| stream.c (Unix) | `src/unix/stream.c` | ソース | ストリーム基盤処理 |
| api.rst | `docs/src/api.rst` | テンプレート | API一覧ページ（遷移元） |
| handle.rst | `docs/src/handle.rst` | テンプレート | ハンドル基底ページ（参照先） |
