Message-ID: <gh-pgjdbc-pgjdbc-4066@github.com>
From: "davecramer (@davecramer)" <noreply+davecramer@github.com>
To: "pgjdbc/pgjdbc" <noreply+pgjdbc-pgjdbc@github.com>
Date: Tue, 12 May 2026 14:42:26 +0000
Subject: [pgjdbc/pgjdbc] PR #4066: feat: Add pipeline mode with dedicated reader thread
List-Id: <gh-pgjdbc-pgjdbc.github.com>
X-GitHub-Author-Id: 406518
X-GitHub-Author-Login: davecramer
X-GitHub-Issue: 4066
X-GitHub-Repo: pgjdbc/pgjdbc
X-GitHub-State: open
X-GitHub-Type: pull_request
X-GitHub-Url: https://github.com/pgjdbc/pgjdbc/pull/4066
Content-Type: text/plain; charset=utf-8

Implement protocol-level pipelining using a dedicated reader thread that decouples send and receive paths. When enabled via the pipelineMode connection property, the driver sends Parse/Bind/Execute messages without waiting for responses, while a background thread reads and dispatches results to ResponseSlots using LockSupport park/unpark signaling.

Key design decisions:
- Dedicated reader thread owns pgInput exclusively after startup
- ConcurrentLinkedDeque for lock-free slot queue between threads
- Volatile signaling fields with parkNanos timeout + liveness check
- SYNC_MARKER sentinels for error cascading across batch boundaries
- Clean shutdown path via close()/abort() overrides

Concurrency fixes applied during review:
- Made ResponseSlot.waiter volatile for cross-thread visibility
- Added reader thread shutdown in close() and abort()
- Added parkNanos(1s) timeout with isAlive() liveness check to prevent indefinite parking if reader thread dies
- Await BEGIN slot and propagate errors before user query
- Used receiveErrorString for notice messages (encoding fallback)

Performance measurements (PG 15, us-east-1 EC2, network RTT ~20ms):

  Sequential queries (200 iter): sync 36.22ms, pipeline 54.56ms (0.66x)
  Batch insert (500 rows):       sync 23.52ms, pipeline 19.07ms (1.23x)
  Prepared stmt reuse (500 iter): sync 52.99ms, pipeline 55.83ms (0.95x)
  Large result fetch (10k rows): sync 18.39ms, pipeline 10.23ms (1.80x)

Pipeline mode shows clear wins for bulk operations (batch insert 1.23x, large result fetch 1.80x) where the decoupled read path eliminates round-trip stalls. Sequential single-query workloads show slight overhead from thread coordination, as expected — the benefit scales with batch size and result volume.

Test: 22 pipeline functional tests + 4 performance tests all pass.
Full suite: 9367 tests, 0 pipeline-related failures.