pg_pipeline 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7135257ec52d199f4a7e0d3666909eebd8effa277f7efe80d27ca8ff00717f93
-  data.tar.gz: 8f3b976cc4b9f8400439a1504bbad9a019865a88a7f41e6556907ba649587c80
+  metadata.gz: e6537ec11ece29a487aa35449c264d2bae69089022a28c473f71523e52fd2acd
+  data.tar.gz: 231b7285d0ddf23bb686836217ff35d1c89cc3872a5ac4ef20df28cea7e781bb
 SHA512:
-  metadata.gz: 90422fd9a948509c2e53b9058d052a822e76f303a736a39488a0870b6fa903d6c1b2b8248e00649269a63ed606a9a8d04b1c2c081cf0f2b89e81000af8a36e54
-  data.tar.gz: fa76f361560fa078903685d69de81600b8337509b8f37b89cd93fdfdc71ebc3953180edf8487b4aa24d79d521237ef98bc727cde48ca959acb41c0d589749999
+  metadata.gz: 31ef9eeacef9208296c2df0d29f5a83e0a2ee8a2278715bd4b67d261fb1561a5b0e11771856b5dfb27d34a28cb21034e7b6cda5408757f6e13672a3db65c8d3d
+  data.tar.gz: b686d8bd24fb976e8d9e6842b92db04988b1ae6f5981b297de57fc7d32b0add212d200f5b2906d5a7ea450b47bf46b9373a4404d5449ab24b702b189fb2a9131

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [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,24 @@ 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.
 
 ## 11. Version policy
 

data/README.md

@@ -187,6 +187,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/request.rb

@@ -1,26 +1,25 @@
 # 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.prepare(statement) = PrepareRequest.new(statement)
@@ -156,7 +155,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 +166,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 +179,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PgPipeline
-  VERSION = "0.2.3"
+  VERSION = "0.2.4"
 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.4
 platform: ruby
 authors:
 - Roman Hajdarov