pg_pipeline 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bc5e0b7e4d8a274bc84e16fc7205774f0c20a0d4b2ee2ed9482a676eb15b986
-  data.tar.gz: fd0f6c75af1815f9574b2133caff20c092db8f45f4ee04085bf975f51be231e0
+  metadata.gz: 5ebb76f18598913316b77fdc0fd0ab4aa411fbd014cf1f3f10e427c1a5709967
+  data.tar.gz: cd51b3fc6b5f20f5896969e8eb3a4263d999f2544239606944194192f894e850
 SHA512:
-  metadata.gz: 3a284e77a674fc31d6e1b0263ff32cd254814f8f535e84060227e30d5e7ffe284b104dc764dfb9cd9062dc4f56b5319b088d9649ff6213e60498775806930637
-  data.tar.gz: fa814de3830232f0f9136d3f582917bd91c426fc540f1d4cc19ded4872eb9eed4d45f936738d35f34c9377beb6057fe9e4c204b413f1654aa31b3d431e2c3266
+  metadata.gz: 6c1581a9ecc7f45b44342c49c529d12694c5d962808ef4ba7a0ec9d71aac5ae46852c99c242ec1b897c8c1b591d9ab66c55a24eacf0a4e6637de068624f36fc3
+  data.tar.gz: 3272e19424de3eed0f6c186b2bf14ac830ef226f9ce47207fd3c71fd38f622557a6542630c44934794cf9c650106a2e5a7e66ec475501220a685551799609111

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## [0.3.0] - 2026-08-07
+
+Scheduler-agnostic control plane: the gem no longer depends on the `async` gem
+at runtime. Any `Fiber::Scheduler` host works (Async::Scheduler, Itsi::Scheduler,
+or another `Fiber.set_scheduler` implementation).
+
+This unlocks hosts that were previously impossible. On our stand, Itsi with
+0.3.0 serves ~26% more req/s than the 0.2.5 Falcon baseline (29350 vs 23254,
+4 workers, `oha -z 60s -c 1000`) — a configuration 0.2.5 could not run at all,
+since it required an Async reactor. Falcon throughput itself is unchanged
+(23007 vs 23254, inside run-to-run spread): this is a portability change, and
+the speedup comes from being free to pick the host.
+
+### Changed
+
+- New `PgPipeline::Runtime` primitives (`Notification`, `Queue`, `Semaphore`,
+  `Task`, `spawn`, `with_timeout`, `Cancel`) built on `Fiber.scheduler`.
+- Driver/pool background work uses `Runtime.spawn` instead of `parent.async`.
+- Pinned-connection ownership keys on `Fiber.current` (not `Async::Task.current`).
+- Watcher shutdown closes queues + connection, then joins tasks with a timeout.
+- Timeouts go through `Timeout.timeout` (correct `timeout_after` arity), never a
+  direct one-arg `scheduler.timeout_after` call.
+- Closed `Runtime::Queue#enqueue` is a no-op; supervisor sleep errors are recorded
+  and `stats` exposes `supervisor_alive`.
+- `Client#start` / `Pool#start` / `ConnectionDriver#start` no longer take
+  `parent:` (no Async task-tree ownership; use `Runtime.spawn` on the active
+  scheduler). Call sites that passed `start(parent: task)` should use `#start`.
+- Runtime dependency: only `pg`. `async` is a development dependency for the
+  existing Async-based test harness.
+
+### Migration
+
+Hosts must install a Fiber scheduler before `Client#start`. Under Async:
+
+```ruby
+require "async"
+Sync { client.start; ... }
+```
+
+Under Itsi, the server installs `Itsi::Scheduler` for you — just `client.start`.
+
+Apps that previously relied on `pg_pipeline` pulling in `async` transitively
+should add `gem "async"` themselves if they still use Async.
+
 ## [0.2.5] - 2026-08-03
 
 Control-plane cleanup on the multiplexed query path: fewer per-query allocations,

data/README.md

@@ -24,13 +24,66 @@ At 10 ms RTT a naïve pool does ~100 queries/s per connection.
 A pipelined connection can do thousands — the wire stays full instead of sitting idle.
 
 `pg_pipeline` is the Ruby control plane that does exactly this: it multiplexes
-independent queries from many Async fibers onto a small pool of libpq connections,
+independent queries from many fibers onto a small pool of libpq connections,
 routes FIFO results back to the right fiber, and keeps transactional/session work
 on separate pinned connections. All wire protocol work stays in libpq; zero C code here.
 
 The single-owner connection model, FIFO result ownership, and lifecycle approach
 are directly inspired by tokio-postgres.
 
+## Any Fiber scheduler, not just Async
+
+Up to 0.2.x the control plane was built on the `async` gem: `Async::Task`,
+`Async::Queue`, `Async::Semaphore`, and a task tree rooted in Async's reactor.
+That made Falcon the only realistic host.
+
+0.3.0 removes that. The control plane is built on Ruby's `Fiber::Scheduler`
+interface — `Fiber.schedule` plus the scheduler's `block` / `unblock` — and on
+nothing else. The host installs whichever scheduler it likes; the gem never
+installs one and never calls a scheduler hook directly. `async` is now a
+development dependency only, and the sole runtime dependency is `pg`.
+
+```ruby
+# Falcon / any Async host — unchanged, still works
+Async do
+  client = PgPipeline::Client.open(ENV["DATABASE_URL"])
+  client.query("SELECT * FROM users WHERE id = $1", [id]).first
+end
+
+# Itsi, with its own scheduler — no Async anywhere
+# Itsi.rb:
+#   fiber_scheduler "Itsi::Scheduler"
+client = PgPipeline::Client.open(ENV["DATABASE_URL"])
+client.query("SELECT * FROM users WHERE id = $1", [id]).first
+```
+
+The call site does not change: `query` blocks the *fiber*, not the thread, so
+application code reads synchronously with no `await` and no coloured functions.
+The only hard requirement is that some scheduler is installed on the current
+thread — under a web server running requests in `Fiber.schedule` that is free,
+while a plain script or rake task must set one up itself.
+
+### What it buys
+
+On our benchmark stand (4 workers, `oha -z 60s -c 1000`, single-row lookup by
+primary key, local PostgreSQL 16):
+
+| gem | server | scheduler | req/s |
+|---|---|---|---:|
+| 0.2.5 | Falcon | Async | 23254 |
+| 0.3.0 | Falcon | Async | 23007 |
+| 0.3.0 | Itsi | Async | 29206 |
+| 0.3.0 | Itsi | Itsi::Scheduler | 29350 |
+
+Falcon throughput is unchanged — this was a portability change, not a
+Falcon optimisation. The gain comes from being *able* to move: an Itsi host is
+roughly **26% faster than the 0.2.5 Falcon baseline**, and that configuration
+simply could not run before, because 0.2.5 required an Async reactor.
+
+Numbers from one stand on one machine; treat them as a direction, not a
+guarantee. Your own ratio depends on payload size, RTT, and how much of the
+request is spent outside the database.
+
 ## Installation
 
 ```ruby

data/lib/pg_pipeline/bounded_queue.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require "async/notification"
-
 require_relative "errors"
+require_relative "runtime"
 
 module PgPipeline
   class BoundedQueue
@@ -12,15 +11,14 @@ module PgPipeline
     rescue ArgumentError, TypeError
       raise ArgumentError, "limit must be an integer >= 1"
     else
-      @items = []
-      @consumers = []
-      @producers = []
+      @items, @consumers, @producers = [], [], []
+
       @closed = false
       @close_error = nil
     end
 
     def enqueue(item)
-      loop do
+      while true
         raise_close_error if @closed
 
         if @items.size < @limit
@@ -34,7 +32,7 @@ module PgPipeline
     end
 
     def dequeue
-      loop do
+      while true
         unless @items.empty?
           item = @items.shift
           wake_one(@producers)
@@ -72,13 +70,13 @@ module PgPipeline
     private
 
     def wait_on(list)
-      notification = Async::Notification.new
+      notification = Runtime::Notification.new
       list << notification
       completed = false
-      begin
-        notification.wait
-        completed = true
-      ensure
+      notification.wait
+      completed = true
+    ensure
+      if notification
         still_queued = list.delete(notification)
         wake_one(list) if !completed && still_queued.nil? && !@closed
       end

data/lib/pg_pipeline/client.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "async"
-
 require_relative "errors"
 require_relative "pool"
 require_relative "request"
@@ -15,18 +13,18 @@ module PgPipeline
     attr_reader :guard
 
     def initialize(connection_args = nil, guard: :default, **pool_opts)
+      @owner_thread, @scheduler = nil, nil
+
       @guard = SessionGuard.normalize_mode!(guard)
       @pool = Pool.new(connection_args, **pool_opts)
       @started = false
-      @owner_thread = nil
-      @scheduler = nil
     end
 
     def self.open(connection_args = nil, **opts, &block)
       ClientOps.open(connection_args, opts, &block)
     end
 
-    def start(parent: Async::Task.current) = ClientOps.start(self, parent)
+    def start = ClientOps.start(self)
     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)
@@ -54,17 +52,16 @@ module PgPipeline
 
     def open(connection_args, opts)
       client = Client.new(connection_args, **opts).start
-      begin
-        yield client
-      ensure
-        client.close
-      end
+      yield client
+    ensure
+      client.close if client
     end
 
-    def start(client, parent)
+    def start(client)
       raise Error, "client already started" if started?(client)
+      raise Error, "client start requires an active Fiber scheduler" unless Fiber.scheduler
 
-      pool(client).start(parent: parent)
+      pool(client).start
       client.__send__(:owner_thread=, Thread.current)
       client.__send__(:scheduler=, Fiber.scheduler)
       client.__send__(:started=, true)
@@ -98,11 +95,9 @@ module PgPipeline
 
     def wait_for_request
       request = yield
-      begin
-        request.wait
-      ensure
-        request.cancel! unless request.settled?
-      end
+      request.wait
+    ensure
+      request.cancel! if request && !request.settled?
     end
 
     def submit_with_failover(client)

data/lib/pg_pipeline/connection_driver.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
 require "pg"
-require "async"
-require "async/queue"
 
 require_relative "errors"
+require_relative "runtime"
 require_relative "bounded_queue"
 require_relative "server_caps"
 require_relative "request"
@@ -21,7 +20,7 @@ module PgPipeline
                   :owner_task, :reader_task, :writer_task
 
     attr_writer :readable_events, :results_read, :units_completed, :flush_calls,
-                :flush_incomplete, :dispatches
+                :flush_incomplete, :dispatches, :leaked_watchers
 
     def readable_events = @readable_events || 0
     def results_read = @results_read || 0
@@ -29,6 +28,7 @@ module PgPipeline
     def flush_calls = @flush_calls || 0
     def flush_incomplete = @flush_incomplete || 0
     def dispatches = @dispatches || 0
+    def leaked_watchers = @leaked_watchers || 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)
@@ -40,35 +40,19 @@ module PgPipeline
       DriverOps.warn_flush_coupling_once(@caps)
 
       @requests = BoundedQueue.new(@max_pending)
-      @events = Async::Queue.new
-      @reader_rearm = Async::Queue.new
-      @writer_commands = Async::Queue.new
+      @events = Runtime::Queue.new
+      @reader_rearm = Runtime::Queue.new
+      @writer_commands = Runtime::Queue.new
+
+      @accepting = @running = @draining = @needs_flush = @writer_armed = @request_event_pending = false
+      @readable_events = @results_read = @units_completed = @flush_calls =
+        @flush_incomplete = @dispatches = @leaked_watchers = @submitting = 0
+      @socket = @owner_task = @reader_task = @writer_task = @dispatching = nil
 
       @inflight = []
-      @dispatching = nil
-      @submitting = 0
-
-      @accepting = false
-      @running = false
-      @draining = false
-      @needs_flush = false
-      @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
-      @writer_task = nil
-    end
-
-    def start(parent: Async::Task.current) = DriverOps.start(self, parent)
+    end
+
+    def start = DriverOps.start(self)
     def submit(request) = DriverOps.submit(self, request)
     def load = @requests.size + @inflight.size + @submitting + (@dispatching ? 1 : 0)
     def available? = @accepting && @running
@@ -91,7 +75,8 @@ module PgPipeline
         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)
+        flush_calls_per_unit: DriverOps.ratio(flush_calls, units_completed),
+        leaked_watchers: leaked_watchers
       }
     end
 
@@ -99,21 +84,19 @@ module PgPipeline
       return true unless available?
 
       probe = Request.build("SELECT 1", nil)
-      begin
-        submit(probe)
-        Async::Task.current.with_timeout(timeout) { probe.wait }
-        true
-      rescue Async::TimeoutError
-        DriverOps.abort_timed_out_health_probe(self, probe)
-      rescue QueryError, PipelineAbortedError
-        true
-      rescue ShutdownError, NotDispatchedError
-        true
-      rescue ConnectionLostError, PG::Error
-        false
-      ensure
-        probe.cancel! unless probe.settled?
-      end
+      submit(probe)
+      Runtime.with_timeout(timeout) { probe.wait }
+      true
+    rescue Runtime::TimeoutError
+      DriverOps.abort_timed_out_health_probe(self, probe)
+    rescue QueryError, PipelineAbortedError
+      true
+    rescue ShutdownError, NotDispatchedError
+      true
+    rescue ConnectionLostError, PG::Error
+      false
+    ensure
+      probe.cancel! if probe && !probe.settled?
     end
 
     def graceful_close = DriverOps.graceful_close(self)
@@ -124,6 +107,9 @@ module PgPipeline
   end
 
   module DriverOps
+    WATCHER_JOIN_TIMEOUT = 2.0
+    OWNER_JOIN_TIMEOUT = 5.0
+
     module_function
 
     def ratio(numerator, denominator)
@@ -155,8 +141,9 @@ module PgPipeline
       raise ArgumentError, "#{name} must be an integer >= 1"
     end
 
-    def start(d, parent)
+    def start(d)
       raise Error, "driver already started" if d.running
+      raise Error, "driver start requires an active Fiber scheduler" unless Fiber.scheduler
 
       d.conn.setnonblocking(true)
       d.conn.enter_pipeline_mode
@@ -165,15 +152,15 @@ module PgPipeline
       d.accepting = true
       d.running = true
 
-      d.reader_task = parent.async { reader_watcher(d) }
-      d.writer_task = parent.async { writer_watcher(d) }
-      d.owner_task = parent.async { owner_loop(d) }
+      d.reader_task = Runtime.spawn(name: :reader) { reader_watcher(d) }
+      d.writer_task = Runtime.spawn(name: :writer) { writer_watcher(d) }
+      d.owner_task = Runtime.spawn(name: :owner) { owner_loop(d) }
       d
     rescue Exception
       d.accepting = false
       d.running = false
-      stop_watchers(d)
-      safe_close_conn(d)
+      teardown_watchers(d)
+      join_owner(d)
       raise
     end
 
@@ -200,7 +187,7 @@ module PgPipeline
       d.accepting = false
       d.requests.close(ShutdownError.new("driver is closing"))
       d.events.enqueue(:close)
-      d.owner_task.wait
+      join_owner(d)
       nil
     end
 
@@ -210,7 +197,7 @@ module PgPipeline
       d.accepting = false
       d.requests.close(not_dispatched_error(error))
       d.events.enqueue([:abort, error])
-      d.owner_task.wait unless Async::Task.current.equal?(d.owner_task)
+      join_owner(d)
       nil
     end
 
@@ -232,7 +219,12 @@ module PgPipeline
     end
 
     def owner_loop(d)
-      process_event(d, d.events.dequeue) while d.running
+      while d.running
+        event = d.events.dequeue
+        break if event.nil?
+
+        process_event(d, event)
+      end
     rescue StandardError => e
       fatal_close(d, ConnectionLostError.new("driver crashed: #{e.class}: #{e.message}"))
     ensure
@@ -275,6 +267,7 @@ module PgPipeline
 
     def notify_requests(d)
       return if d.request_event_pending
+      return unless d.running
 
       d.request_event_pending = true
       d.events.enqueue(:requests)
@@ -377,6 +370,7 @@ module PgPipeline
 
     def arm_writer(d)
       return if d.writer_armed
+      return unless d.running
 
       d.writer_armed = true
       d.writer_commands.enqueue(:wait_writable)
@@ -466,14 +460,11 @@ module PgPipeline
       d.accepting = false
       d.running = false
 
-      begin
-        d.conn.exit_pipeline_mode
-      rescue PG::Error => e
-        fail_all(d, ConnectionLostError.new("failed to exit pipeline mode: #{e.message}"))
-      ensure
-        stop_watchers(d)
-        safe_close_conn(d)
-      end
+      d.conn.exit_pipeline_mode
+    rescue PG::Error => e
+      fail_all(d, ConnectionLostError.new("failed to exit pipeline mode: #{e.message}"))
+    ensure
+      teardown_watchers(d)
     end
 
     def fatal_close(d, error)
@@ -483,8 +474,8 @@ module PgPipeline
       d.running = false
       d.requests.close(not_dispatched_error(error))
       fail_all(d, error)
-      stop_watchers(d)
-      safe_close_conn(d)
+
+      teardown_watchers(d)
     end
 
     def fail_all(d, error)
@@ -549,21 +540,87 @@ module PgPipeline
       end
     end
 
-    def stop_watchers(d)
-      reader = d.reader_task
-      writer = d.writer_task
+    def teardown_watchers(d)
+      tasks = release_watchers(d)
+      close_wait_points(d)
+      begin
+        d.socket&.close
+      rescue StandardError
+        nil
+      end
+      stop_watchers(tasks)
+      join_watchers(d, tasks)
+      d.socket = nil
+      safe_close_conn(d)
+      nil
+    end
+
+    def release_watchers(d)
+      tasks = [d.reader_task, d.writer_task].compact
       d.reader_task = nil
       d.writer_task = nil
+      tasks
+    end
+
+    def close_wait_points(d)
+      [d.reader_rearm, d.writer_commands, d.events].each do |queue|
+        queue&.close
+      rescue StandardError
+        nil
+      end
+    end
+
+    def stop_watchers(tasks)
+      Array(tasks).each do |task|
+        task.stop
+      rescue Runtime::Cancel, StandardError
+        nil
+      end
+
+      nil
+    end
 
-      [reader, writer].each do |task|
-        task&.stop
-      rescue Async::Cancel, StandardError
+    def join_watchers(d, tasks)
+      Array(tasks).each do |task|
+        task.wait(WATCHER_JOIN_TIMEOUT)
+      rescue Runtime::TimeoutError
+        d.leaked_watchers += 1
+        warn_leaked_task(d, task, WATCHER_JOIN_TIMEOUT)
+      rescue Runtime::Cancel, StandardError
         nil
       end
 
       nil
     end
 
+    def join_owner(d)
+      owner = d.owner_task
+      return if owner.nil?
+      return if Fiber.current.equal?(owner.fiber)
+
+      begin
+        owner.wait(OWNER_JOIN_TIMEOUT)
+      rescue Runtime::TimeoutError
+        d.leaked_watchers += 1
+        warn_leaked_task(d, owner, OWNER_JOIN_TIMEOUT)
+      rescue Runtime::Cancel, StandardError
+        nil
+      end
+
+      nil
+    end
+
+    def warn_leaked_task(d, task, timeout)
+      return if ENV["PG_PIPELINE_SILENCE_WARNINGS"]
+
+      warn(
+        "pg_pipeline: task #{task.name.inspect} did not exit within " \
+        "#{timeout}s and has been leaked (total #{d.leaked_watchers}). " \
+        "Closing the duplexed socket_io / connection did not release the fiber " \
+        "(often parked in wait_readable/wait_writable)."
+      )
+    end
+
     def safe_close_conn(d)
       d.conn.close unless d.conn.finished?
     rescue StandardError