rwc + runtime: netpoller + 最小 TCP API (echo server)

[ryuichi1208]

Summary

• ランタイムに netpoller スレッド を追加 (kqueue on macOS / epoll on Linux、専用 pthread 1 本)
• fiber を fd readiness で park / wake する内部 API (rw_net_park_read/write)
• rw 言語に 5 つの TCP 組込み:
  • tcp_listen(port: int) -> int
  • tcp_accept(listen_fd: int) -> int
  • tcp_read(fd: int, max: int) -> Bytes
  • tcp_write(fd: int, b: Bytes) -> int
  • tcp_close(fd: int) -> int
• examples/tcp_echo.rw (10 行) で TCP echo server が動作
• e2e: 1 接続 + 10 並列接続を Python socket で検証

Why

ロードマップの 最終目標 (docs/specs/12-netpoller-tcp.md)。これまでの言語拡張 (string / Bytes / List / Option / Result / match) と M:N スケジューラ (#90) を組み合わせ、「fiber が recv でブロックしているように見えて裏で kqueue/epoll が回る」 という Go 風の書き味を実現する。

ロードマップ:

1. 文字列 len / == / + (rwc: 文字列の最小拡張 (len, ==, +) #91)
2. Bytes 型 (rwc: Bytes 型 (immutable, echo 最小セット) #92)
3. List[int] (rwc: List[int] 型 (immutable, モノモーフ, echo 最小セット) #93)
   4a. Option[int] + match (rwc: Option[int] 型と最小 match 構文 (Python 3.10 風) #94)
   4b. Result[int, int] (rwc: Result[int, int] 型と match の Ok/Err アーム拡張 #95)
   4c. (将来) 真のジェネリクス化
4. このサブプロジェクト: netpoller + TCP API → echo server

アーキテクチャ

                                 +---------------------+
                                 |  netpoller thread   |
                                 |  kevent/epoll_wait  |
                                 +----------+----------+
                                            | enqueue_ready
                                            v
+--------+   spawn    +------------------------------------+
|  main  | ---------> |   ready queue (per-P + globq)      |
+--------+            +-------+----------+-------+---------+
  blocking                    |          |       |
  accept()                    v          v       v
                          +--------+ +--------+ +--------+
                          | wkr M1 | | wkr M2 | | wkr Mn |
                          +--------+ +--------+ +--------+
                              |          |          |
                              v          v          v
                          fiber 実行 → EAGAIN → rw_net_park_read

OS thread: 1 main + nproc worker M + 1 netpoller = nproc + 2 (接続数に依存しない)。
fiber: 接続ごとに 1 つ、上限は実質的に ulimit -n と RAM。

できるようになったこと

```rw
def handle_client(fd: int) -> int:
while true:
b: Bytes = tcp_read(fd, 4096)
if len(b) == 0:
tcp_close(fd)
return 0
tcp_write(fd, b)
return 0

def main() -> int:
listen_fd: int = tcp_listen(8080)
while true:
client: int = tcp_accept(listen_fd)
spawn handle_client(client)
return 0
```

```sh
$ uv run rwc run examples/tcp_echo.rw &
$ python3 -c "import socket; s=socket.create_connection(('127.0.0.1',8080)); s.sendall(b'hello'); print(s.recv(64))"
b'hello'
```

コミット構成 (8 commits)

commit	内容
spec	docs/specs/12-netpoller-tcp.md
sched export	rw_sched_enqueue_ready / rw_sched_current_fiber / rw_sched_park_current を netpoller 向けに公開
netpoller skeleton	runtime/net/{netpoller, netpoller_kqueue, netpoller_epoll, tcp}.{c,h} の枠組み。rw_init / rw_shutdown で netpoller pthread を起動・停止
pipe テスト	pipe(2) で park/wake の動作を C テスト (test_netpoller_pipe) で確認
tcp 本実装	tcp_listen/tcp_accept/tcp_read/tcp_write/tcp_close を実装し、localhost loopback の C テストで検証
rwc	5 つの組込みを Sema + irgen に追加、positive 5 + negative 5
examples + e2e	examples/tcp_echo.rw + Python e2e (1 接続 / 10 並列接続)
plan	docs/plans/2026-05-23-netpoller-tcp.md

設計の要点

専用 netpoller スレッド

1 つの pthread が kevent / epoll_wait を ループ。fd ready 通知を受けたら rw_sched_enqueue_ready(fiber) で fiber を起こす。worker M のスケジュール責務とは分離。

ONESHOT 監視

kqueue は EV_ONESHOT、epoll は EPOLLONESHOT を使用。同じ fd への複数 fiber 同時 park は protocol 規約で排除し (Non-Goals)、kernel 側の自動 deregister でクリーンアップ。

main thread と fiber で分岐

rw_tcp_accept は rw_sched_current_fiber() で呼び出し元を判別:

• fiber 内: nonblocking accept + EAGAIN park
• main thread (worker でも fiber でもない): blocking accept で kernel sleep — worker M / netpoller は別 thread なので並行進行は維持

Shutdown 同期

netpoller スレッドは kevent/epoll_wait で sleep している。shutdown 時に起こすため:

• kqueue: EVFILT_USER + NOTE_TRIGGER
• epoll: eventfd に書き込み

Test plan

• `uv run pytest -q` で 143 件 緑 (元 131 + sema 新規 10 + e2e_tcp 新規 2)
• C 単体テスト test_netpoller_pipe: pipe で fiber が park → 別 fiber が write → 起きる
• C 単体テスト test_tcp_loopback: localhost で listen → connect → recv/send round-trip
• 既存 example (option_basic / result_basic / spawn_many) 全部回帰なし
• `examples/tcp_echo.rw` が手動 smoke で hello を echo
• e2e で 10 並列接続を捌ける

ネガティブテスト (Sema)

• tcp_listen("8080") → 引数型エラー
• tcp_read(3, "big") / tcp_write(3, "hi") → 引数型エラー
• tcp_listen() → arity エラー
• spawn tcp_accept(3) → 組込みは spawn 不可

Non-Goals (spec で明示)

• IPv6 / UDP / TLS / Unix domain socket
• tcp_listen のホスト指定 (0.0.0.0 固定 IPv4)
• 詳細エラー (errno 取得 API)
• graceful shutdown / SIGINT ハンドラ
• partial write の自動 retry
• Result[Bytes, int] でのエラー表現 (4c のジェネリクス待ち)
• C10k ベンチ
• ファイル I/O / pipe / TTY の rw 言語 API

🤖 Generated with Claude Code