# データベース設計書

## 概要

本ドキュメントは、libuv（バージョン1.x）プロジェクトにおける内部データ構造の設計を記述するものである。

libuvはC言語で実装されたクロスプラットフォーム非同期I/Oライブラリであり、SQLデータベースやNoSQLデータベースのような外部永続化ストレージは使用していない。しかし、libuvの内部にはイベントループを中核とした複数のインメモリデータ構造（キュー、ヒープ、赤黒木等）が存在し、これらがハンドル・リクエストの管理に使用されている。

本設計書では、libuvの主要なデータ構造体を「テーブル」として捉え、各構造体のフィールドを「カラム」として文書化する。これは永続化データベースの設計ではなく、ランタイムにおけるインメモリデータモデルの設計書として位置づけられる。

## テーブル一覧

| テーブル名 | 対応エンティティ | 説明 |
| --- | --- | --- |
| uv_loop_s | イベントループ | libuvの中核。全てのハンドルとリクエストを管理する |
| uv_handle_s | ハンドル（基底） | 全ハンドル型の抽象基底クラス |
| uv_stream_s | ストリーム（基底） | TCP/Pipe/TTYの抽象基底クラス。uv_handle_sを継承 |
| uv_tcp_s | TCPハンドル | TCP接続を表現。uv_stream_sを継承 |
| uv_udp_s | UDPハンドル | UDPソケットを表現。uv_handle_sを継承 |
| uv_pipe_s | パイプハンドル | Unix domain socket / Named Pipeを表現。uv_stream_sを継承 |
| uv_tty_s | TTYハンドル | ターミナルストリームを表現。uv_stream_sを継承 |
| uv_poll_s | Pollハンドル | ファイルディスクリプタのポーリング。uv_handle_sを継承 |
| uv_timer_s | タイマーハンドル | タイマーイベント。uv_handle_sを継承 |
| uv_prepare_s | Prepareハンドル | ループ反復前のコールバック。uv_handle_sを継承 |
| uv_check_s | Checkハンドル | ループ反復後のコールバック。uv_handle_sを継承 |
| uv_idle_s | Idleハンドル | アイドル時コールバック。uv_handle_sを継承 |
| uv_async_s | Asyncハンドル | スレッド間通知。uv_handle_sを継承 |
| uv_process_s | プロセスハンドル | 子プロセス管理。uv_handle_sを継承 |
| uv_fs_event_s | FSイベントハンドル | ファイルシステムイベント監視。uv_handle_sを継承 |
| uv_fs_poll_s | FSポーリングハンドル | ファイルシステムのポーリング監視。uv_handle_sを継承 |
| uv_signal_s | シグナルハンドル | Unixシグナル処理。uv_handle_sを継承 |
| uv_req_s | リクエスト（基底） | 全リクエスト型の抽象基底クラス |
| uv_write_s | 書き込みリクエスト | ストリーム書き込み操作。uv_req_sを継承 |
| uv_connect_s | 接続リクエスト | TCP接続操作。uv_req_sを継承 |
| uv_shutdown_s | シャットダウンリクエスト | ストリームシャットダウン操作。uv_req_sを継承 |
| uv_udp_send_s | UDP送信リクエスト | UDPデータ送信操作。uv_req_sを継承 |
| uv_fs_s | FSリクエスト | ファイルシステム操作。uv_req_sを継承 |
| uv_work_s | ワークリクエスト | スレッドプールジョブ。uv_req_sを継承 |
| uv_getaddrinfo_s | DNS解決リクエスト | アドレス解決操作。uv_req_sを継承 |
| uv_getnameinfo_s | 逆引きDNSリクエスト | 名前解決操作。uv_req_sを継承 |
| uv_random_s | 乱数リクエスト | 乱数生成操作。uv_req_sを継承 |
| heap | バイナリ最小ヒープ | タイマー管理用データ構造 |
| heap_node | ヒープノード | ヒープの各要素 |
| uv__queue | 双方向リンクリスト | ハンドル管理用キューデータ構造 |
| uv__io_s | I/Oウォッチャー | ファイルディスクリプタのI/Oイベント監視（Unix） |
| uv_stat_t | ファイル統計情報 | ファイルのメタデータ |
| uv_statfs_s | ファイルシステム統計 | ファイルシステムの容量情報 |
| uv_cpu_info_s | CPU情報 | CPU情報の格納 |
| uv_interface_address_s | ネットワークIF情報 | ネットワークインタフェース情報 |
| uv_passwd_s | ユーザー情報 | OSユーザーのパスワードエントリ |
| uv_group_s | グループ情報 | OSグループ情報 |
| uv_utsname_s | システム名情報 | OSのuname情報 |
| uv_env_item_s | 環境変数 | 環境変数のキーバリューペア |
| uv_dirent_s | ディレクトリエントリ | ディレクトリ内のファイルエントリ |
| uv_dir_s | ディレクトリ | ディレクトリの読み取りコンテキスト |
| uv_metrics_s | メトリクス | イベントループのメトリクス情報 |
| uv_process_options_s | プロセスオプション | 子プロセス起動時のオプション |
| uv__loop_internal_fields_s | ループ内部フィールド | イベントループの内部管理データ |
| uv__loop_metrics_s | ループメトリクス（内部） | イベントループの内部メトリクスデータ |

## 各テーブル定義

### 1. uv_loop_s（イベントループ）

libuvの中核データ構造。全てのハンドルとリクエストはイベントループに紐づく。イベントループはI/Oポーリング、タイマー管理、コールバック実行のライフサイクルを管理する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| data | void* | YES | ユーザーデータ用汎用ポインタ |
| active_handles | unsigned int | NO | アクティブなハンドルの数 |
| handle_queue | struct uv__queue | NO | 全ハンドルのキュー |
| active_reqs.count | unsigned int | NO | アクティブなリクエストの数 |
| internal_fields | void* | YES | 内部拡張用ストレージ（uv__loop_internal_fields_sへのポインタ） |
| stop_flag | unsigned int | NO | ループ停止フラグ |
| flags | unsigned long | NO | ループフラグ（Unix固有） |
| backend_fd | int | NO | バックエンドのファイルディスクリプタ（epoll/kqueue等） |
| pending_queue | struct uv__queue | NO | 保留中のI/Oコールバックキュー |
| watcher_queue | struct uv__queue | NO | ウォッチャーキュー |
| watchers | uv__io_t** | YES | I/Oウォッチャーの配列 |
| nwatchers | unsigned int | NO | ウォッチャー数 |
| nfds | unsigned int | NO | ファイルディスクリプタ数 |
| wq | struct uv__queue | NO | ワークキュー（スレッドプール連携） |
| wq_mutex | uv_mutex_t | NO | ワークキュー用ミューテックス |
| wq_async | uv_async_t | NO | ワークキュー完了通知用Asyncハンドル |
| cloexec_lock | uv_rwlock_t | NO | close-on-exec設定用ロック |
| closing_handles | uv_handle_t* | YES | クローズ中のハンドルのリンクリスト |
| process_handles | struct uv__queue | NO | プロセスハンドルキュー |
| prepare_handles | struct uv__queue | NO | Prepareハンドルキュー |
| check_handles | struct uv__queue | NO | Checkハンドルキュー |
| idle_handles | struct uv__queue | NO | Idleハンドルキュー |
| async_handles | struct uv__queue | NO | Asyncハンドルキュー |
| async_io_watcher | uv__io_t | NO | Async用I/Oウォッチャー |
| async_wfd | int | NO | Async用書き込みファイルディスクリプタ |
| timer_heap | struct { void* min; unsigned int nelts; } | NO | タイマー管理用バイナリ最小ヒープ |
| timer_counter | uint64_t | NO | タイマーの一意ID生成カウンタ |
| time | uint64_t | NO | 現在のループ時刻（ミリ秒） |
| signal_pipefd | int[2] | NO | シグナル通知用パイプ |
| signal_io_watcher | uv__io_t | NO | シグナル用I/Oウォッチャー |
| child_watcher | uv_signal_t | NO | 子プロセス監視用シグナルハンドル |
| emfile_fd | int | NO | EMFILE対策用予約ファイルディスクリプタ |

### 2. uv_handle_s（ハンドル基底）

全てのハンドル型の抽象基底構造体。全ハンドルはイベントループに所属し、キューで管理される。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| data | void* | YES | ユーザーデータ用汎用ポインタ |
| loop | uv_loop_t* | NO | 所属するイベントループ |
| type | uv_handle_type | NO | ハンドル種別（UV_TCP, UV_TIMER等） |
| close_cb | uv_close_cb | YES | クローズ時コールバック |
| handle_queue | struct uv__queue | NO | ループのハンドルキューへのリンク |
| u.fd | int | NO | ファイルディスクリプタ |
| next_closing | uv_handle_t* | YES | クローズ中リンクリストの次要素（Unix固有） |
| flags | unsigned int | NO | ハンドル状態フラグ（ACTIVE, CLOSING, REF等） |

### 3. uv_stream_s（ストリーム基底）

TCP、パイプ、TTYの共通基底構造体。読み書きのI/O操作と接続管理を提供する。uv_handle_sのフィールドを全て含む。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_handle_sの全フィールド） | - | - | ハンドル基底フィールドを継承 |
| write_queue_size | size_t | NO | 書き込みキューのバイト数 |
| alloc_cb | uv_alloc_cb | YES | バッファ割り当てコールバック |
| read_cb | uv_read_cb | YES | 読み取りコールバック |
| connect_req | uv_connect_t* | YES | 接続リクエスト（Unix固有） |
| shutdown_req | uv_shutdown_t* | YES | シャットダウンリクエスト（Unix固有） |
| io_watcher | uv__io_t | NO | I/Oウォッチャー（Unix固有） |
| write_queue | struct uv__queue | NO | 書き込みリクエストキュー（Unix固有） |
| write_completed_queue | struct uv__queue | NO | 完了済み書き込みキュー（Unix固有） |
| connection_cb | uv_connection_cb | YES | 接続受付コールバック（Unix固有） |
| delayed_error | int | NO | 遅延エラーコード（Unix固有） |
| accepted_fd | int | NO | 受理済みファイルディスクリプタ（Unix固有） |
| queued_fds | void* | YES | キューイングされたFD（Unix固有） |

### 4. uv_tcp_s（TCPハンドル）

TCPストリームまたはTCPサーバーを表現する。uv_stream_sの全フィールドを継承する。Unix環境ではTCP固有のプライベートフィールドは空である。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_stream_sの全フィールド） | - | - | ストリーム基底フィールドを継承 |

### 5. uv_udp_s（UDPハンドル）

UDPソケットを表現する。uv_handle_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_handle_sの全フィールド） | - | - | ハンドル基底フィールドを継承 |
| send_queue_size | size_t | NO | 送信キューのバイト数 |
| send_queue_count | size_t | NO | 送信キュー内のリクエスト数 |
| alloc_cb | uv_alloc_cb | YES | バッファ割り当てコールバック（Unix固有） |
| recv_cb | uv_udp_recv_cb | YES | 受信コールバック（Unix固有） |
| io_watcher | uv__io_t | NO | I/Oウォッチャー（Unix固有） |
| write_queue | struct uv__queue | NO | 書き込みキュー（Unix固有） |
| write_completed_queue | struct uv__queue | NO | 完了済み書き込みキュー（Unix固有） |

### 6. uv_pipe_s（パイプハンドル）

UnixドメインソケットまたはWindowsの名前付きパイプを表現する。uv_stream_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_stream_sの全フィールド） | - | - | ストリーム基底フィールドを継承 |
| ipc | int | NO | IPC用パイプかどうか（非0ならハンドル受け渡し可能） |
| pipe_fname | const char* | YES | パイプのファイル名（Unix固有） |

### 7. uv_tty_s（TTYハンドル）

ターミナルストリームを表現する。uv_stream_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_stream_sの全フィールド） | - | - | ストリーム基底フィールドを継承 |
| orig_termios | struct termios | NO | 元のターミナル設定（Unix固有） |
| mode | int | NO | 現在のTTYモード（Unix固有） |

### 8. uv_poll_s（Pollハンドル）

ファイルディスクリプタのI/Oイベント監視を行う。uv_handle_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_handle_sの全フィールド） | - | - | ハンドル基底フィールドを継承 |
| poll_cb | uv_poll_cb | YES | ポーリングイベントコールバック |
| io_watcher | uv__io_t | NO | I/Oウォッチャー（Unix固有） |

### 9. uv_timer_s（タイマーハンドル）

指定時刻にコールバックを実行するタイマー。uv_handle_sのフィールドを継承する。バイナリ最小ヒープで管理される。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_handle_sの全フィールド） | - | - | ハンドル基底フィールドを継承 |
| timer_cb | uv_timer_cb | YES | タイマー発火時コールバック |
| node.heap | void*[3] | NO | ヒープノード（left, right, parent） |
| timeout | uint64_t | NO | 発火時刻（ミリ秒） |
| repeat | uint64_t | NO | リピート間隔（ミリ秒。0の場合はワンショット） |
| start_id | uint64_t | NO | タイマーの開始ID（同一タイムアウトの順序保証用） |

### 10. uv_prepare_s（Prepareハンドル）

イベントループのI/Oポーリング前にコールバックを実行する。uv_handle_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_handle_sの全フィールド） | - | - | ハンドル基底フィールドを継承 |
| prepare_cb | uv_prepare_cb | YES | Prepare時コールバック（Unix固有） |
| queue | struct uv__queue | NO | Prepareハンドルキュー（Unix固有） |

### 11. uv_check_s（Checkハンドル）

イベントループのI/Oポーリング後にコールバックを実行する。uv_handle_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_handle_sの全フィールド） | - | - | ハンドル基底フィールドを継承 |
| check_cb | uv_check_cb | YES | Check時コールバック（Unix固有） |
| queue | struct uv__queue | NO | Checkハンドルキュー（Unix固有） |

### 12. uv_idle_s（Idleハンドル）

イベントループが他に処理するものがない場合にコールバックを実行する。uv_handle_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_handle_sの全フィールド） | - | - | ハンドル基底フィールドを継承 |
| idle_cb | uv_idle_cb | YES | Idle時コールバック（Unix固有） |
| queue | struct uv__queue | NO | Idleハンドルキュー（Unix固有） |

### 13. uv_async_s（Asyncハンドル）

別スレッドからイベントループスレッドへの通知に使用する。uv_handle_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_handle_sの全フィールド） | - | - | ハンドル基底フィールドを継承 |
| async_cb | uv_async_cb | YES | 非同期通知時コールバック（Unix固有） |
| queue | struct uv__queue | NO | Asyncハンドルキュー（Unix固有） |
| pending | int | NO | 保留中の通知フラグ（Unix固有） |

### 14. uv_process_s（プロセスハンドル）

子プロセスの管理を行う。uv_handle_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_handle_sの全フィールド） | - | - | ハンドル基底フィールドを継承 |
| exit_cb | uv_exit_cb | YES | プロセス終了時コールバック |
| pid | int | NO | 子プロセスのプロセスID |
| queue | struct uv__queue | NO | プロセスハンドルキュー（Unix固有） |
| status | int | NO | プロセス終了ステータス（Unix固有） |

### 15. uv_fs_event_s（FSイベントハンドル）

ファイルシステムの変更イベントを監視する。uv_handle_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_handle_sの全フィールド） | - | - | ハンドル基底フィールドを継承 |
| path | char* | YES | 監視対象パス |
| cb | uv_fs_event_cb | YES | FSイベントコールバック（Unix固有） |

### 16. uv_fs_poll_s（FSポーリングハンドル）

stat()ベースのファイル変更監視を行う。uv_handle_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_handle_sの全フィールド） | - | - | ハンドル基底フィールドを継承 |
| poll_ctx | void* | YES | ポーリングコンテキスト |

### 17. uv_signal_s（シグナルハンドル）

Unixシグナルの捕捉を行う。uv_handle_sのフィールドを継承する。赤黒木で管理される。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_handle_sの全フィールド） | - | - | ハンドル基底フィールドを継承 |
| signal_cb | uv_signal_cb | YES | シグナル受信時コールバック |
| signum | int | NO | 監視対象シグナル番号 |
| tree_entry.rbe_left | struct uv_signal_s* | YES | 赤黒木の左子ノード（Unix固有） |
| tree_entry.rbe_right | struct uv_signal_s* | YES | 赤黒木の右子ノード（Unix固有） |
| tree_entry.rbe_parent | struct uv_signal_s* | YES | 赤黒木の親ノード（Unix固有） |
| tree_entry.rbe_color | int | NO | 赤黒木のノード色（Unix固有） |
| caught_signals | unsigned int | NO | 捕捉したシグナル数（Unix固有） |
| dispatched_signals | unsigned int | NO | ディスパッチしたシグナル数（Unix固有） |

### 18. uv_req_s（リクエスト基底）

全てのリクエスト型の抽象基底構造体。非同期操作の実行単位を表現する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| data | void* | YES | ユーザーデータ用汎用ポインタ |
| type | uv_req_type | NO | リクエスト種別（UV_CONNECT, UV_WRITE等） |
| reserved | void*[6] | YES | 予約フィールド |

### 19. uv_write_s（書き込みリクエスト）

ストリームへの書き込み操作を表現する。uv_req_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_req_sの全フィールド） | - | - | リクエスト基底フィールドを継承 |
| cb | uv_write_cb | YES | 書き込み完了コールバック |
| send_handle | uv_stream_t* | YES | IPC経由で送信するハンドル |
| handle | uv_stream_t* | NO | 書き込み先ストリーム |
| queue | struct uv__queue | NO | 書き込みキューリンク（Unix固有） |
| write_index | unsigned int | NO | 書き込みバッファインデックス（Unix固有） |
| bufs | uv_buf_t* | YES | 書き込みバッファ配列（Unix固有） |
| nbufs | unsigned int | NO | バッファ数（Unix固有） |
| error | int | NO | エラーコード（Unix固有） |
| bufsml | uv_buf_t[4] | NO | 小規模バッファ用インライン配列（Unix固有） |

### 20. uv_connect_s（接続リクエスト）

TCP接続操作を表現する。uv_req_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_req_sの全フィールド） | - | - | リクエスト基底フィールドを継承 |
| cb | uv_connect_cb | YES | 接続完了コールバック |
| handle | uv_stream_t* | NO | 接続対象ストリーム |
| queue | struct uv__queue | NO | 接続キューリンク（Unix固有） |

### 21. uv_shutdown_s（シャットダウンリクエスト）

ストリームのシャットダウン操作を表現する。uv_req_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_req_sの全フィールド） | - | - | リクエスト基底フィールドを継承 |
| handle | uv_stream_t* | NO | シャットダウン対象ストリーム |
| cb | uv_shutdown_cb | YES | シャットダウン完了コールバック |

### 22. uv_udp_send_s（UDP送信リクエスト）

UDPデータ送信操作を表現する。uv_req_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_req_sの全フィールド） | - | - | リクエスト基底フィールドを継承 |
| handle | uv_udp_t* | NO | 送信元UDPハンドル |
| cb | uv_udp_send_cb | YES | 送信完了コールバック |
| queue | struct uv__queue | NO | 送信キューリンク（Unix固有） |
| u.addr | struct sockaddr | NO | 送信先アドレス（Unix固有） |
| nbufs | unsigned int | NO | バッファ数（Unix固有） |
| bufs | uv_buf_t* | YES | 送信バッファ配列（Unix固有） |
| status | ssize_t | NO | 送信ステータス（Unix固有） |
| send_cb | uv_udp_send_cb | YES | 送信コールバック（Unix固有） |
| bufsml | uv_buf_t[4] | NO | 小規模バッファ用インライン配列（Unix固有） |

### 23. uv_fs_s（FSリクエスト）

ファイルシステム操作を表現する。uv_req_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_req_sの全フィールド） | - | - | リクエスト基底フィールドを継承 |
| fs_type | uv_fs_type | NO | FS操作種別（OPEN, READ, WRITE等） |
| loop | uv_loop_t* | NO | 所属するイベントループ |
| cb | uv_fs_cb | YES | FS操作完了コールバック |
| result | ssize_t | NO | 操作結果 |
| ptr | void* | YES | 結果データポインタ |
| path | const char* | YES | 操作対象パス |
| statbuf | uv_stat_t | NO | stat結果格納領域 |
| new_path | const char* | YES | リネーム/リンク先パス（Unix固有） |
| file | uv_file | NO | ファイルディスクリプタ（Unix固有） |
| flags | int | NO | オープンフラグ（Unix固有） |
| mode | mode_t | NO | ファイルモード（Unix固有） |
| nbufs | unsigned int | NO | バッファ数（Unix固有） |
| bufs | uv_buf_t* | YES | 読み書きバッファ（Unix固有） |
| off | off_t | NO | オフセット（Unix固有） |
| uid | uv_uid_t | NO | ユーザーID（Unix固有） |
| gid | uv_gid_t | NO | グループID（Unix固有） |
| atime | double | NO | アクセス時刻（Unix固有） |
| mtime | double | NO | 変更時刻（Unix固有） |
| work_req | struct uv__work | NO | ワーカーリクエスト（Unix固有） |
| bufsml | uv_buf_t[4] | NO | 小規模バッファ用インライン配列（Unix固有） |

### 24. uv_work_s（ワークリクエスト）

スレッドプール上で実行されるジョブを表現する。uv_req_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_req_sの全フィールド） | - | - | リクエスト基底フィールドを継承 |
| loop | uv_loop_t* | NO | 所属するイベントループ |
| work_cb | uv_work_cb | YES | ワーカースレッドで実行するコールバック |
| after_work_cb | uv_after_work_cb | YES | ワーク完了後のコールバック |
| work_req | struct uv__work | NO | 内部ワーカーリクエスト（Unix固有） |

### 25. uv_getaddrinfo_s（DNS解決リクエスト）

ホスト名からアドレスへの解決操作を表現する。uv_req_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_req_sの全フィールド） | - | - | リクエスト基底フィールドを継承 |
| loop | uv_loop_t* | NO | 所属するイベントループ |
| work_req | struct uv__work | NO | ワーカーリクエスト（Unix固有） |
| cb | uv_getaddrinfo_cb | YES | 解決完了コールバック（Unix固有） |
| hints | struct addrinfo* | YES | アドレスヒント（Unix固有） |
| hostname | char* | YES | 解決対象ホスト名（Unix固有） |
| service | char* | YES | サービス名（Unix固有） |
| addrinfo | struct addrinfo* | YES | 解決結果（Unix固有） |
| retcode | int | NO | リターンコード（Unix固有） |

### 26. uv_getnameinfo_s（逆引きDNSリクエスト）

アドレスからホスト名への逆引き解決操作を表現する。uv_req_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_req_sの全フィールド） | - | - | リクエスト基底フィールドを継承 |
| loop | uv_loop_t* | NO | 所属するイベントループ |
| work_req | struct uv__work | NO | ワーカーリクエスト（Unix固有） |
| getnameinfo_cb | uv_getnameinfo_cb | YES | 逆引き完了コールバック（Unix固有） |
| storage | struct sockaddr_storage | NO | アドレス格納領域（Unix固有） |
| flags | int | NO | フラグ（Unix固有） |
| host | char[NI_MAXHOST] | NO | ホスト名結果（Unix固有） |
| service | char[NI_MAXSERV] | NO | サービス名結果（Unix固有） |
| retcode | int | NO | リターンコード（Unix固有） |

### 27. uv_random_s（乱数リクエスト）

乱数生成操作を表現する。uv_req_sのフィールドを継承する。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| （uv_req_sの全フィールド） | - | - | リクエスト基底フィールドを継承 |
| loop | uv_loop_t* | NO | 所属するイベントループ |
| status | int | NO | 操作ステータス |
| buf | void* | YES | 乱数格納先バッファ |
| buflen | size_t | NO | バッファ長 |
| cb | uv_random_cb | YES | 乱数生成完了コールバック |
| work_req | struct uv__work | NO | ワーカーリクエスト |

### 28. heap（バイナリ最小ヒープ）

タイマーハンドルの管理に使用されるバイナリ最小ヒープ。ルートが最小要素となり、木の高さは最大log2(n)である。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| min | struct heap_node* | YES | ヒープのルート（最小要素） |
| nelts | unsigned int | NO | ヒープ内の要素数 |

### 29. heap_node（ヒープノード）

バイナリ最小ヒープの各要素を表現するノード。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| left | struct heap_node* | YES | 左子ノード |
| right | struct heap_node* | YES | 右子ノード |
| parent | struct heap_node* | YES | 親ノード |

### 30. uv__queue（双方向リンクリスト）

libuvの内部キュー構造。ハンドルの管理、書き込みキュー等で広く使用される。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| next | struct uv__queue* | NO | 次の要素へのポインタ |
| prev | struct uv__queue* | NO | 前の要素へのポインタ |

### 31. uv__io_s（I/Oウォッチャー）

ファイルディスクリプタのI/Oイベント監視を行う内部構造体。Unix環境固有。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| bits | uintptr_t | NO | コールバック関数ポインタとフラグのビットフィールド |
| pending_queue | struct uv__queue | NO | 保留キューリンク |
| watcher_queue | struct uv__queue | NO | ウォッチャーキューリンク |
| pevents | unsigned int | NO | 保留中のイベントマスク（次のティック用） |
| events | unsigned int | NO | 現在のイベントマスク |
| fd | int | NO | 監視対象ファイルディスクリプタ |

### 32. uv_stat_t（ファイル統計情報）

ファイルのメタデータを格納する構造体。uv_fs_stat()の結果として使用される。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| st_dev | uint64_t | NO | デバイスID |
| st_mode | uint64_t | NO | ファイルモード（パーミッション等） |
| st_nlink | uint64_t | NO | ハードリンク数 |
| st_uid | uint64_t | NO | 所有者ユーザーID |
| st_gid | uint64_t | NO | 所有者グループID |
| st_rdev | uint64_t | NO | デバイスID（特殊ファイル用） |
| st_ino | uint64_t | NO | inode番号 |
| st_size | uint64_t | NO | ファイルサイズ（バイト） |
| st_blksize | uint64_t | NO | ブロックサイズ |
| st_blocks | uint64_t | NO | 割り当てブロック数 |
| st_flags | uint64_t | NO | ファイルフラグ |
| st_gen | uint64_t | NO | ファイル生成番号 |
| st_atim | uv_timespec_t | NO | 最終アクセス時刻 |
| st_mtim | uv_timespec_t | NO | 最終変更時刻 |
| st_ctim | uv_timespec_t | NO | 最終状態変更時刻 |
| st_birthtim | uv_timespec_t | NO | 作成時刻 |

### 33. uv_statfs_s（ファイルシステム統計）

ファイルシステムの容量情報を格納する構造体。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| f_type | uint64_t | NO | ファイルシステム種別 |
| f_bsize | uint64_t | NO | 基本ブロックサイズ |
| f_blocks | uint64_t | NO | 総ブロック数 |
| f_bfree | uint64_t | NO | 空きブロック数 |
| f_bavail | uint64_t | NO | 非特権ユーザー利用可能ブロック数 |
| f_files | uint64_t | NO | 総inode数 |
| f_ffree | uint64_t | NO | 空きinode数 |
| f_frsize | uint64_t | NO | フラグメントサイズ |
| f_spare | uint64_t[3] | NO | 予約領域 |

### 34. uv_cpu_info_s（CPU情報）

CPU情報を格納する構造体。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| model | char* | YES | CPUモデル名 |
| speed | int | NO | CPUクロック速度（MHz） |
| cpu_times.user | uint64_t | NO | ユーザーモードCPU時間（ミリ秒） |
| cpu_times.nice | uint64_t | NO | nice優先度CPU時間（ミリ秒） |
| cpu_times.sys | uint64_t | NO | システムモードCPU時間（ミリ秒） |
| cpu_times.idle | uint64_t | NO | アイドルCPU時間（ミリ秒） |
| cpu_times.irq | uint64_t | NO | IRQ処理CPU時間（ミリ秒） |

### 35. uv_interface_address_s（ネットワークIF情報）

ネットワークインタフェースのアドレス情報を格納する構造体。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| name | char* | YES | インタフェース名 |
| phys_addr | char[6] | NO | 物理（MAC）アドレス |
| is_internal | int | NO | 内部インタフェース（ループバック）かどうか |
| address.address4 | struct sockaddr_in | NO | IPv4アドレス |
| address.address6 | struct sockaddr_in6 | NO | IPv6アドレス |
| netmask.netmask4 | struct sockaddr_in | NO | IPv4ネットマスク |
| netmask.netmask6 | struct sockaddr_in6 | NO | IPv6ネットマスク |

### 36. uv_passwd_s（ユーザー情報）

OSユーザーのパスワードエントリ情報を格納する構造体。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| username | char* | YES | ユーザー名 |
| uid | unsigned long | NO | ユーザーID |
| gid | unsigned long | NO | グループID |
| shell | char* | YES | デフォルトシェル |
| homedir | char* | YES | ホームディレクトリ |

### 37. uv_group_s（グループ情報）

OSグループ情報を格納する構造体。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| groupname | char* | YES | グループ名 |
| gid | unsigned long | NO | グループID |
| members | char** | YES | メンバーユーザー名の配列 |

### 38. uv_utsname_s（システム名情報）

OSのuname情報を格納する構造体。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| sysname | char[256] | NO | OS名 |
| release | char[256] | NO | リリース番号 |
| version | char[256] | NO | バージョン情報 |
| machine | char[256] | NO | ハードウェア識別子 |

### 39. uv_env_item_s（環境変数）

環境変数のキーバリューペアを格納する構造体。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| name | char* | YES | 環境変数名 |
| value | char* | YES | 環境変数値 |

### 40. uv_dirent_s（ディレクトリエントリ）

ディレクトリ内のファイルエントリ情報を格納する構造体。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| name | const char* | YES | エントリ名 |
| type | uv_dirent_type_t | NO | エントリ種別（FILE, DIR, LINK等） |

### 41. uv_dir_s（ディレクトリ）

ディレクトリの読み取りコンテキストを管理する構造体。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| dirents | uv_dirent_t* | YES | ディレクトリエントリの配列 |
| nentries | size_t | NO | エントリ数 |
| reserved | void*[4] | YES | 予約フィールド |
| dir | DIR* | YES | ディレクトリストリーム（Unix固有） |

### 42. uv_metrics_s（メトリクス）

イベントループのメトリクス情報を格納する構造体。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| loop_count | uint64_t | NO | ループ反復回数 |
| events | uint64_t | NO | 処理済みイベント数 |
| events_waiting | uint64_t | NO | 待機中のイベント数 |
| reserved | uint64_t*[13] | YES | 予約フィールド |

### 43. uv_process_options_s（プロセスオプション）

子プロセス起動時のオプションを指定する構造体。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| exit_cb | uv_exit_cb | YES | プロセス終了時コールバック |
| file | const char* | NO | 実行するプログラムのパス |
| args | char** | YES | コマンドライン引数（args[0]はプログラムパス） |
| env | char** | YES | 環境変数（NULLの場合は親の環境を継承） |
| cwd | const char* | YES | 作業ディレクトリ |
| flags | unsigned int | NO | プロセスフラグ |
| stdio_count | int | NO | stdioコンテナの数 |
| stdio | uv_stdio_container_t* | YES | stdioコンテナ配列 |
| uid | uv_uid_t | NO | 子プロセスのユーザーID |
| gid | uv_gid_t | NO | 子プロセスのグループID |

### 44. uv__loop_internal_fields_s（ループ内部フィールド）

イベントループの内部管理データを格納する構造体。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| flags | unsigned int | NO | 内部フラグ |
| loop_metrics | uv__loop_metrics_t | NO | ループメトリクス |
| current_timeout | int | NO | 現在のタイムアウト値 |

### 45. uv__loop_metrics_s（ループメトリクス内部）

イベントループの内部メトリクスデータを格納する構造体。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| metrics | uv_metrics_t | NO | 公開メトリクス情報 |
| provider_entry_time | uint64_t | NO | プロバイダーエントリ時刻 |
| provider_idle_time | uint64_t | NO | プロバイダーアイドル時間 |
| lock | uv_mutex_t | NO | メトリクスアクセス用ミューテックス |

## 備考

### データ構造間の関係

1. **イベントループ（uv_loop_s）が全体の中核**：全てのハンドルとリクエストはイベントループに紐づく。
2. **ハンドル継承階層**：uv_handle_s -> uv_stream_s -> uv_tcp_s / uv_pipe_s / uv_tty_s。CマクロによるフィールドのインクルードでC言語上の「継承」を実現している。
3. **リクエスト継承階層**：uv_req_s -> uv_write_s / uv_connect_s / uv_shutdown_s / uv_fs_s / uv_work_s 等。
4. **キュー管理**：uv__queue構造体による双方向リンクリストで、ハンドルやリクエストがイベントループ内のキューに管理される。
5. **タイマー管理**：バイナリ最小ヒープ（heap構造体）でタイマーが管理され、最小タイムアウトが効率的に取得される。
6. **シグナル管理**：赤黒木（RBツリー）でシグナルハンドルが管理される。

### プラットフォーム依存性

本設計書は主にUnix（POSIX）環境におけるデータ構造を記述している。Windows環境では一部のプライベートフィールドが異なる実装を持つ（UV_xxx_PRIVATE_FIELDSマクロにより切り替えられる）。

### 永続化について

libuvは純粋なインメモリライブラリであり、これらのデータ構造はプロセスの寿命と同じ期間のみ存在する。ディスクへの永続化やデータベースへの保存は行われない。
