aio-readstreamlisted

PostgreSQL's async I/O subsystem + the read-stream API — `src/backend/storage/aio/` (introduced PG 17, matured PG 18). Loads when the user asks about the read_stream API, AIO methods (sync / worker / io_uring), how sequential + bitmap scans issue prefetch, migrating a code path from `StartReadBuffer`+`WaitReadBuffer` to `read_stream_*`, adding a new read-stream consumer, tuning `io_max_concurrency` / `io_workers` / `io_method`, or debugging AIO-related buildfarm failures. Also for the read-stream callbacks (per-block-lookup / per-buffer-release), completion callbacks (`aio_callback.c`), and the io_uring linkage. Skip when the ask is about client-side async (libpq) or about the WAL writer / walreceiver (those have their own I/O paths).
matejformanek/postgres-claude · ★ 0 · AI & Automation · score 70

Install: claude install-skill matejformanek/postgres-claude

# aio-readstream — the async I/O and read-stream API PostgreSQL 17 introduced the **`read_stream` API** — a unified way for scan-shaped code (sequential scans, bitmap heap scans, VACUUM, ANALYZE, some indexes) to issue reads. PG 18 promoted the underlying AIO layer to a first-class subsystem in `src/backend/storage/aio/`, adding pluggable methods (sync / worker / io_uring). Together they let PG overlap CPU work with I/O without per-caller `posix_fadvise` bookkeeping. ## The file map | File | Lines | Role | |---|---:|---| | `aio.c` | 36.6K | Framework core — `PgAioHandle` pool, submit/wait state machine, method dispatch. | | `aio_init.c` | 6.6K | Shmem init + GUCs (`io_method`, `io_max_concurrency`, `io_workers`, `io_uring_slots`). | | `aio_callback.c` | 10.2K | Completion-callback registration + dispatch — modules extend AIO by registering a callback. | | `aio_target.c` | 3.2K | The set of "things that can be read" — currently smgr (files by relfilenode) + WAL (in progress). | | `aio_io.c` | 5.5K | The low-level read/write submission (per-target-per-method). | | `aio_funcs.c` | 6.2K | SQL-callable helpers backing `pg_aios` view + statistics. | | `method_sync.c` | 1.2K | Synchronous fallback — no actual async, just `pread`. Default on platforms without io_uring or when disabled. | | `method_worker.c` | 27.6K | Background-worker method — a small pool of dedicated I/O workers do the reads. Portable across Unix/Windows. | | `method_io_uring.c` | 22.1K | io_uring method (Linux