pg_pipeline 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7135257ec52d199f4a7e0d3666909eebd8effa277f7efe80d27ca8ff00717f93
-  data.tar.gz: 8f3b976cc4b9f8400439a1504bbad9a019865a88a7f41e6556907ba649587c80
+  metadata.gz: 9bc5e0b7e4d8a274bc84e16fc7205774f0c20a0d4b2ee2ed9482a676eb15b986
+  data.tar.gz: fd0f6c75af1815f9574b2133caff20c092db8f45f4ee04085bf975f51be231e0
 SHA512:
-  metadata.gz: 90422fd9a948509c2e53b9058d052a822e76f303a736a39488a0870b6fa903d6c1b2b8248e00649269a63ed606a9a8d04b1c2c081cf0f2b89e81000af8a36e54
-  data.tar.gz: fa76f361560fa078903685d69de81600b8337509b8f37b89cd93fdfdc71ebc3953180edf8487b4aa24d79d521237ef98bc727cde48ca959acb41c0d589749999
+  metadata.gz: 3a284e77a674fc31d6e1b0263ff32cd254814f8f535e84060227e30d5e7ffe284b104dc764dfb9cd9062dc4f56b5319b088d9649ff6213e60498775806930637
+  data.tar.gz: fa814de3830232f0f9136d3f582917bd91c426fc540f1d4cc19ded4872eb9eed4d45f936738d35f34c9377beb6057fe9e4c204b413f1654aa31b3d431e2c3266

data/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## [0.2.5] - 2026-08-03
+
+Control-plane cleanup on the multiplexed query path: fewer per-query allocations,
+a cheaper session-guard fast path, slightly tighter result drain, and driver
+fill metrics. Wire behaviour and the public API are unchanged.
+
+### Performance
+
+- `SessionGuard` skips comment/literal masking when the SQL has no quotes,
+  comments or dollar-quotes; skips the forbidden-pattern scan when the SQL has
+  neither `(` nor `into`; and uses a byte scan for multi-statement detection.
+- `Request.build` / `PreparedQueryRequest.build` avoid keyword `Class#new` hash
+  allocation on the hot path.
+- `RequestOps.snapshot_params` reuses a shared frozen empty array and skips
+  copying frozen immutable param arrays.
+- Default query params use that empty frozen array instead of allocating `[]`
+  per call (`Client`, `Session`, `PreparedStatement`).
+- `PoolOps.select_driver_into` writes the round-robin cursor into a pool-owned
+  slot instead of allocating a `[driver, cursor]` pair per selection.
+- `drain_results` matches hot statuses (`TUPLES_OK`, `PIPELINE_SYNC`) first and
+  accumulates `results_read` once per drain.
+
+### Observability
+
+- Driver stats add `fast_sync`, `units_per_readable`, `results_per_readable`,
+  `flush_calls`, `flush_incomplete`, `dispatches`, and `flush_calls_per_unit`.
+- One process-level warning on libpq older than 17 when Sync is coupled to flush
+  (`PG_PIPELINE_SILENCE_WARNINGS=1` to suppress).
+
+### Reliability
+
+- Round-robin cursor is normalised with `rr % size` when past the pool length.
+- Driver metric readers default to zero if ivars are unset.
+
+### Tests
+
+- Guard fast-path / masking / cache eviction coverage.
+- `Request.build` equivalence and prepared-query build coverage.
+- Randomised driver-selection vs reference algorithm.
+- Drain counter write-back when the loop raises.
+
+## [0.2.4] - 2026-07-31
+
+Request-completion allocation patch. It replaces the general-purpose
+`Async::Notification` attached to every multiplexed request with a direct
+single-waiter fiber handoff while preserving deferred reactor wakeups and the
+existing SQL, Sync, result and failure semantics.
+
+### Performance
+
+- A request now stores only the waiting fiber and its originating scheduler.
+  `Scheduler#block` parks that fiber and `Scheduler#unblock` schedules only that
+  waiter on a later reactor turn.
+- Removed the per-request `Async::Notification` and its initial
+  `Thread::Queue`; when a waiter is present, completion also avoids the
+  replacement queue and `Async::Notification::Signal` allocation.
+- The optimization is limited to one-shot request completion. Bounded-queue and
+  pinned-pool notifications retain `Async::Notification` because they require
+  multi-waiter coordination.
+
+### Reliability
+
+- Completion-before-wait still returns immediately through the settled guard, so
+  no wakeup can be lost.
+- Timeout or task cancellation clears the stored waiter in an `ensure`, preventing
+  a late query completion from retaining or waking an abandoned fiber.
+- A second concurrent waiter is rejected explicitly instead of silently replacing
+  the first waiter.
+- The scheduler associated with the waiting fiber is stored and used for the
+  matching unblock rather than looking up an implicit current scheduler at
+  completion time.
+- Added focused coverage for wait-before-completion, completion after an
+  interrupted wait, the single-waiter invariant and already-settled waits outside
+  an active scheduler.
+
 ## [0.2.3] - 2026-07-30
 
 Performance-focused release based on CPU profiles from the live pipeline

data/DESIGN.md

@@ -126,7 +126,7 @@ 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
+generated name until that connection is replaced or closed. Version 0.2.3 and later do
 not expose `DEALLOCATE` for multiplexed handles. Server-side plan invalidation is
 reported as the ordinary request-local `QueryError`.
 
@@ -221,15 +221,64 @@ without reset would leak that state to the next caller. After each pinned block:
 
 Immediately resuming a waiter from inside the connection owner is unsafe: a
 resumed caller could re-enter the driver (submit, or close the client and wait on
-the owner) while the owner is mid-`signal`. Internal wait/notify points therefore
-use `Async::Notification`, which resumes waiters on a later reactor turn, avoiding
-reentrancy into the owner. The same rule applies to request completion,
-bounded-queue backpressure and pinned-pool idle notifications.
+the owner) while the owner is still completing the current pipeline unit.
+
+A `Request` has exactly one consumer, so request completion stores that waiter
+fiber and its scheduler directly. `Scheduler#block` parks it, and
+`Scheduler#unblock` pushes it onto the selector for a later reactor turn. This
+preserves deferred wakeup without allocating a general-purpose
+`Async::Notification` and its queue objects for every query. The settled flag
+handles completion-before-wait, and an `ensure` removes a waiter interrupted by
+timeout or task cancellation before a late result can try to wake it.
+
+Multi-waiter coordination points still use `Async::Notification`: bounded-queue
+backpressure and pinned-pool idle notifications need queue/broadcast semantics
+that the request-specific one-shot waiter deliberately does not provide.
 
 > Note: the supported Async range starts at 2.42 and stays below 3. The lockfile
 > exercises the current compatible 2.x release, while CI separately runs the unit
-> suite against the exact 2.42.0 floor so this coordination behavior is not merely
-> assumed from a broad pessimistic dependency range.
+> suite against the exact 2.42.0 floor so `Scheduler#block`/`#unblock` behavior is
+> not merely assumed from a broad pessimistic dependency range.
+
+## 10a. Guard evaluation shape
+
+`SessionGuard` validates the session-neutral SQL contract of §6 before a query is
+allowed onto the shared path, so its cost lands on the reactor thread and its
+stalls are visible in every other fiber's latency, not just the caller's.
+
+Evaluation is therefore staged so that the expensive stage runs only when it can
+change the answer:
+
+1. **Masking is skipped when it is provably an identity transform.** `code_only`
+   blanks string literals, quoted identifiers, comments and dollar-quoted bodies.
+   If none of `'`, `"`, `--`, `/*` or a `$tag$` delimiter appears in the SQL,
+   there is nothing to blank and the raw SQL is validated directly.
+2. **The forbidden-pattern scan is skipped when no pattern can match.** Every
+   pattern in `FORBIDDEN_PATTERNS` and `STRICT_FORBIDDEN` is anchored on either a
+   parenthesis or the word `into`, so SQL containing neither cannot match any of
+   them.
+3. **Verdicts are cached by SQL string**, and the cache evicts a single oldest
+   entry at its limit. Clearing the whole cache would turn one insertion into a
+   full recompute for every subsequent statement.
+
+Stage 1 and stage 2 are correctness-preserving only as long as their premises
+hold. Both are asserted in `spec/pg_pipeline/session_guard_fast_path_spec.rb`;
+**adding a pattern that is not anchored on `(` or `into` requires updating the
+prefilter in the same change.**
+
+Masking is deliberately monotone in the wrong direction to be reordered: blanking
+a comment can *create* a match (`nextval/* c */('s')` becomes `nextval      ('s')`),
+so the raw SQL can never be used as a negative filter for stage 2. Only the
+absence of maskable syntax justifies skipping stage 1.
+
+## 10b. Fill observability
+
+Pipelining pays off only when one reactor wakeup is amortised over several units.
+`ConnectionDriver#stats` therefore reports `units_per_readable` (and related
+counters) alongside the queue depths. A value near 1.0 means each query costs a
+full socket wait and a scheduler round trip, which bounds throughput
+independently of control-plane work; values well above 1.0 mean the pipeline is
+filling. Read this number before attributing throughput to Ruby-side cost.
 
 ## 11. Version policy
 

data/README.md

@@ -40,6 +40,14 @@ gem "pg_pipeline"
 
 Requires Ruby ≥ 3.3, `async ~> 2.42`, `pg ≥ 1.5`, and **libpq ≥ 14** at runtime.
 
+**libpq ≥ 17 is recommended for maximum local throughput.** Below 17 there is no
+`PQsendPipelineSync`, so `PQpipelineSync` couples Sync with a flush and the driver
+cannot batch writes across a dispatch burst. Correctness is identical and RTT
+amortisation — the main reason to pipeline — still works on libpq 14; only local
+throughput is capped. The driver detects this at connect time and warns once per
+process; set `PG_PIPELINE_SILENCE_WARNINGS=1` to suppress it, and check
+`db.stats[:pipeline][:drivers].first[:fast_sync]` to see which path is active.
+
 ## Usage
 
 ### Multiplexed queries
@@ -155,6 +163,49 @@ db.stats
 
 `load` (pending + in-flight + submitting + dispatching) per driver is the routing/head-of-line signal.
 
+Each driver also reports how well the pipeline is filling:
+
+```ruby
+db.stats[:pipeline][:drivers].first
+# => { ..., fast_sync: true,
+#      units_per_readable: 7.9, results_per_readable: 22.2,
+#      flush_calls_per_unit: 0.17, flush_incomplete: 0 }
+```
+
+`units_per_readable` is the number to watch. Around `1.0` means every query pays a
+full socket wait plus scheduler round trip and the pipeline is not filling — that is
+the expected shape for a single fiber issuing one query at a time, and no amount of
+Ruby-side optimisation will change it. Values well above `1.0` mean one reactor
+wakeup is amortised over many queries, which is the regime pipelining is for. Check
+this before attributing a throughput number to control-plane cost.
+
+The numbers above are from a saturated HTTP benchmark (4 workers, 4 connections
+each, ~20k requests/second against a local server): roughly eight queries per
+reactor wakeup and one flush per six queries. `results_per_readable` runs at
+three times `units_per_readable` because a completed unit yields three protocol
+results -- the data, the query boundary and the Sync.
+
+## Head-of-line blocking
+
+Results on a pipelined connection arrive in FIFO order, and PostgreSQL offers no
+safe way to cancel one request out of a multiplexed pipeline (see `DESIGN.md` §7).
+Two consequences worth designing around:
+
+- **A slow query delays everything behind it on the same connection.** With the
+  default `max_in_flight: 64`, one multi-second query can hold up to 63 unrelated
+  queries on that driver. Driver selection balances by queue depth, not by expected
+  cost, so a slow query counts the same as a fast one.
+- **A timeout is not a cancellation.** Wrapping `db.query` in `with_timeout` returns
+  control to your fiber, but the unit stays in the pipeline until the server answers
+  it, and the requests behind it still wait.
+
+If your workload mixes fast and slow queries, prefer one of:
+
+- lower `max_in_flight` so a stall cannot capture a deep queue;
+- a second `Client` with its own connections for the slow queries;
+- `Client#session` for anything long-running, which uses an exclusive pinned
+  connection and cannot block multiplexed traffic.
+
 ## Failure model
 
 | Error | Meaning | Retry safe? |
@@ -187,6 +238,8 @@ See `examples/falcon_config.ru` for a complete setup.
 
 ## Benchmark
 
+[Performance test results and methodology](docs/PERFORMANCE.md).
+
 ```bash
 docker compose up -d pg17
 export PG_PIPELINE_URL=postgres://postgres:postgres@127.0.0.1:5417/postgres

data/lib/pg_pipeline/client.rb

@@ -27,7 +27,7 @@ module PgPipeline
     end
 
     def start(parent: Async::Task.current) = ClientOps.start(self, parent)
-    def query(sql, params = []) = ClientOps.query(self, sql, params)
+    def query(sql, params = RequestOps::EMPTY_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)
 
@@ -77,7 +77,7 @@ module PgPipeline
       SessionGuard.assert_multiplexable_normalized!(sql, mode: client.guard)
 
       wait_for_request do
-        submit_with_failover(client) { Request.new(sql: sql, params: params) }
+        submit_with_failover(client) { Request.build(sql, params) }
       end
     end
 
@@ -105,8 +105,6 @@ module PgPipeline
       end
     end
 
-    # 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)
       attempts = 0
       limit = [pool(client).pipeline_size, 1].max

data/lib/pg_pipeline/connection_driver.rb

@@ -20,6 +20,16 @@ module PgPipeline
                   :draining, :needs_flush, :writer_armed, :request_event_pending,
                   :owner_task, :reader_task, :writer_task
 
+    attr_writer :readable_events, :results_read, :units_completed, :flush_calls,
+                :flush_incomplete, :dispatches
+
+    def readable_events = @readable_events || 0
+    def results_read = @results_read || 0
+    def units_completed = @units_completed || 0
+    def flush_calls = @flush_calls || 0
+    def flush_incomplete = @flush_incomplete || 0
+    def dispatches = @dispatches || 0
+
     def initialize(conn, max_pending: DEFAULT_MAX_PENDING, max_in_flight: DEFAULT_MAX_IN_FLIGHT)
       @max_pending = DriverOps.positive_integer!(max_pending, :max_pending)
       @max_in_flight = DriverOps.positive_integer!(max_in_flight, :max_in_flight)
@@ -27,6 +37,7 @@ module PgPipeline
       @conn = conn
       @caps = ServerCaps.from_connection(conn)
       @caps.assert_supported!
+      DriverOps.warn_flush_coupling_once(@caps)
 
       @requests = BoundedQueue.new(@max_pending)
       @events = Async::Queue.new
@@ -44,6 +55,13 @@ module PgPipeline
       @writer_armed = false
       @request_event_pending = false
 
+      @readable_events = 0
+      @results_read = 0
+      @units_completed = 0
+      @flush_calls = 0
+      @flush_incomplete = 0
+      @dispatches = 0
+
       @socket = nil
       @owner_task = nil
       @reader_task = nil
@@ -63,14 +81,24 @@ module PgPipeline
         pending: @requests.size,
         in_flight: @inflight.size,
         submitting: @submitting,
-        needs_flush: @needs_flush
+        needs_flush: @needs_flush,
+        fast_sync: @caps.fast_sync?,
+        readable_events: readable_events,
+        results_read: results_read,
+        units_completed: units_completed,
+        flush_calls: flush_calls,
+        flush_incomplete: flush_incomplete,
+        dispatches: dispatches,
+        units_per_readable: DriverOps.ratio(units_completed, readable_events),
+        results_per_readable: DriverOps.ratio(results_read, readable_events),
+        flush_calls_per_unit: DriverOps.ratio(flush_calls, units_completed)
       }
     end
 
     def health_check(timeout)
       return true unless available?
 
-      probe = Request.new(sql: "SELECT 1", params: [])
+      probe = Request.build("SELECT 1", nil)
       begin
         submit(probe)
         Async::Task.current.with_timeout(timeout) { probe.wait }
@@ -98,17 +126,25 @@ module PgPipeline
   module DriverOps
     module_function
 
-    SUCCESS_STATUSES = [
-      PG::PGRES_EMPTY_QUERY,
-      PG::PGRES_COMMAND_OK,
-      PG::PGRES_TUPLES_OK
-    ].freeze
+    def ratio(numerator, denominator)
+      return 0.0 if denominator.zero?
+
+      (numerator.to_f / denominator).round(3)
+    end
+
+    def warn_flush_coupling_once(caps)
+      return if @flush_coupling_warned
+      return if caps.fast_sync?
+      return if ENV["PG_PIPELINE_SILENCE_WARNINGS"]
 
-    COPY_STATUSES = [
-      PG::PGRES_COPY_IN,
-      PG::PGRES_COPY_OUT,
-      PG::PGRES_COPY_BOTH
-    ].freeze
+      @flush_coupling_warned = true
+      warn(
+        "pg_pipeline: libpq #{caps.libpq_version} couples pipeline Sync with flush " \
+        "(no PQsendPipelineSync). Queries still pipeline and still amortise RTT, but " \
+        "one flush per unit caps local throughput; libpq >= 17 is recommended for " \
+        "maximum throughput. Set PG_PIPELINE_SILENCE_WARNINGS=1 to silence this."
+      )
+    end
 
     def positive_integer!(value, name)
       integer = Integer(value)
@@ -213,6 +249,7 @@ module PgPipeline
         nil
       when :readable
         begin
+          d.readable_events += 1
           read_available(d)
           input_changed = true
         ensure
@@ -260,6 +297,7 @@ module PgPipeline
         request.dispatched!
         d.inflight << request
         d.dispatching = nil
+        d.dispatches += 1
         dispatched = true
       end
 
@@ -286,9 +324,6 @@ module PgPipeline
       rescue ProtocolError
         raise
       rescue StandardError => e
-        # 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
       end
@@ -327,10 +362,13 @@ module PgPipeline
     def flush_output(d)
       return unless d.running
 
+      d.flush_calls += 1
+
       if d.conn.sync_flush
         d.needs_flush = false
       else
         d.needs_flush = true
+        d.flush_incomplete += 1
         arm_writer(d)
       end
     rescue PG::Error => e
@@ -351,42 +389,52 @@ module PgPipeline
     end
 
     def drain_results(d)
-      while !d.inflight.empty? && !d.conn.is_busy
-        result = d.conn.sync_get_result
-        request = d.inflight.first
-        raise ProtocolError, "result without an in-flight request" unless request
-
-        if result.nil?
-          request.query_boundary!
-          next
-        end
+      read = 0
 
-        status = result.result_status
-
-        case status
-        when PG::PGRES_PIPELINE_SYNC
-          clear_result(result)
-          complete_front(d, request)
-        when PG::PGRES_PIPELINE_ABORTED
-          ensure_before_query_boundary!(request, status)
-          clear_result(result)
-          request.record_error!(PipelineAbortedError.new("pipeline unit aborted"))
-        when PG::PGRES_BAD_RESPONSE
-          clear_result(result)
-          raise ProtocolError, "server response was not understood"
-        when PG::PGRES_FATAL_ERROR
-          ensure_before_query_boundary!(request, status)
-          request.record_error!(query_error(result), result: result)
-        when *COPY_STATUSES
-          clear_result(result)
-          raise ProtocolError, "COPY is not supported on the multiplexed pipeline"
-        when *SUCCESS_STATUSES
-          ensure_before_query_boundary!(request, status)
-          request.accept_result(result)
-        else
-          clear_result(result)
-          raise ProtocolError, "unexpected pipeline result status #{status}"
+      begin
+        while !d.inflight.empty? && !d.conn.is_busy
+          result = d.conn.sync_get_result
+          read += 1
+          request = d.inflight.first
+          raise ProtocolError, "result without an in-flight request" unless request
+
+          if result.nil?
+            request.query_boundary!
+            next
+          end
+
+          status = result.result_status
+
+          case status
+          when PG::PGRES_TUPLES_OK
+            ensure_before_query_boundary!(request, status)
+            request.accept_result(result)
+          when PG::PGRES_PIPELINE_SYNC
+            clear_result(result)
+            complete_front(d, request)
+          when PG::PGRES_COMMAND_OK, PG::PGRES_EMPTY_QUERY
+            ensure_before_query_boundary!(request, status)
+            request.accept_result(result)
+          when PG::PGRES_FATAL_ERROR
+            ensure_before_query_boundary!(request, status)
+            request.record_error!(query_error(result), result: result)
+          when PG::PGRES_PIPELINE_ABORTED
+            ensure_before_query_boundary!(request, status)
+            clear_result(result)
+            request.record_error!(PipelineAbortedError.new("pipeline unit aborted"))
+          when PG::PGRES_BAD_RESPONSE
+            clear_result(result)
+            raise ProtocolError, "server response was not understood"
+          when PG::PGRES_COPY_IN, PG::PGRES_COPY_OUT, PG::PGRES_COPY_BOTH
+            clear_result(result)
+            raise ProtocolError, "COPY is not supported on the multiplexed pipeline"
+          else
+            clear_result(result)
+            raise ProtocolError, "unexpected pipeline result status #{status}"
+          end
         end
+      ensure
+        d.results_read += read if read.positive?
       end
     end
 
@@ -400,6 +448,7 @@ module PgPipeline
       raise ProtocolError, "sync does not match FIFO front" unless request.equal?(d.inflight.first)
 
       d.inflight.shift
+      d.units_completed += 1
       request.finish!
     end
 

data/lib/pg_pipeline/pool.rb

@@ -53,6 +53,7 @@ module PgPipeline
       @driver_attempts = []
       @driver_last_health = []
       @rr = 0
+      @rr_slot = [0]
       @reconnects = 0
       @health_failures = 0
       @supervisor_error = nil
@@ -106,7 +107,8 @@ module PgPipeline
     def pipeline_driver
       ensure_available!
 
-      driver, @rr = PoolOps.select_driver(@drivers, @rr)
+      driver = PoolOps.select_driver_into(@drivers, @rr, @rr_slot)
+      @rr = @rr_slot[0]
       raise NotDispatchedError, "no live pipeline connections; request was not dispatched" unless driver
 
       driver
@@ -557,28 +559,42 @@ module PgPipeline
       raise ArgumentError, "#{name} must be an integer >= 0"
     end
 
-    def select_driver(drivers, rr)
+    def select_driver_into(drivers, rr, slot)
       size = drivers.length
-      return [nil, rr] if size.zero?
+      if size.zero?
+        slot[0] = rr
+        return nil
+      end
 
+      start = rr % size
       best = nil
-      best_index = nil
-      best_load = nil
+      best_index = 0
+      best_load = 0
+      offset = 0
 
-      size.times do |offset|
-        index = (rr + offset) % size
+      while offset < size
+        index = start + offset
+        index -= size if index >= size
         driver = drivers[index]
+        offset += 1
         next unless driver.available?
 
         load = driver.load
-        if best.nil? || load < best_load
-          best = driver
-          best_index = index
-          best_load = load
-        end
+        next unless best.nil? || load < best_load
+
+        best = driver
+        best_index = index
+        best_load = load
       end
 
-      best ? [best, (best_index + 1) % size] : [nil, rr]
+      slot[0] = best ? (best_index + 1) % size : rr
+      best
+    end
+
+    def select_driver(drivers, rr)
+      slot = [rr]
+      driver = select_driver_into(drivers, rr, slot)
+      [driver, slot[0]]
     end
 
     def new_connection(connection_args)

data/lib/pg_pipeline/prepared_statement.rb

@@ -16,7 +16,7 @@ module PgPipeline
       freeze
     end
 
-    def query(params = []) = PreparedStatementOps.query(self, params)
+    def query(params = RequestOps::EMPTY_PARAMS) = PreparedStatementOps.query(self, params)
     alias call query
 
     def inspect

data/lib/pg_pipeline/request.rb

@@ -1,32 +1,37 @@
 # frozen_string_literal: true
 
-require "async/notification"
-
 require_relative "errors"
 
 module PgPipeline
   class Request
-    attr_reader :sql, :params, :condition
+    attr_reader :sql, :params
     attr_accessor :state, :cancelled, :settled, :result_seen, :query_boundary_seen,
-                  :result, :error
+                  :result, :error, :waiter, :waiter_scheduler
 
     def initialize(sql:, params: nil)
       @sql = RequestOps.snapshot_sql(sql)
       @params = RequestOps.snapshot_params(params)
       @state = :new
-      @condition = Async::Notification.new
       @cancelled = false
       @settled = false
       @result_seen = false
       @query_boundary_seen = false
       @result = nil
       @error = nil
+      @waiter = nil
+      @waiter_scheduler = nil
+    end
+
+    def self.build(sql, params)
+      request = allocate
+      request.__send__(:init_query, sql, params)
+      request
     end
 
     def self.prepare(statement) = PrepareRequest.new(statement)
 
     def self.prepared_query(statement, params: nil)
-      PreparedQueryRequest.new(statement, params: params)
+      PreparedQueryRequest.build(statement, params)
     end
 
     def operation = :query
@@ -44,6 +49,23 @@ module PgPipeline
     def query_boundary_seen? = @query_boundary_seen
     def cancelled? = @cancelled
     def settled? = @settled
+
+    private
+
+    def init_query(sql, params)
+      @sql = RequestOps.snapshot_sql(sql)
+      @params = RequestOps.snapshot_params(params)
+      @state = :new
+      @cancelled = false
+      @settled = false
+      @result_seen = false
+      @query_boundary_seen = false
+      @result = nil
+      @error = nil
+      @waiter = nil
+      @waiter_scheduler = nil
+      self
+    end
   end
 
   class PrepareRequest < Request
@@ -66,7 +88,21 @@ module PgPipeline
       @statement_name = RequestOps.snapshot_name(statement.physical_name)
     end
 
+    def self.build(statement, params)
+      request = allocate
+      request.__send__(:init_prepared, statement, params)
+      request
+    end
+
     def operation = :prepared_query
+
+    private
+
+    def init_prepared(statement, params)
+      init_query(statement.sql, params)
+      @statement_name = RequestOps.snapshot_name(statement.physical_name)
+      self
+    end
   end
 
   module RequestOps
@@ -77,11 +113,34 @@ module PgPipeline
       value.frozen? ? value : value.dup.freeze
     end
 
+    EMPTY_PARAMS = [].freeze
+
     def snapshot_params(params)
-      values = params.nil? ? [] : params
-      raise ArgumentError, "params must be an Array" unless values.is_a?(Array)
+      return EMPTY_PARAMS if params.nil?
+      raise ArgumentError, "params must be an Array" unless params.is_a?(Array)
+      return EMPTY_PARAMS if params.empty?
+
+      return params if params.frozen? && immutable_values?(params)
 
-      values.map { |value| snapshot_value(value) }.freeze
+      params.map { |value| snapshot_value(value) }.freeze
+    end
+
+    def immutable_values?(values)
+      index = 0
+      size = values.size
+      while index < size
+        value = values[index]
+        case value
+        when Integer, Float, Symbol, NilClass, TrueClass, FalseClass
+          nil
+        when String
+          return false unless value.frozen?
+        else
+          return false
+        end
+        index += 1
+      end
+      true
     end
 
     def snapshot_value(value)
@@ -156,7 +215,7 @@ module PgPipeline
 
       req.settled = true
       req.state = :done
-      req.condition.signal unless req.cancelled
+      wake_waiter(req) unless req.cancelled
     end
 
     def reject!(req, error)
@@ -167,7 +226,7 @@ module PgPipeline
       req.error ||= error
       req.settled = true
       req.state = :done
-      req.condition.signal unless req.cancelled
+      wake_waiter(req) unless req.cancelled
     end
 
     def cancel!(req)
@@ -180,12 +239,42 @@ module PgPipeline
     end
 
     def wait(req)
-      req.condition.wait unless req.settled
+      park_waiter(req) unless req.settled
       raise req.error if req.error
 
       req.result
     end
 
+    def park_waiter(req)
+      raise ProtocolError, "request already has a waiter" if req.waiter
+
+      scheduler = Fiber.scheduler
+      raise Error, "request wait requires an active Fiber scheduler" unless scheduler
+
+      waiter = Fiber.current
+      req.waiter = waiter
+      req.waiter_scheduler = scheduler
+
+      begin
+        scheduler.block(req, nil) until req.settled
+      ensure
+        if req.waiter.equal?(waiter)
+          req.waiter = nil
+          req.waiter_scheduler = nil
+        end
+      end
+    end
+
+    def wake_waiter(req)
+      waiter = req.waiter
+      scheduler = req.waiter_scheduler
+
+      req.waiter = nil
+      req.waiter_scheduler = nil
+
+      scheduler.unblock(req, waiter) if scheduler && waiter
+    end
+
     def assert_result_slot!(req)
       raise ProtocolError, "result arrived after query boundary" if req.query_boundary_seen
       raise ProtocolError, "multiple results for one pipeline unit" if req.result_seen

data/lib/pg_pipeline/session.rb

@@ -4,6 +4,8 @@ require_relative "errors"
 
 module PgPipeline
   class Session
+    EMPTY_PARAMS = [].freeze
+
     attr_reader :owner_fiber
 
     def initialize(conn)
@@ -12,10 +14,10 @@ module PgPipeline
       @owner_fiber = Fiber.current
     end
 
-    def query(sql, params = []) = SessionOps.query(self, sql, params)
+    def query(sql, params = EMPTY_PARAMS) = SessionOps.query(self, sql, params)
     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 exec_prepared(name, params = EMPTY_PARAMS) = SessionOps.exec_prepared(self, name, params)
     def active? = @active
 
     private

data/lib/pg_pipeline/session_guard.rb

@@ -29,6 +29,11 @@ module PgPipeline
       "pg_export_snapshot" => /\bpg_export_snapshot\s*\(/i
     }.freeze
 
+    PATTERN_PREFILTER = /\binto\b/i
+    NEEDS_MASK = /['"]|--|\/\*|\$[A-Za-z_0-9]*\$/
+    LEADING_KEYWORD = /\A\s*([a-zA-Z_]+)/
+    WHITESPACE_BYTES = [9, 10, 11, 12, 13, 32].freeze
+
     def assert_multiplexable!(sql, mode: :default)
       assert_multiplexable_normalized!(sql, mode: normalize_mode!(mode))
     end
@@ -45,6 +50,7 @@ module PgPipeline
     end
 
     GUARD_CACHE_LIMIT = 2048
+    SAFE = :safe
 
     def unsafe_reason(sql, mode: :default)
       unsafe_reason_normalized(sql, mode: normalize_mode!(mode))
@@ -53,11 +59,12 @@ module PgPipeline
     def unsafe_reason_normalized(sql, mode:)
       key = sql.to_s
       cache = guard_cache.fetch(mode)
-      return cache[key] if cache.key?(key)
+      cached = cache[key]
+      return (cached.equal?(SAFE) ? nil : cached) if cached
 
       reason = compute_unsafe_reason(key, mode)
-      cache.clear if cache.size >= GUARD_CACHE_LIMIT
-      cache[key] = reason
+      cache.shift if cache.size >= GUARD_CACHE_LIMIT
+      cache[key] = reason || SAFE
       reason
     end
 
@@ -66,12 +73,13 @@ module PgPipeline
     end
 
     def compute_unsafe_reason(sql, mode)
-      code = code_only(sql)
-      lead = code[/\A\s*([a-zA-Z_]+)/, 1]&.downcase
+      code = NEEDS_MASK.match?(sql) ? code_only(sql) : sql
+      lead = code[LEADING_KEYWORD, 1]&.downcase
 
       return "empty" unless lead
       return "leading:#{lead}" unless ALLOWED_LEADING.include?(lead)
       return "multiple-statements" if multiple_statements?(code)
+      return nil unless code.include?("(") || code.match?(PATTERN_PREFILTER)
 
       FORBIDDEN_PATTERNS.each do |name, pattern|
         return name if code.match?(pattern)
@@ -95,47 +103,50 @@ module PgPipeline
 
     def code_only(sql)
       source = sql.to_s.b
-      output = String.new(capacity: source.bytesize, encoding: Encoding::BINARY)
+      size = source.bytesize
+      output = String.new(capacity: size, encoding: Encoding::BINARY)
       index = 0
       block_depth = 0
 
-      while index < source.bytesize
+      while index < size
+        byte = source.getbyte(index)
+        nxt = index + 1 < size ? source.getbyte(index + 1) : nil
+
         if block_depth.positive?
-          if source.byteslice(index, 2) == "/*"
+          if byte == 47 && nxt == 42
             block_depth += 1
             output << "  "
             index += 2
-          elsif source.byteslice(index, 2) == "*/"
+          elsif byte == 42 && nxt == 47
             block_depth -= 1
             output << "  "
             index += 2
           else
-            output << (source.getbyte(index) == 10 ? "\n" : " ")
+            output << (byte == 10 ? 10 : 32)
             index += 1
           end
           next
         end
 
-        if source.byteslice(index, 2) == "--"
+        if byte == 45 && nxt == 45
           newline = source.index("\n", index + 2)
           if newline
-            output << " " * (newline - index) << "\n"
+            output << (" " * (newline - index)) << "\n"
             index = newline + 1
           else
-            output << " " * (source.bytesize - index)
+            output << (" " * (size - index))
             break
           end
           next
         end
 
-        if source.byteslice(index, 2) == "/*"
+        if byte == 47 && nxt == 42
           block_depth = 1
           output << "  "
           index += 2
           next
         end
 
-        byte = source.getbyte(index)
         if byte == 39
           index = mask_quoted(source, output, index, 39, escape_backslash: escape_string_prefix?(source, index))
           next
@@ -147,18 +158,18 @@ module PgPipeline
         end
 
         if byte == 36
-          remainder = source.byteslice(index, source.bytesize - index)
+          remainder = source.byteslice(index, size - index)
           tag = remainder.match(/\A\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/)&.[](0)
           if tag
             closing = source.index(tag, index + tag.bytesize)
-            finish = closing ? closing + tag.bytesize : source.bytesize
-            output << " " * (finish - index)
+            finish = closing ? closing + tag.bytesize : size
+            output << (" " * (finish - index))
             index = finish
             next
           end
         end
 
-        output << source.getbyte(index)
+        output << byte
         index += 1
       end
 
@@ -209,12 +220,17 @@ module PgPipeline
     private_class_method :escape_string_prefix?
 
     def multiple_statements?(code)
-      semicolons = []
-      code.each_char.with_index { |char, i| semicolons << i if char == ";" }
-      return false if semicolons.empty?
+      first = code.index(";")
+      return false unless first
+
+      index = first + 1
+      size = code.bytesize
+      while index < size
+        return true unless WHITESPACE_BYTES.include?(code.getbyte(index))
 
-      last_non_space = code.rstrip.length - 1
-      semicolons.length > 1 || semicolons.first != last_non_space
+        index += 1
+      end
+      false
     end
   end
 end

data/lib/pg_pipeline/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_pipeline
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.5
 platform: ruby
 authors:
 - Roman Hajdarov