pg_pipeline 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b73820c432250a5622916f522cc7df96e9be218120372d90d30447b2ea4364f
-  data.tar.gz: af6ac07e07a30e7812846c58b56cfb3fcf0722b6fcac99119be4529249a92a0f
+  metadata.gz: 7135257ec52d199f4a7e0d3666909eebd8effa277f7efe80d27ca8ff00717f93
+  data.tar.gz: 8f3b976cc4b9f8400439a1504bbad9a019865a88a7f41e6556907ba649587c80
 SHA512:
-  metadata.gz: 70249da4404588815fd9b5122ad3bcd564ca8fb8deec8f9068788a27bad9427ebac189bb7ee3ae9f0e05c0461429a00c2a70001749d62f11199777a1d3394472
-  data.tar.gz: b030ef64f18383b8d3fd15177f7375b7347fed99e7e2e2dc387133306a35fccbe775a79aa8545005fef3bffc7d8ed1ba9547a389212de9a3c8801c0558a0d24e
+  metadata.gz: 90422fd9a948509c2e53b9058d052a822e76f303a736a39488a0870b6fa903d6c1b2b8248e00649269a63ed606a9a8d04b1c2c081cf0f2b89e81000af8a36e54
+  data.tar.gz: fa76f361560fa078903685d69de81600b8337509b8f37b89cd93fdfdc71ebc3953180edf8487b4aa24d79d521237ef98bc727cde48ca959acb41c0d589749999

data/CHANGELOG.md

@@ -1,6 +1,135 @@
 # Changelog
 
-## [0.2.0] - unreleased
+## [0.2.3] - 2026-07-30
+
+Performance-focused release based on CPU profiles from the live pipeline
+workload. It removes redundant libpq polling, adds an explicit prepared-
+statement hot path, and trims several per-query control-plane costs without
+changing the failure model.
+
+### Added
+
+- `Client#prepare(name, sql, param_types = nil)` prepares immutable SQL on every
+  currently live pipeline connection and returns a `PreparedStatement` handle.
+- `PreparedStatement#query(params = [])` executes through
+  `send_query_prepared`, avoiding repeated Parse/Describe work for hot SQL.
+- Replacement pipeline connections replay the registered prepared-statement
+  catalog before becoming available, including registrations that race with a
+  reconnect.
+- Prepared-statement unit and live integration coverage, including execution
+  across multiple drivers and automatic re-prepare after reconnect.
+
+### Performance
+
+- The connection owner drains results only after `consume_input` actually read
+  a readable socket event. Removed unconditional pre/post-dispatch drain passes
+  that repeatedly called `PQisBusy` without new input.
+- A blocked `PQflush` is retried by the writer watcher instead of again on every
+  unrelated owner event. Newly queued output remains buffered in libpq until the
+  socket becomes writable.
+- Driver selection is now one circular least-load pass: each available driver's
+  `load` is read once and equal-load ties rotate from the selected slot.
+- The normalized SQL guard mode is reused on the query hot path instead of
+  coercing and validating it for every request.
+- Already-frozen SQL strings and frozen string bind values are reused rather
+  than duplicated; mutable caller input is still snapshotted before submission.
+- Prepared-only metadata lives on internal request subclasses, so ordinary
+  query requests do not grow extra instance variables for the new API.
+- The throughput and A/B harnesses explicitly clear every result and support
+  `PREPARED=1`, preparing both pipeline and baseline clients for a fair hot-path
+  comparison.
+
+### Semantics
+
+- Prepared statements are explicit client-scoped handles, not an automatic
+  unbounded SQL cache. The SQL guard runs once during registration.
+- Failed registration is removed from the reconnect catalog. Successfully
+  prepared but unreachable internal names may remain on already-prepared
+  physical connections until those connections close.
+- Multiplexed prepared handles live for the lifetime of the client; this release
+  intentionally does not add a concurrent `DEALLOCATE` API.
+
+## [0.2.2] - 2026-07-30
+
+Lifecycle-hardening release. Fixes five pool/task-ownership defects surfaced by
+review, adds input validation, and ships deterministic regression coverage for
+each fix.
+
+### Fixed (pool & task lifecycle)
+
+- Replacement pipeline drivers are now owned by the pool's stable parent task,
+  not the supervisor. Stopping the supervisor during shutdown can no longer
+  cascade-cancel a live replacement driver before it is gracefully drained.
+- Returning a pinned connection re-checks the closing state after the yielding
+  recycle step (`ROLLBACK`/`DISCARD ALL`/reconnect); a connection recycled while
+  a concurrent `abort!` runs is closed instead of leaked into the free list.
+- Task cancellation during pinned recycle (`Async::Cancel`/`Async::Stop` are
+  `Exception`s, not `StandardError`s) is caught solely to close the connection
+  and then re-raised, so cancellation semantics are preserved and the connection
+  is not leaked.
+- Nested `Client#session`/`Client#transaction` on the same task is rejected with
+  `RecursiveCheckoutError` before the pinned semaphore is acquired, preventing a
+  self-deadlock (`pinned_size: 1`) or a silently different connection
+  (`pinned_size > 1`). Use `Transaction#savepoint` for nested atomicity.
+- A closing or closed pool is terminal: `Pool#start` raises rather than
+  half-restarting onto stale driver state, including after an interrupted close.
+  Create a new pool instead.
+- Partial startup now also cleans up if spawning the supervisor task fails after
+  drivers were created.
+- Once shutdown begins, availability checks report `ShutdownError` before the
+  generic not-started state, preserving the definitely-not-dispatched failure
+  classification for concurrent submitters.
+
+### Changed (hardening)
+
+- Timing options (`reconnect_interval`, `reconnect_backoff_max`,
+  `health_interval`, `health_timeout`) reject negative, `NaN`, and infinite
+  values; `health_interval` additionally allows `0` ("probe every cycle").
+- The supervisor wakes on the shorter of the enabled reconnect/health cadences,
+  so a short `health_interval` is honored independently of a large
+  `reconnect_interval`, using scheduler-aware `Kernel#sleep` rather than the
+  deprecated `Async::Task#sleep` wrapper.
+- Reconnect backoff uses floating-point exponentiation and caps non-finite or
+  over-limit delays, avoiding giant integers without prematurely flattening the
+  backoff for very small base intervals.
+- `Transaction#open`/`#savepoint_seq` are no longer publicly writable; control
+  state is read via `#open?` and mutated only internally.
+- `Session#exec` accepts optional bind parameters (`exec(sql, params)`),
+  matching the documented API; any explicitly supplied params value, including
+  an empty array, uses `exec_params`, while omitted params keep simple-query mode.
+- Driver shutdown attempts every driver even if one close raises or the closing
+  task is cancelled, then re-raises cancellation after best-effort cleanup;
+  watcher cleanup still stops the writer when stopping the reader fails.
+- `Client#close`/`#abort!` now clear client lifecycle state even when terminal pool
+  cleanup reports an error, while a rejected re-entrant close leaves the live
+  client started.
+
+### Compatibility
+
+- Shutdown cleanup handles `Async::Cancel` explicitly. The supported dependency
+  floor (`async 2.42.0`) already defines that class, so no dead compatibility
+  fallback is required.
+- CI now runs the unit suite against exact `async 2.42.0`, builds ruby-pg against
+  source-built client libpq 14.23/16.14/17.10 and runs each build against a live
+  PostgreSQL server, plus a separate server integration matrix for 14/16/17/18.
+
+## [0.2.1]
+
+- SessionGuard: bounded per-SQL memo cache for unsafe_reason. Repeated SQL
+  (parameterized queries) now costs ~0 allocations instead of ~330 objects/call
+  (measured); eliminates the code_only/byteslice line that showed up in profiles.
+- Client#query: drop redundant sql dup (Request owns the one immutable copy).
+- PoolOps.select_driver: allocation-free least-loaded scan (was 2-3 arrays/call);
+  behavior verified identical across 20k random cases.
+- bench_kit/metrics.rb + rake bench:metrics: full picture in one run —
+  allocations/query + GC pressure, RubyProf process_time (CPU) and allocations,
+  RubyProf wall (sanity), and StackProf cpu/wall sampling. Asserts run outside
+  every profiler; warmup keeps connection setup out of frame.
+- profile_ci_scenario.rb: correctness asserts moved out of the profiled block;
+  GC.start before profiling.
+- Dev dependency: stackprof (~> 0.2).
+
+## [0.2.0]
 
 Initial experimental implementation.
 
@@ -103,7 +232,7 @@ Initial experimental implementation.
   even when the losing Request was already settled.
 - Strict guard precise denylist (no pg_typeof/setup/xact-advisory false positives).
 - CI separates server-major coverage from source-built client-libpq 14/16 coverage.
-- benchmarks/ (fiber-storm latency, multi-worker connection-count smoke).
+- `bench_kit/` (fiber-storm latency, multi-worker connection-count smoke).
 - Pool driver slot arrays self-heal size (reconnect/health safe under partial init).
 - Unit coverage: failover, health_probe, pinned cancel on abort.
 
@@ -138,19 +267,3 @@ Initial experimental implementation.
   boundary: cancellation during rollback/sanitize/reconnect closes the physical
   connection instead of orphaning it outside the pool. Graceful close also closes
   already-idle pinned sockets before waiting for active checkouts.
-
-## 0.2.1 (perf + measurement)
-
-- SessionGuard: bounded per-SQL memo cache for unsafe_reason. Repeated SQL
-  (parameterized queries) now costs ~0 allocations instead of ~330 objects/call
-  (measured); eliminates the code_only/byteslice line that showed up in profiles.
-- Client#query: drop redundant sql dup (Request owns the one immutable copy).
-- PoolOps.select_driver: allocation-free least-loaded scan (was 2-3 arrays/call);
-  behavior verified identical across 20k random cases.
-- bench_kit/metrics.rb + rake bench:metrics: full picture in one run —
-  allocations/query + GC pressure, RubyProf process_time (CPU) and allocations,
-  RubyProf wall (sanity), and StackProf cpu/wall sampling. Asserts run outside
-  every profiler; warmup keeps connection setup out of frame.
-- profile_ci_scenario.rb: correctness asserts moved out of the profiled block;
-  GC.start before profiling.
-- Dev dependency: stackprof (~> 0.2).

data/DESIGN.md

@@ -51,10 +51,13 @@ sync_get_result
 `is_busy` is only a readiness predicate: false means the next
 `sync_get_result` will not block. It is not a request boundary.
 
-The owner also checks `is_busy` opportunistically before going back to sleep,
-not only after a socket-readable notification. PostgreSQL's own
-`libpq_pipeline.c` does the same because libpq can synthesize an aborted-pipeline
-result locally without making the socket newly readable.
+The owner calls `consume_input` on a socket-readable event and then drains until
+`is_busy` becomes true or the in-flight FIFO is empty. A drain pass exhausts all
+currently buffered results, including locally represented pipeline-aborted and
+pipeline-sync statuses. Request, writable and bookkeeping events therefore do
+not poll `is_busy` again: without a new `consume_input` they cannot reveal new
+server input, and the redundant Ruby-to-C calls were the largest control-plane
+CPU hot spot in profiling.
 
 ## 4. Protocol/FIFO model
 
@@ -112,6 +115,21 @@ Anything stateful goes through an exclusive pinned connection:
 - `Client#session` — no implicit BEGIN;
 - `Client#transaction` — BEGIN/COMMIT/ROLLBACK.
 
+The one deliberate exception is `Client#prepare`, which is not an arbitrary
+session mutation exposed to callers. It registers immutable SQL in a
+client-owned catalog and prepares the same generated physical name on every
+pipeline connection. The returned `PreparedStatement` handle can then use
+`send_query_prepared` through the normal FIFO protocol. A replacement connection
+replays the full catalog before it becomes available, so routing never selects a
+driver that lacks a successfully registered handle.
+
+Registration is explicit: there is no unbounded automatic SQL cache. A failed
+registration is removed from the reconnect catalog; statements that had already
+been prepared on another connection may remain there under an unreachable
+generated name until that connection is replaced or closed. Version 0.2.3 does
+not expose `DEALLOCATE` for multiplexed handles. Server-side plan invalidation is
+reported as the ordinary request-local `QueryError`.
+
 Pinned connections are opened lazily up to `pinned_size`; a query-only process
 does not reserve an otherwise idle second pool at startup. Before a pinned
 physical connection is reused, the pool makes sure it is outside an explicit
@@ -250,14 +268,16 @@ chunked-rows, non-blocking cancel), never a floor.
   (`cancel_pinned_on_abort: true`); it does not force-close the socket if the
   backend ignores cancel.
 - No streaming/single-row/chunked-row result API.
+- No multiplexed prepared-statement deallocation API; registered handles live
+  for the lifetime of the client.
 - No cross-thread/reactor sharing; `Client` rejects use from a different thread or Fiber scheduler.
 - `SessionGuard` is policy/ergonomics, not a security boundary. `:strict` adds a
   precise denylist (`nextval`/`setval`/`pg_export_snapshot`, …) without the old
   broad `pg_*(` / `set*(` false positives; UDFs can still mutate session state.
-- Live integration covers **server** PG 14/16/17. CI prints the linked **client**
-  libpq version, but does not yet matrix distinct client-libpq majors (one
-  runner libpq across all server jobs). Pipeline capability is client-side, so
-  a dedicated libpq 14/16/17 client matrix remains future work.
+- Live integration covers **server** PG 14/16/17/18. A separate CI matrix
+  builds ruby-pg against source-built **client** libpq 14/16/17, asserts the
+  linked major, and runs both unit and live integration suites because pipeline
+  capability is determined by client libpq rather than server version.
 - On libpq 14–16, `place_sync` uses `PQpipelineSync` / ruby-pg `sync_pipeline_sync`
   (flush coupled); libpq 17+ uses `send_pipeline_sync` + explicit `sync_flush`.
 - Pinned recycle still runs full `DISCARD ALL` (no lighter reset profile / recycle
@@ -284,15 +304,15 @@ Implemented:
   live sibling; the failed Request object itself is never re-used.
 - `abort!` CancelRequest on in-use pinned connections.
 - Falcon per-worker contract + sizing formula; reactor-local Client fail-fast.
-- Packaging: gemspec metadata, CI (unit + PG server 14/16/17), docker-compose,
-  examples, `benchmarks/pipeline_bench.rb` + `benchmarks/multiworker_smoke.rb`.
+- Packaging: gemspec metadata, CI (unit + PG server 14/16/17/18 + client-libpq
+  14/16/17 + exact async floor), docker-compose,
+  examples, `bench_kit/pipeline_throughput.rb` + `bench_kit/multiworker_smoke.rb`.
 - Live integration suite (multiplex, isolation, cancel-drain, savepoints, stats,
   backpressure, pinned concurrency, indeterminate on abort, reconnect, backend
   terminate recovery, pinned abort cancel).
 
 Still open:
 
-- Dedicated client-libpq 14/16/17 CI matrix (not only server majors).
 - Lighter pinned reset / recycle-latency metrics under high-TPS tx.
 - Force socket close if pinned cancel is ignored.
 - Published bench numbers in README; tighten multiworker smoke to peak occupancy.

data/README.md

@@ -62,6 +62,35 @@ end
 `Client.open` manages the pool lifecycle. `db.query` is fiber-safe and multiplexed —
 every fiber yields while waiting, the event loop stays unblocked.
 
+### Multiplexed prepared statements
+
+For repeated SQL, prepare it once on every pipeline connection and execute the
+returned immutable handle:
+
+```ruby
+by_id = db.prepare(
+  "user_by_id",
+  "SELECT id, email, name FROM users WHERE id = $1",
+  [23] # optional PostgreSQL parameter OIDs
+)
+
+result = by_id.query([42])
+begin
+  p result.first
+ensure
+  result.clear
+end
+```
+
+`Client#prepare` returns only after the statement is ready on every currently
+live pipeline connection. Replacement connections automatically prepare the
+registered catalog before they begin accepting requests. The logical name is
+client-local; the gem uses private generated server names on its owned connections.
+
+Prepared handles are intentionally explicit rather than an unbounded automatic
+SQL cache. The SQL guard runs once at preparation time, while each execution
+still snapshots its bind values before submission.
+
 ### Transactions
 
 ```ruby
@@ -84,7 +113,7 @@ db.transaction do |tx|
 end
 ```
 
-### Session (DDL, LISTEN, SET, prepared statements)
+### Session (DDL, LISTEN, SET, connection-local prepared statements)
 
 ```ruby
 db.session do |s|
@@ -119,11 +148,12 @@ db.stats
 # => {
 #   pipeline: { size: 4, live: 4, drivers: [{load: 3, in_flight: 2, ...}, ...] },
 #   pinned:   { size: 2, active: 1, free: 1 },
+#   prepared_statements: 1,
 #   reconnects: 0
 # }
 ```
 
-`load` (pending + in_flight) per driver is the head-of-line signal.
+`load` (pending + in-flight + submitting + dispatching) per driver is the routing/head-of-line signal.
 
 ## Failure model
 

data/lib/pg_pipeline/client.rb

@@ -5,6 +5,7 @@ require "async"
 require_relative "errors"
 require_relative "pool"
 require_relative "request"
+require_relative "prepared_statement"
 require_relative "session_guard"
 require_relative "session"
 require_relative "transaction"
@@ -27,6 +28,7 @@ module PgPipeline
 
     def start(parent: Async::Task.current) = ClientOps.start(self, parent)
     def query(sql, params = []) = ClientOps.query(self, sql, params)
+    def prepare(name, sql, param_types = nil) = ClientOps.prepare(self, name, sql, param_types)
     def stats = ClientOps.stats(self)
 
     def session(&block)
@@ -71,11 +73,31 @@ module PgPipeline
 
     def query(client, sql, params)
       ensure_started!(client)
-      sql = sql.to_s
-      SessionGuard.assert_multiplexable!(sql, mode: client.guard)
+      sql = RequestOps.snapshot_sql(sql)
+      SessionGuard.assert_multiplexable_normalized!(sql, mode: client.guard)
 
-      request = submit_with_failover(client, sql, params)
+      wait_for_request do
+        submit_with_failover(client) { Request.new(sql: sql, params: params) }
+      end
+    end
+
+    def prepare(client, name, sql, param_types)
+      ensure_started!(client)
+      sql = RequestOps.snapshot_sql(sql)
+      SessionGuard.assert_multiplexable_normalized!(sql, mode: client.guard)
+      pool(client).__send__(:prepare_statement, client, name, sql, param_types)
+    end
+
+    def query_prepared(client, statement, params)
+      ensure_started!(client)
+
+      wait_for_request do
+        submit_with_failover(client) { Request.prepared_query(statement, params: params) }
+      end
+    end
 
+    def wait_for_request
+      request = yield
       begin
         request.wait
       ensure
@@ -85,13 +107,13 @@ module PgPipeline
 
     # NotDispatchedError is safe to retry on a fresh Request by contract.
     # ShutdownError is retried only while the current Request is still pre-dispatch.
-    def submit_with_failover(client, sql, params)
+    def submit_with_failover(client)
       attempts = 0
       limit = [pool(client).pipeline_size, 1].max
       last_error = nil
 
       while attempts < limit
-        request = Request.new(sql: sql, params: params)
+        request = yield
         begin
           pool(client).__send__(:pipeline_driver).submit(request)
           return request
@@ -144,16 +166,22 @@ module PgPipeline
       return unless started?(client)
 
       ensure_context!(client)
-      pool(client).graceful_close
-      client.__send__(:started=, false)
+      begin
+        pool(client).graceful_close
+      ensure
+        client.__send__(:started=, false) if pool(client).closing?
+      end
     end
 
     def abort!(client)
       return unless started?(client)
 
       ensure_context!(client)
-      pool(client).abort!
-      client.__send__(:started=, false)
+      begin
+        pool(client).abort!
+      ensure
+        client.__send__(:started=, false) if pool(client).closing?
+      end
     end
 
     def pool(client)

data/lib/pg_pipeline/connection_driver.rb

@@ -196,44 +196,46 @@ module PgPipeline
     end
 
     def owner_loop(d)
-      while d.running
-        event = d.events.dequeue
-
-        case event
-        when :requests
-          d.request_event_pending = false
-        when :submission_finished
-          nil
-        when :readable
-          begin
-            read_available(d)
-          ensure
-            d.reader_rearm.enqueue(:rearm) if d.running
-          end
-        when :writable
-          d.writer_armed = false
-          flush_output(d)
-        when :close
-          d.draining = true
-        when Array
-          tag, payload = event
-          if tag == :abort
-            fatal_close(d, payload)
-            break
-          end
-        end
-
-        drain_results(d)
-        pump_requests(d)
-        drain_results(d)
-        finish_graceful_close(d) if d.draining && drained?(d)
-      end
+      process_event(d, d.events.dequeue) while d.running
     rescue StandardError => e
       fatal_close(d, ConnectionLostError.new("driver crashed: #{e.class}: #{e.message}"))
     ensure
       fatal_close(d, ShutdownError.new("driver owner stopped before shutdown completed")) if d.running
     end
 
+    def process_event(d, event)
+      input_changed = false
+
+      case event
+      when :requests
+        d.request_event_pending = false
+      when :submission_finished
+        nil
+      when :readable
+        begin
+          read_available(d)
+          input_changed = true
+        ensure
+          d.reader_rearm.enqueue(:rearm) if d.running
+        end
+      when :writable
+        d.writer_armed = false
+        flush_output(d)
+      when :close
+        d.draining = true
+      when Array
+        tag, payload = event
+        if tag == :abort
+          fatal_close(d, payload)
+          return
+        end
+      end
+
+      drain_results(d) if input_changed
+      pump_requests(d) if d.running
+      finish_graceful_close(d) if d.running && d.draining && drained?(d)
+    end
+
     def notify_requests(d)
       return if d.request_event_pending
 
@@ -261,12 +263,12 @@ module PgPipeline
         dispatched = true
       end
 
-      flush_output(d) if dispatched || d.needs_flush
+      flush_output(d) if dispatched && !d.needs_flush
     end
 
     def send_unit(d, request)
       begin
-        d.conn.send_query_params(request.sql, request.params)
+        send_command(d.conn, request)
       rescue PG::UnableToSend => e
         d.dispatching = nil
         request.reject!(
@@ -281,9 +283,11 @@ module PgPipeline
           NotDispatchedError.new("query was rejected before libpq accepted it: #{e.class}: #{e.message}")
         )
         raise ConnectionLostError, "dispatch failed: #{e.class}: #{e.message}"
+      rescue ProtocolError
+        raise
       rescue StandardError => e
-        # ruby-pg prepares/encodes query parameters before calling PQsendQueryParams.
-        # A Ruby-side encoder/coercion exception therefore belongs only to this
+        # ruby-pg prepares/encodes query parameters before calling PQsend*. A
+        # Ruby-side encoder/coercion exception therefore belongs only to this
         # request and must not poison unrelated work already in the pipeline.
         request.reject!(e)
         return false
@@ -295,6 +299,23 @@ module PgPipeline
       raise ConnectionLostError, "dispatch Sync failed: #{e.class}: #{e.message}"
     end
 
+    def send_command(conn, request)
+      case request.operation
+      when :query
+        conn.send_query_params(request.sql, request.params)
+      when :prepare
+        if request.param_types.nil?
+          conn.send_prepare(request.statement_name, request.sql)
+        else
+          conn.send_prepare(request.statement_name, request.sql, request.param_types)
+        end
+      when :prepared_query
+        conn.send_query_prepared(request.statement_name, request.params)
+      else
+        raise ProtocolError, "unsupported request operation #{request.operation.inspect}"
+      end
+    end
+
     def reusable_after_send_rejection?(d)
       !d.conn.finished? &&
         d.conn.status == PG::CONNECTION_OK &&
@@ -325,7 +346,6 @@ module PgPipeline
 
     def read_available(d)
       d.conn.consume_input
-      drain_results(d)
     rescue PG::Error => e
       raise ConnectionLostError, "read failed: #{e.class}: #{e.message}"
     end
@@ -481,11 +501,17 @@ module PgPipeline
     end
 
     def stop_watchers(d)
-      d.reader_task&.stop
-      d.writer_task&.stop
+      reader = d.reader_task
+      writer = d.writer_task
       d.reader_task = nil
       d.writer_task = nil
-    rescue StandardError
+
+      [reader, writer].each do |task|
+        task&.stop
+      rescue Async::Cancel, StandardError
+        nil
+      end
+
       nil
     end
 

data/lib/pg_pipeline/errors.rb

@@ -10,6 +10,7 @@ module PgPipeline
   class IndeterminateResultError < ConnectionLostError; end
   class ShutdownError < Error; end
   class ProtocolError < Error; end
+  class RecursiveCheckoutError < Error; end
 
   class QueryError < Error
     attr_reader :cause_result

data/lib/pg_pipeline/pool.rb

@@ -7,6 +7,7 @@ require "async/notification"
 
 require_relative "errors"
 require_relative "connection_driver"
+require_relative "prepared_statement"
 require_relative "server_caps"
 
 module PgPipeline
@@ -18,6 +19,7 @@ module PgPipeline
     DEFAULT_HEALTH_INTERVAL = 10.0
     DEFAULT_HEALTH_TIMEOUT = 5.0
     DISCARD_SEQUENCES_SERVER_VERSION = 90_400
+    CANCEL_SIGNAL = Async::Cancel
 
     attr_reader :reconnects, :pipeline_size
 
@@ -39,11 +41,11 @@ module PgPipeline
       @max_pending = max_pending
       @max_in_flight = max_in_flight
       @reconnect = reconnect
-      @reconnect_interval = Float(reconnect_interval)
-      @reconnect_backoff_max = Float(reconnect_backoff_max)
+      @reconnect_interval = PoolOps.finite_float!(reconnect_interval, :reconnect_interval)
+      @reconnect_backoff_max = PoolOps.finite_float!(reconnect_backoff_max, :reconnect_backoff_max)
       @health_check = health_check
-      @health_interval = Float(health_interval)
-      @health_timeout = Float(health_timeout)
+      @health_interval = PoolOps.finite_float!(health_interval, :health_interval, allow_zero: true)
+      @health_timeout = PoolOps.finite_float!(health_timeout, :health_timeout)
       @cancel_pinned_on_abort = cancel_pinned_on_abort
 
       @drivers = []
@@ -55,6 +57,11 @@ module PgPipeline
       @health_failures = 0
       @supervisor_error = nil
       @supervisor = nil
+      @task_parent = nil
+
+      @prepared_statements = {}
+      @prepared_generation = 0
+      @statement_sequence = 0
 
       @pinned_free = []
       @pinned_in_use = {}
@@ -66,10 +73,17 @@ module PgPipeline
 
       @started = false
       @closing = false
+      @closed = false
     end
 
-    def start(parent: Async::Task.current)
+    def start(parent: nil)
       raise Error, "pool already started" if @started
+      if @closing || @closed
+        raise ShutdownError, "pool is closing or was closed and cannot be restarted; create a new Pool"
+      end
+
+      parent ||= Async::Task.current
+      @task_parent = parent
 
       begin
         @pipeline_size.times { @drivers << start_pipeline_driver(parent) }
@@ -77,13 +91,13 @@ module PgPipeline
         @driver_attempts = Array.new(@drivers.size, 0)
         @driver_last_health = Array.new(@drivers.size, monotonic)
         @pinned_gate = Async::Semaphore.new(@pinned_size) if @pinned_size.positive?
+        @started = true
+        @supervisor = parent.async { supervise } if @reconnect || @health_check
       rescue Exception
         cleanup_partial_start
         raise
       end
 
-      @started = true
-      @supervisor = parent.async { supervise } if @reconnect || @health_check
       self
     end
 
@@ -98,11 +112,72 @@ module PgPipeline
       driver
     end
 
+    def prepare_statement(client, name, sql, param_types)
+      ensure_available!
+      logical_name = PreparedStatementOps.snapshot_name(name)
+      if @prepared_statements.key?(logical_name)
+        raise Error, "prepared statement #{logical_name.inspect} already exists"
+      end
+
+      @statement_sequence += 1
+      statement = PreparedStatement.new(
+        client: client,
+        name: logical_name,
+        physical_name: "pgp_#{@statement_sequence.to_s(36)}",
+        sql: sql,
+        param_types: param_types
+      )
+
+      @prepared_statements[logical_name] = statement
+      @prepared_generation += 1
+      requests = []
+
+      begin
+        drivers = @drivers.select(&:available?)
+        if drivers.empty?
+          raise NotDispatchedError, "no live pipeline connections; statement was not prepared"
+        end
+
+        requests = drivers.map do |driver|
+          Request.prepare(statement).tap { |request| driver.submit(request) }
+        end
+
+        first_error = nil
+        requests.each do |request|
+          begin
+            RequestOps.clear_result(request.wait)
+          rescue StandardError => e
+            if first_error
+              e.clear_result! if e.respond_to?(:clear_result!)
+            else
+              first_error = e
+            end
+          end
+        end
+        raise first_error if first_error
+
+        statement
+      rescue Exception
+        if @prepared_statements.delete(logical_name)
+          @prepared_generation += 1
+        end
+        raise
+      ensure
+        requests.each { |request| request.cancel! unless request.settled? }
+      end
+    end
+
     def with_pinned
       ensure_available!
       raise @pinned_error if @pinned_error
       raise Error, "pinned pool is disabled (pinned_size=0)" if @pinned_size.zero?
 
+      if @pinned_owners[Async::Task.current].positive?
+        raise RecursiveCheckoutError,
+              "nested Client#session/transaction on the same task is not allowed; " \
+              "use Transaction#savepoint for nested atomicity"
+      end
+
       @pinned_gate.acquire do
         raise @pinned_error if @pinned_error
         raise ShutdownError, "pool is closing" if @closing
@@ -139,10 +214,12 @@ module PgPipeline
           free: @pinned_free.size,
           in_use: @pinned_in_use.size
         },
+        prepared_statements: (@prepared_statements || {}).size,
         reconnects: @reconnects,
         health_failures: @health_failures,
         supervisor_error: @supervisor_error&.message,
         closing: @closing,
+        closed: @closed,
         pinned_error: @pinned_error&.message
       }
     end
@@ -156,10 +233,24 @@ module PgPipeline
 
       @closing = true
       @started = false
-      stop_supervisor
-      @drivers.each(&:graceful_close)
-      wait_for_pinned_idle
-      close_free_pinned
+      first_error = nil
+
+      begin
+        first_error = preferred_shutdown_error(first_error, stop_supervisor)
+        first_error = preferred_shutdown_error(first_error, close_all_drivers(:graceful_close))
+
+        begin
+          wait_for_pinned_idle
+        rescue CANCEL_SIGNAL, StandardError => e
+          first_error = preferred_shutdown_error(first_error, e)
+        end
+      ensure
+        close_free_pinned
+        @closed = true
+      end
+
+      raise first_error if first_error
+
       nil
     end
 
@@ -168,31 +259,50 @@ module PgPipeline
 
       @closing = true
       @started = false
-      stop_supervisor
-      cancel_in_use_pinned if @cancel_pinned_on_abort
-      @drivers.each(&:abort!)
-      close_free_pinned
+      first_error = nil
+
+      begin
+        first_error = preferred_shutdown_error(first_error, stop_supervisor)
+        if @cancel_pinned_on_abort
+          first_error = preferred_shutdown_error(first_error, cancel_in_use_pinned)
+        end
+        first_error = preferred_shutdown_error(first_error, close_all_drivers(:abort!))
+      ensure
+        close_free_pinned
+        @closed = true
+      end
+
+      raise first_error if first_error
+
       nil
     end
 
     private
 
     def supervise
-      parent = Async::Task.current
       until @closing
         begin
-          reap_and_replace(parent) if @reconnect
+          reap_and_replace(@task_parent) if @reconnect
           health_probe if @health_check
           @supervisor_error = nil
         rescue StandardError => e
-          # Keep the loop alive: one probe/reconnect failure must not permanently
-          # disable health checks and replacement for the worker lifetime.
           @supervisor_error = e
         end
-        parent.sleep(@reconnect_interval)
+
+        break if @closing
+
+        sleep(supervisor_sleep_interval)
       end
     end
 
+    def supervisor_sleep_interval
+      candidates = []
+      candidates << @reconnect_interval if @reconnect
+      candidates << @health_interval if @health_check && @health_interval.positive?
+      interval = candidates.min || @reconnect_interval
+      interval.positive? ? interval : @reconnect_interval
+    end
+
     def reap_and_replace(parent)
       now = monotonic
       ensure_driver_slots!
@@ -242,32 +352,68 @@ module PgPipeline
     end
 
     def next_backoff(attempts)
-      delay = @reconnect_interval * (2**(attempts - 1))
-      delay < @reconnect_backoff_max ? delay : @reconnect_backoff_max
+      exponent = [Integer(attempts) - 1, 0].max
+      delay = @reconnect_interval * (2.0**exponent)
+      delay.finite? && delay < @reconnect_backoff_max ? delay : @reconnect_backoff_max
     end
 
     def cancel_in_use_pinned
+      cancellation = nil
+
       @pinned_in_use.keys.each do |conn|
         conn.cancel if conn.respond_to?(:cancel)
+      rescue CANCEL_SIGNAL => e
+        cancellation ||= e
       rescue StandardError
         nil
       end
+
+      cancellation
     end
 
     def stop_supervisor
-      @supervisor&.stop
+      supervisor = @supervisor
       @supervisor = nil
+      supervisor&.stop
+      nil
+    rescue CANCEL_SIGNAL => e
+      e
     rescue StandardError
       nil
     end
 
+    def close_all_drivers(method_name)
+      first_error = nil
+      cancellation = nil
+
+      @drivers.each do |driver|
+        begin
+          driver.public_send(method_name)
+        rescue CANCEL_SIGNAL => e
+          cancellation ||= e
+        rescue StandardError => e
+          first_error ||= e
+        end
+      end
+
+      cancellation || first_error
+    end
+
+    def preferred_shutdown_error(current, candidate)
+      return current unless candidate
+      return candidate if candidate.is_a?(CANCEL_SIGNAL)
+
+      current || candidate
+    end
+
     def ensure_available!
+      raise ShutdownError, "pool is closing or closed" if @closing || @closed
       raise Error, "pool not started" unless @started
-      raise ShutdownError, "pool is closing" if @closing
     end
 
     def start_pipeline_driver(parent)
       conn = PoolOps.new_connection(@connection_args)
+      prepare_registered_statements(conn)
       driver = ConnectionDriver.new(conn, max_pending: @max_pending, max_in_flight: @max_in_flight)
       driver.start(parent: parent)
     rescue Exception
@@ -275,6 +421,29 @@ module PgPipeline
       raise
     end
 
+    def prepare_registered_statements(conn)
+      prepared = {}
+
+      loop do
+        generation = @prepared_generation || 0
+        statements = (@prepared_statements || {}).values.dup
+
+        statements.each do |statement|
+          next if prepared.key?(statement.physical_name)
+
+          result = if statement.param_types.nil?
+                     conn.prepare(statement.physical_name, statement.sql)
+                   else
+                     conn.prepare(statement.physical_name, statement.sql, statement.param_types)
+                   end
+          RequestOps.clear_result(result)
+          prepared[statement.physical_name] = true
+        end
+
+        break if generation == (@prepared_generation || 0)
+      end
+    end
+
     def release_pinned(owner, conn)
       begin
         if conn
@@ -282,7 +451,14 @@ module PgPipeline
             PoolOps.safe_close(conn)
           else
             recycled = recycle_pinned_connection(conn)
-            @pinned_free << recycled if recycled
+
+            if recycled
+              if @closing
+                PoolOps.safe_close(recycled)
+              else
+                @pinned_free << recycled
+              end
+            end
           end
         end
       ensure
@@ -301,6 +477,9 @@ module PgPipeline
 
       PoolOps.sanitize_pinned_connection(conn)
       conn
+    rescue CANCEL_SIGNAL
+      PoolOps.safe_close(conn)
+      raise
     rescue StandardError => cleanup_error
       PoolOps.safe_close(conn)
 
@@ -322,13 +501,20 @@ module PgPipeline
     def cleanup_partial_start
       @drivers.each do |driver|
         driver.abort!
-      rescue StandardError
+      rescue CANCEL_SIGNAL, StandardError
         nil
       end
       @drivers.clear
+      @driver_backoff.clear
+      @driver_attempts.clear
+      @driver_last_health.clear
       close_free_pinned
+      @pinned_gate = nil
+      @supervisor = nil
+      @task_parent = nil
       @started = false
       @closing = false
+      @closed = false
     end
 
     def close_free_pinned
@@ -351,6 +537,17 @@ module PgPipeline
       raise ArgumentError, "#{name} must be an integer >= 1"
     end
 
+    def finite_float!(value, name, allow_zero: false)
+      number = Float(value)
+      bound_ok = allow_zero ? number >= 0 : number.positive?
+      raise ArgumentError unless number.finite? && bound_ok
+
+      number
+    rescue ArgumentError, TypeError
+      requirement = allow_zero ? "non-negative finite" : "positive finite"
+      raise ArgumentError, "#{name} must be a #{requirement} number (got #{value.inspect})"
+    end
+
     def nonnegative_integer!(value, name)
       integer = Integer(value)
       raise ArgumentError, "#{name} must be >= 0" if integer.negative?
@@ -361,32 +558,27 @@ module PgPipeline
     end
 
     def select_driver(drivers, rr)
-      min_load = nil
-      count = 0
-      drivers.each do |driver|
+      size = drivers.length
+      return [nil, rr] if size.zero?
+
+      best = nil
+      best_index = nil
+      best_load = nil
+
+      size.times do |offset|
+        index = (rr + offset) % size
+        driver = drivers[index]
         next unless driver.available?
 
         load = driver.load
-        if min_load.nil? || load < min_load
-          min_load = load
-          count = 1
-        elsif load == min_load
-          count += 1
+        if best.nil? || load < best_load
+          best = driver
+          best_index = index
+          best_load = load
         end
       end
-      return [nil, rr] if count.zero?
-
-      target = rr % count
-      index = 0
-      drivers.each do |driver|
-        next unless driver.available?
-        next unless driver.load == min_load
 
-        return [driver, rr + 1] if index == target
-
-        index += 1
-      end
-      [nil, rr]
+      best ? [best, (best_index + 1) % size] : [nil, rr]
     end
 
     def new_connection(connection_args)

data/lib/pg_pipeline/prepared_statement.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "request"
+
+module PgPipeline
+  class PreparedStatement
+    attr_reader :name, :sql, :param_types, :physical_name
+
+    def initialize(client:, name:, physical_name:, sql:, param_types: nil)
+      @client = client
+      @name = PreparedStatementOps.snapshot_name(name)
+      @physical_name = PreparedStatementOps.snapshot_name(physical_name)
+      @sql = RequestOps.snapshot_sql(sql)
+      @param_types = RequestOps.snapshot_param_types(param_types)
+      freeze
+    end
+
+    def query(params = []) = PreparedStatementOps.query(self, params)
+    alias call query
+
+    def inspect
+      "#<#{self.class} name=#{@name.inspect} sql=#{@sql.inspect}>"
+    end
+
+    private
+
+    attr_reader :client
+  end
+
+  module PreparedStatementOps
+    module_function
+
+    def query(statement, params)
+      ClientOps.query_prepared(statement.__send__(:client), statement, params)
+    end
+
+    def snapshot_name(name)
+      value = name.to_s
+      raise ArgumentError, "prepared statement name must not be empty" if value.empty?
+      raise ArgumentError, "prepared statement name must not contain NUL" if value.include?("\0")
+
+      value.frozen? ? value : value.dup.freeze
+    end
+
+  end
+end

data/lib/pg_pipeline/request.rb

@@ -11,7 +11,7 @@ module PgPipeline
                   :result, :error
 
     def initialize(sql:, params: nil)
-      @sql = sql.to_s.dup.freeze
+      @sql = RequestOps.snapshot_sql(sql)
       @params = RequestOps.snapshot_params(params)
       @state = :new
       @condition = Async::Notification.new
@@ -23,6 +23,14 @@ module PgPipeline
       @error = nil
     end
 
+    def self.prepare(statement) = PrepareRequest.new(statement)
+
+    def self.prepared_query(statement, params: nil)
+      PreparedQueryRequest.new(statement, params: params)
+    end
+
+    def operation = :query
+
     def queued! = RequestOps.transition!(self, :new, :queued)
     def dispatched! = RequestOps.transition!(self, :queued, :dispatched)
     def accept_result(result) = RequestOps.accept_result(self, result)
@@ -38,9 +46,37 @@ module PgPipeline
     def settled? = @settled
   end
 
+  class PrepareRequest < Request
+    attr_reader :statement_name, :param_types
+
+    def initialize(statement)
+      super(sql: statement.sql)
+      @statement_name = RequestOps.snapshot_name(statement.physical_name)
+      @param_types = RequestOps.snapshot_param_types(statement.param_types)
+    end
+
+    def operation = :prepare
+  end
+
+  class PreparedQueryRequest < Request
+    attr_reader :statement_name
+
+    def initialize(statement, params: nil)
+      super(sql: statement.sql, params: params)
+      @statement_name = RequestOps.snapshot_name(statement.physical_name)
+    end
+
+    def operation = :prepared_query
+  end
+
   module RequestOps
     module_function
 
+    def snapshot_sql(sql)
+      value = sql.to_s
+      value.frozen? ? value : value.dup.freeze
+    end
+
     def snapshot_params(params)
       values = params.nil? ? [] : params
       raise ArgumentError, "params must be an Array" unless values.is_a?(Array)
@@ -51,16 +87,32 @@ module PgPipeline
     def snapshot_value(value)
       case value
       when String
-        value.dup.freeze
+        value.frozen? ? value : value.dup.freeze
       when Hash
         value.each_with_object({}) do |(key, item), copy|
-          copy[key] = item.is_a?(String) ? item.dup.freeze : item
+          copy[key] = item.is_a?(String) && !item.frozen? ? item.dup.freeze : item
         end.freeze
       else
         value
       end
     end
 
+    def snapshot_name(name)
+      value = name.to_s
+      raise ArgumentError, "statement_name must not be empty" if value.empty?
+
+      value.frozen? ? value : value.dup.freeze
+    end
+
+    def snapshot_param_types(param_types)
+      return nil if param_types.nil?
+      raise ArgumentError, "param_types must be an Array or nil" unless param_types.is_a?(Array)
+
+      param_types.map { |oid| oid.nil? ? nil : Integer(oid) }.freeze
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "param_types must contain only integer OIDs or nil"
+    end
+
     def transition!(req, from, to)
       unless req.state == from
         raise ProtocolError, "invalid request transition #{req.state.inspect} -> #{to.inspect}"

data/lib/pg_pipeline/session.rb

@@ -13,7 +13,7 @@ module PgPipeline
     end
 
     def query(sql, params = []) = SessionOps.query(self, sql, params)
-    def exec(sql) = SessionOps.exec(self, sql)
+    def exec(sql, params = nil) = SessionOps.exec(self, sql, params)
     def prepare(name, sql, param_types = nil) = SessionOps.prepare(self, name, sql, param_types)
     def exec_prepared(name, params = []) = SessionOps.exec_prepared(self, name, params)
     def active? = @active
@@ -39,9 +39,13 @@ module PgPipeline
       connection(session).exec_params(sql, params)
     end
 
-    def exec(session, sql)
+    def exec(session, sql, params = nil)
       ensure_active!(session)
-      connection(session).exec(sql)
+      if params.nil?
+        connection(session).exec(sql)
+      else
+        connection(session).exec_params(sql, params)
+      end
     end
 
     def prepare(session, name, sql, param_types)

data/lib/pg_pipeline/session_guard.rb

@@ -30,7 +30,11 @@ module PgPipeline
     }.freeze
 
     def assert_multiplexable!(sql, mode: :default)
-      reason = unsafe_reason(sql, mode: mode)
+      assert_multiplexable_normalized!(sql, mode: normalize_mode!(mode))
+    end
+
+    def assert_multiplexable_normalized!(sql, mode:)
+      reason = unsafe_reason_normalized(sql, mode: mode)
       return true unless reason
 
       raise UnsafeMultiplexError,
@@ -43,9 +47,12 @@ module PgPipeline
     GUARD_CACHE_LIMIT = 2048
 
     def unsafe_reason(sql, mode: :default)
-      mode = normalize_mode!(mode)
+      unsafe_reason_normalized(sql, mode: normalize_mode!(mode))
+    end
+
+    def unsafe_reason_normalized(sql, mode:)
       key = sql.to_s
-      cache = guard_cache[mode]
+      cache = guard_cache.fetch(mode)
       return cache[key] if cache.key?(key)
 
       reason = compute_unsafe_reason(key, mode)

data/lib/pg_pipeline/transaction.rb

@@ -6,8 +6,6 @@ require_relative "session"
 
 module PgPipeline
   class Transaction < Session
-    attr_accessor :open, :savepoint_seq
-
     def initialize(conn)
       super
       @open = false
@@ -23,6 +21,10 @@ module PgPipeline
     end
 
     def open? = @open
+
+    private
+
+    attr_accessor :open, :savepoint_seq
   end
 
   module TransactionOps
@@ -30,19 +32,17 @@ module PgPipeline
 
     def run(tx)
       SessionOps.ensure_active!(tx)
-      raise Error, "transaction is already open" if tx.open
+      raise Error, "transaction is already open" if tx.open?
 
       conn = SessionOps.connection(tx)
       conn.exec("BEGIN")
-      tx.open = true
+      tx.__send__(:open=, true)
       begin
         result = yield tx
         conn.exec("COMMIT")
-        tx.open = false
+        tx.__send__(:open=, false)
         result
       rescue Exception
-        # Only roll back the transaction we opened. Early guard errors
-        # ("already open", inactive handle) must not hit this path.
         rollback_quietly(tx)
         raise
       end
@@ -50,11 +50,12 @@ module PgPipeline
 
     def savepoint(tx, name)
       SessionOps.ensure_active!(tx)
-      raise Error, "savepoint requires an open transaction" unless tx.open
+      raise Error, "savepoint requires an open transaction" unless tx.open?
 
       conn = SessionOps.connection(tx)
-      tx.savepoint_seq += 1
-      point = name || "pgp_sp_#{tx.savepoint_seq}"
+      seq = tx.__send__(:savepoint_seq) + 1
+      tx.__send__(:savepoint_seq=, seq)
+      point = name || "pgp_sp_#{seq}"
       ident = conn.quote_ident(point)
 
       conn.exec("SAVEPOINT #{ident}")
@@ -79,14 +80,14 @@ module PgPipeline
     end
 
     def rollback_quietly(tx)
-      return unless tx.open
+      return unless tx.open?
 
       conn = SessionOps.connection(tx)
       conn&.exec("ROLLBACK")
     rescue PG::Error
       nil
     ensure
-      tx.open = false
+      tx.__send__(:open=, false)
     end
   end
 end

data/lib/pg_pipeline/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PgPipeline
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 end

data/lib/pg_pipeline.rb

@@ -7,6 +7,7 @@ require_relative "pg_pipeline/session_guard"
 require_relative "pg_pipeline/session"
 require_relative "pg_pipeline/transaction"
 require_relative "pg_pipeline/request"
+require_relative "pg_pipeline/prepared_statement"
 require_relative "pg_pipeline/connection_driver"
 require_relative "pg_pipeline/pool"
 require_relative "pg_pipeline/client"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_pipeline
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Roman Hajdarov
@@ -121,6 +121,7 @@ files:
 - lib/pg_pipeline/connection_driver.rb
 - lib/pg_pipeline/errors.rb
 - lib/pg_pipeline/pool.rb
+- lib/pg_pipeline/prepared_statement.rb
 - lib/pg_pipeline/request.rb
 - lib/pg_pipeline/server_caps.rb
 - lib/pg_pipeline/session.rb