pgbus 0.17.0 → 0.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11b7ad58d91fe1eb9c0388008907523c77324f286f27a0e97a94353e4a8577b0
-  data.tar.gz: '0707593bb7c826f48f9a84db9a666057aaed3407b0d1cb559007f57caf080be2'
+  metadata.gz: 7b7955f6b4ccdd4d3e4f8d8e372e9283ca0b7f801d7a6909d29f03fde3425ce7
+  data.tar.gz: f26d692d0e9b979e9c4b77b3e28cafdab4d3c50e32292e793e1885d94f0d5943
 SHA512:
-  metadata.gz: 0f1422dea206dbeaac10b1fd7dfa74da2338c007cffb48d7a2b5429bf3a94e6f3e78b5795832d0a2f45346fe4350d4c7355d16b773247420894ea5234c50db85
-  data.tar.gz: 6d30c3583b7e6b5fa9dc89cf42115f57b182dea18b2d363f1ec413d6096ba32b76d75f008dcf7a2f25de3baf9ceba7e17f1edbb382b96e2aeb23bf52a8824af2
+  metadata.gz: 30c539f2494acaeffdd10301bba047d6dca86ab2bf3ae776ac6d8d3239f4b5e5a05d530135932cf15122b37dd02acd50de86026315365ea10c085e0100201ebf
+  data.tar.gz: 596d817366be305b4abd3c9f1975e6e004ef2448976f58bfb36c9c9b1cd15d0abbc830a98bfd9900d5fc2cfc07b2f6257c1f158b7f8b09a653e97e55c590cc92

data/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ### Added
 
+- **`rake bench:worker_profile` measures the event consumer too.** A consumer cell drives a real `Process::Consumer` over an event-bus topic queue (plain handler, so the transport is measured, not the dedup table) with the same harness as the worker cell. `WP_BENCH_ROLE` (`worker`, `consumer`, `both`) and `WP_BENCH_READ_AHEAD` (passed as `read_ahead:`) are new knobs. Refs #486.
+
 - **`coalesce:` now works on the `Turbo::StreamsChannel` broadcast path.** `Pgbus::Streams::Stream#broadcast` has accepted `coalesce:` since #171, but the Turbo patch forwarded only four options (`durable:`, `exclude:`, `visible_to:`, `event:`), so nothing that broadcasts through `Turbo::StreamsChannel.broadcast_*_to` — every `Turbo::Broadcastable` model, and phlex-reactive's `Streamable.broadcast_to` — could debounce. A background job settling a 177-row collection therefore pushed 177 idempotent replaces of the same count badge at every peer. Any targeted helper now takes `coalesce:` (`@order.broadcast_replace_to :account, coalesce: 100`), as does a direct channel call (`Turbo::StreamsChannel.broadcast_replace_to(@account, target: "order-count", coalesce: true)`), with the same semantics as the direct API: opt-in, per `(stream, target)`, last-write-wins, `true` = the 50ms default window, an integer = the window in ms. Two things the option's plumbing needed beyond a fifth thread-local: the coalescing key, which dedupes on `(stream, target)` while `broadcast_stream_to` only ever sees the rendered `content:` — it is now resolved from the frame's own `target:`/`targets:` through the same `ActionView::RecordIdentifier.dom_id` conversion Turbo applies, so a record target keys on `order_7` rather than on a per-instance `#to_s`; and extraction of the pgbus options at the channel itself, since a direct `Turbo::StreamsChannel` call never passes through `Turbo::Broadcastable` and so previously leaked `durable: true` (and now `coalesce:`) into Turbo's renderer. `broadcast_refresh_to` and `broadcast_render_to` carry no target and so cannot coalesce — they raise the existing actionable "requires target:" error rather than guessing a key — and the `_later_to` variants remain out of scope, as the thread-local cannot follow into a job. The wire is byte-identical when `coalesce:` is absent. Closes #465.
 
 - **Concurrency is now visible: a section on the Locks page, three gauges, a home stat card and an MCP tool.** `limits_concurrency … on_conflict: :block` became durable in #460 — a parked job is never dropped and a key never runs past `to:` — but nothing showed it, so an operator whose per-record pipeline looked "stuck" had no way to see that the key's slot was held, how many jobs were parked behind it, or how long the oldest had waited, short of SQL. `pgbus_semaphores` and `pgbus_blocked_executions` appeared on no page, in no gauge, in no tool. One new read, `Web::DataSource#concurrency_stats`, now feeds four surfaces: the Locks page's **Concurrency** section (parked jobs, oldest wait, slots held, keys at limit, then a row per key with value / limit, lease state, parked count and oldest wait, auto-refreshing like the other dashboard panels); a **Parked jobs** card on the dashboard home; three unlabelled gauges on both `/pgbus/api/metrics` and the AppSignal probe (`pgbus_concurrency_blocked_executions`, `pgbus_concurrency_blocked_oldest_age_seconds`, `pgbus_concurrency_slots_held` — keys are per-record, so a per-key label would be an unbounded series); and a read-only `pgbus_concurrency` MCP tool returning the same data. The key rows come from a FULL OUTER JOIN, not a LEFT one: a key can have parked jobs and no semaphore (its holder died and the sweep removed the row) or a semaphore and nothing parked, and both shapes matter to an operator. Each row carries two guarded escape hatches. **Release** drops the semaphore and promotes through `Concurrency::BlockedExecution.promote_next`, so it takes each slot through the same guarded upsert an enqueue uses and can never reintroduce the over-admission #460 closed; when the lease is still fresh the confirm says so, because a job is then probably still running and releasing lets another start beside it. **Discard parked** drops a single key's parked jobs, naming the exact count in the confirm, and resolves the bookkeeping those jobs will never resolve themselves — a parked batch child is marked failed so its batch stops waiting and `on_failure` fires (#413), and an `:until_executed` uniqueness lock is released rather than orphaned (#423); each discard logs a warning naming the job and emits `pgbus.blocked_execution_discarded`. There is deliberately no cross-key "discard all parked": not losing work is the whole point of `:block`. Nothing is added to the enqueue or execute path. Refs #461.
@@ -10,6 +12,16 @@
 
 - **The batches list and a batch's progress panel now refresh themselves.** Batches was the only dashboard list whose `turbo-frame` was missing `data-auto-refresh`, and the batch detail page had no frame at all, so watching a batch drain meant reloading by hand. Both now poll on the existing `web_refresh_interval` (5s, pauses while you interact) like every other list — the batch progress panel is served by `GET /batches/:id?frame=progress`. This reuses the dashboard's turbo-frame polling rather than the SSE stack in `lib/pgbus/web/stream_app.rb`: that is the host-app-facing stream feature, and pointing it at the dashboard would open a PG `LISTEN` connection per viewer to move four integers.
 
+- **`pgbus doctor` reports the Ruby JIT, and the boot banner names it.** A new "Ruby JIT" check is `:ok` when YJIT (or ZJIT) is on, when the Ruby has no JIT, or in a local (development/test) environment, and warns otherwise — never fails, never enables anything; turning YJIT on stays with Rails' `config.yjit`. The supervisor's first boot line now ends `jit=yjit|zjit|none`. Measured reason: with Postgres close by, a worker is CPU-bound under the GVL and YJIT is worth ~14–20 % jobs/s (`docs/performance.md`). Refs #484.
+
+- **`rake bench:worker_profile`: jobs/s and where a job's time goes, for a real worker.** Drives a real `Pgbus::Process::Worker` against real PGMQ and splits each thread's time (Postgres wait, pool-checkout wait, waiting for work, GVL wait, and whose code was on-CPU) with vernier, locally and optionally behind toxiproxy-injected latency. `vernier` joins the test group; it is not a runtime dependency. The same change repairs `benchmarks/integration_bench.rb`, which no longer ran against 1.0's `ensures_uniqueness`. Refs #484.
+
+### Changed
+
+- **perf(worker, consumer): opt-in read-ahead, so one read feeds many jobs when Postgres is on another host.** A worker read `qty = free threads`; once its pool was busy, threads freed one at a time, so it made one read round trip per job. Under +1 ms of latency that capped a 12-thread worker at ~1.3–1.7 k no-op jobs/s however many threads it had (#484), and the event consumer's loop had the same shape. New `config.read_ahead` (default **0**, off; overridable per capsule and per `event_consumers` entry with `read_ahead:`) lets either loop claim up to N messages beyond its free threads. Claimed messages wait in a new `Process::ClaimBuffer`, kept invisible by a new `VisibilityHeartbeat.hold`, until a thread frees. They are handed back to the queue (`set_vt` 0) the moment the worker drains, recycles, pauses or stops, or the consumer shuts down or recycles, with `read_ct` already counted. Buffered claims count as in flight, so `prefetch_limit` still caps everything claimed. Measured with `rake bench:worker_profile` (12 threads, no-op jobs, +1 ms per round trip, rounds 2–3 of three interleaved rounds on a loaded machine): **worker 1 286–1 731 → 2 300–2 462 jobs/s, consumer 1 326–1 779 → 2 288–2 599** at `read_ahead` 12. Locally both are within noise, because there the worker is CPU-bound under the GVL; `read_ahead` 0 overlaps the baseline's run-to-run range in 7 of 8 cells; consumer / proxied / no JIT sits 2–18 % below, plausibly load noise but unproven. A returned message's next claimant logs it as a zombie redelivery when `zombie_detection` is on, and `validate!` warns when `read_ahead > 0` meets `visibility_heartbeat = false`, since nothing then keeps a buffered message invisible. With read-ahead on, the next ceiling under latency is the connection pool (checkout wait 2–3 % → 14–15 %), so raise `pool_size` with it. `VisibilityHeartbeat`'s unregister now drops only the entry it registered, so a stale hold released after a job's own tracking took over cannot drop that job's heartbeat. Worker heartbeat metadata gains `"buffered"`. Refs #486.
+
+- **perf(executor): a successful first delivery no longer deletes from `pgbus_failed_events`.** Every successful job ran a `DELETE … WHERE queue_name = $1 AND msg_id = $2` through ActiveRecord, but only a failed attempt ever writes that table, so a job on its first delivery cannot have a row. The DELETE now runs only on redelivery (`read_ct > 1`), still clearing the row a failed attempt left. Measured with `rake bench:worker_profile` (12 threads, no-op jobs, local Postgres): **4 569 → 5 823 jobs/s with YJIT (+27 %), 3 797 → 5 119 without (+35 %)**; under +1 ms injected latency the change is within noise, because there the worker's single reader is the ceiling. This is a per-job query removed, not faster job code. The executor's debug tag is also built only when debug logging is on (9 → 8 pgbus-owned objects per job, now a hard budget). `Client#drop_queue` now also deletes the dropped queue's `pgbus_failed_events` rows: PGMQ restarts `msg_id`s when a queue is recreated, and a surviving row would point the dashboard's retry/discard at an unrelated new message — previously a first-delivery success happened to sweep such a row, and that sweep is gone. Refs #484.
+
 ### Fixed
 
 - **A still-running event handler is no longer re-run as if it had crashed, and a slow one is no longer redelivered mid-run.** Two halves of one hole, follow-up to #469. First: `Process::Consumer` had no equivalent of `ActiveJob::Executor#with_visibility_heartbeat`, so an event message's visibility timeout was never re-armed — a handler slower than `visibility_timeout` (30s by default) was redelivered *while it was still running*, `read_ct` climbed on every redelivery, and after `max_retries` the event was dead-lettered without the handler ever raising. Workers have been protected from this since the heartbeat landed; event consumers never were. The consumer now tracks each message through `VisibilityHeartbeat` for exactly as long as its handlers run, releasing the entry before the archive so a beat can never re-arm a message that is already gone. Second: `Handler#claim_idempotency?` read a `pgbus_processed_events` row with `completed_at IS NULL` as proof that the previous holder had been killed mid-handler, and re-ran. That state equally describes a handler that is simply still running — on another thread, another fork or another host — so a second delivery (a genuine redelivery, or a duplicate envelope, whose independent visibility timeouts no heartbeat can serialize) executed the handler *concurrently with* the live one, which is precisely the double-execution `idempotent!` exists to prevent. The claim now carries liveness rather than only a claim instant: `EventBus::ClaimBeat` refreshes every in-flight claim's `processed_at` from the same beat that re-arms the message's visibility timeout, so message visibility and claim liveness go quiet together when a process dies. A pending claim silent for longer than twice the heartbeat interval is abandoned and re-runs, exactly as before; a fresher one is owned and the delivery skips, deferring to the holder — which either completes (nothing is lost) or fails, leaving its own message for visibility-timeout redelivery to recover. A skip is also no longer silent: `pgbus.event_skipped` carries the reason (`:completed`, `:cached` or `:owned`), the claim's age in seconds and the delivery's `read_ct`, and the metrics subscriber counts it as `pgbus_event_count` with `status: "skipped"` and the reason as a tag. No migration, no new column, and no change on a table that has not run `pgbus:add_processed_event_completion` — a single-phase claim has no pending state and therefore no ownership question. Closes #470.

data/README.md

@@ -26,6 +26,7 @@ PostgreSQL-native job processing and event bus for Rails, built on [PGMQ](https:
   - [Client-level circuit breaker (database-down)](#client-level-circuit-breaker-database-down)
   - [Read timeouts (libpq-native)](#read-timeouts-libpq-native)
   - [Prefetch flow control](#prefetch-flow-control)
+  - [Read-ahead](#read-ahead)
   - [Worker recycling](#worker-recycling)
   - [Retry backoff](#retry-backoff)
 - [Routing and ordering](#routing-and-ordering)
@@ -541,6 +542,24 @@ end
 
 The worker tracks in-flight messages with an atomic counter and only fetches `min(idle_threads, prefetch_available)` messages per cycle. The counter is decremented in an `ensure` block so it never gets stuck.
 
+### Read-ahead
+
+By default a worker reads as many messages as it has free threads. Once the pool is busy, threads free one at a time, so the worker ends up making one read round trip per job. That costs nothing when Postgres is on the same host. When Postgres is on another host, that round trip becomes the throughput ceiling. `read_ahead` lets a worker or event consumer claim up to N messages beyond its free threads and hold them until a thread frees:
+
+```ruby
+Pgbus.configure do |config|
+  config.read_ahead = 12                                   # global; 0 = off (default)
+  config.capsule :api, queues: %w[api], threads: 12, read_ahead: 12   # per capsule
+  config.event_consumers = [{ topics: ["orders.#"], threads: 8, read_ahead: 8 }]
+end
+```
+
+- **When to turn it on:** when Postgres is not on the same host as the worker. Start with `read_ahead` equal to `threads`. With a local database it buys little, because the worker is CPU-bound there. Under +1 ms of latency, `read_ahead` 12 took a 12-thread worker from ~1.3–1.7k to ~2.3–2.5k no-op jobs/s (`docs/performance.md`, "Read-ahead"). The next ceiling is the connection pool, so raise `pool_size` with it.
+- **Visibility:** buffered messages are kept invisible by the visibility heartbeat until their job starts, so a long wait never lets another worker claim them. With `visibility_heartbeat = false` nothing holds them, and a message buffered past `visibility_timeout` can run twice; `validate!` warns about that combination.
+- **Shutdown and recycle:** when a worker drains, recycles, pauses or shuts down, buffered messages go straight back to the queue (`set_vt` 0), not after `visibility_timeout`. Their `read_ct` has already been incremented, the same as after a crash, so with `zombie_detection` on, the worker that picks one up logs it as a zombie redelivery.
+- **With `prefetch_limit`:** buffered messages count as in flight, so `prefetch_limit` still caps everything a worker has claimed.
+- **Multi-queue workers:** the plain multi-queue read (no priority, fair share or group mode) can claim and discard rows past its limit. A larger read makes that worse; see `docs/performance.md`.
+
 ### Worker recycling
 
 Pgbus workers recycle themselves to prevent memory bloat. This is the main reliability difference vs. solid_queue, which leaves workers alive forever.
@@ -2031,11 +2050,12 @@ pgbus help      # Show help
 
 #### pgbus doctor
 
-A single preflight command that answers "is this environment healthy enough to run?" — useful as a deploy or CI gate. It runs 11 checks and never raises; a broken environment turns every probe into a failed/warned check instead of a crash:
+A single preflight command that answers "is this environment healthy enough to run?" — useful as a deploy or CI gate. It runs 12 checks and never raises; a broken environment turns every probe into a failed/warned check instead of a crash:
 
 | Check | Fails (`:fail`) when | Warns (`:warn`) when |
 |---|---|---|
 | Configuration | `Configuration#validate!` raises | — |
+| Ruby JIT | — | YJIT is available but off outside a local environment (a CPU-bound worker with Postgres nearby runs ~15% fewer jobs/s without it; no measurable effect when network-bound); reports only, never enables |
 | Database | Unreachable (`SELECT 1` via `Client#ping`) | — |
 | PGMQ schema | Schema not installed | Installed but untracked, or behind the vendored version |
 | Queues | A configured queue has no PGMQ table | — |

data/Rakefile

@@ -25,7 +25,8 @@ namespace :bench do
   # no-DB unit suite that bench:all runs in CI.
   db_benches = %w[connection_pool_bench integration_bench streams_bench streams_read_pool_bench
                   execution_modes_bench pool_swap_bench pool_autoscale_bench job_burst_bench
-                  notify_wake_bench notify_chaos_bench streams_hub_bench fair_read_bench].freeze
+                  notify_wake_bench notify_chaos_bench streams_hub_bench fair_read_bench
+                  worker_profile_bench].freeze
   # The unit suite is every *_bench.rb that doesn't need a database, derived
   # from the directory so a new unit bench is picked up automatically (kept in
   # sync with bench:one, which globs the same files).
@@ -60,6 +61,11 @@ namespace :bench do
     ruby "benchmarks/integration_bench.rb"
   end
 
+  desc "Run worker profiling bench: jobs/s and where a job's time goes (requires PGBUS_DATABASE_URL)"
+  task :worker_profile do
+    ruby "benchmarks/worker_profile_bench.rb"
+  end
+
   desc "Run fair share read benchmark (requires PGBUS_DATABASE_URL)"
   task :fair_read do
     ruby "benchmarks/fair_read_bench.rb"

data/lib/pgbus/active_job/executor.rb

@@ -19,8 +19,7 @@ module Pgbus
 
       def execute(message, queue_name, source_queue: nil)
         execution_start = monotonic_now
-        tag = "msg_id=#{message.msg_id} queue=#{queue_name} read_ct=#{message.read_ct}"
-        Pgbus.logger.debug { "[Pgbus::Executor] start #{tag}" }
+        Pgbus.logger.debug { "[Pgbus::Executor] start #{log_tag(message, queue_name)}" }
 
         payload = JSON.parse(message.message)
         job_class = payload["job_class"]
@@ -42,7 +41,7 @@ module Pgbus
             read_ct: read_count,
             msg_id: message.msg_id.to_i
           )
-          Pgbus.logger.debug { "[Pgbus::Executor] dead_lettered #{tag} job_class=#{job_class}" }
+          Pgbus.logger.debug { "[Pgbus::Executor] dead_lettered #{log_tag(message, queue_name)} job_class=#{job_class}" }
           return :dead_lettered
         end
         uniqueness_key = Uniqueness.extract_key(payload)
@@ -70,7 +69,7 @@ module Pgbus
           end
         end
 
-        Pgbus.logger.debug { "[Pgbus::Executor] deserialized #{tag} job_class=#{job_class}" }
+        Pgbus.logger.debug { "[Pgbus::Executor] deserialized #{log_tag(message, queue_name)} job_class=#{job_class}" }
         job_succeeded = false
         retried = false
 
@@ -95,13 +94,13 @@ module Pgbus
           # job data, so hand it to the job before perform — that is what makes
           # `batch` (and `batch.enqueue` for open batches) work inside a job.
           assign_batch_id(job, payload)
-          Pgbus.logger.debug { "[Pgbus::Executor] running #{tag} job_class=#{job_class}" }
+          Pgbus.logger.debug { "[Pgbus::Executor] running #{log_tag(message, queue_name)} job_class=#{job_class}" }
           with_visibility_heartbeat(job, queue_name, msg_id, source_queue, payload) { execute_job(job) }
           # retry_on re-enqueues from inside perform_now and returns normally:
           # this attempt is done (archive it) but the job is not — the retry
           # message carries the batch tag and signals on its own outcome.
           retried = Batch.retry_reenqueued?(payload["job_id"])
-          Pgbus.logger.debug { "[Pgbus::Executor] perform_returned #{tag} job_class=#{job_class}" }
+          Pgbus.logger.debug { "[Pgbus::Executor] perform_returned #{log_tag(message, queue_name)} job_class=#{job_class}" }
           # Archiving is the exact-once claim on this execution.
           # :already_archived means another worker archived the message (our
           # heartbeat lapsed and it was redelivered): that worker owns the
@@ -109,20 +108,24 @@ module Pgbus
           # concurrency slot a second time (rails/solid_queue#761).
           if archive_from(queue_name, msg_id, source_queue: source_queue) == :already_archived
             Pgbus.logger.warn do
-              "[Pgbus::Executor] already archived elsewhere, skipping signals #{tag} job_class=#{job_class}"
+              "[Pgbus::Executor] already archived elsewhere, skipping signals #{log_tag(message, queue_name)} job_class=#{job_class}"
             end
             release_duplicate_execution_lock(uniqueness_key, uniqueness_strategy, queue_name, msg_id)
             return :duplicate
           end
-          Pgbus.logger.debug { "[Pgbus::Executor] archived #{tag} job_class=#{job_class}" }
+          Pgbus.logger.debug { "[Pgbus::Executor] archived #{log_tag(message, queue_name)} job_class=#{job_class}" }
           job_succeeded = true
           release_uniqueness_lock(uniqueness_key)
-          FailedEventRecorder.clear!(queue_name: queue_name, msg_id: msg_id)
+          # Only FailedEventRecorder.record! writes this table, and only after a
+          # failed attempt, so a first delivery has no row: skip the per-job
+          # DELETE round trip (issue #484). A stale row from a dropped-and-
+          # recreated queue reusing this msg_id is the dispatcher's to sweep.
+          FailedEventRecorder.clear!(queue_name: queue_name, msg_id: msg_id) if read_count > 1
         end
 
         instrument("pgbus.job_completed", queue: queue_name, job_class: job_class)
         record_stat(payload, queue_name, "success", execution_start, message: message)
-        Pgbus.logger.debug { "[Pgbus::Executor] done #{tag} job_class=#{job_class}" }
+        Pgbus.logger.debug { "[Pgbus::Executor] done #{log_tag(message, queue_name)} job_class=#{job_class}" }
         :success
       rescue *FATAL_EXCEPTIONS
         # Process-fatal: propagate so the supervisor/OS can react.
@@ -150,7 +153,7 @@ module Pgbus
           exception_object: e
         )
         record_stat(payload, queue_name, "failed", execution_start, message: message)
-        Pgbus.logger.debug { "[Pgbus::Executor] failed #{tag} job_class=#{payload&.dig("job_class")} error=#{e.class}" }
+        Pgbus.logger.debug { "[Pgbus::Executor] failed #{log_tag(message, queue_name)} job_class=#{payload&.dig("job_class")} error=#{e.class}" }
         # Don't signal concurrency on transient failure — the job will be retried.
         # Semaphore is released only on success or dead-lettering.
         :failed
@@ -170,6 +173,12 @@ module Pgbus
 
       private
 
+      # Built inside the logger blocks so a job pays for the string only when
+      # debug logging is on (issue #484).
+      def log_tag(message, queue_name)
+        "msg_id=#{message.msg_id} queue=#{queue_name} read_ct=#{message.read_ct}"
+      end
+
       def assign_batch_id(job, payload)
         batch_id = payload[Batch::METADATA_KEY]
         return unless batch_id && job.respond_to?(:batch_id=)

data/lib/pgbus/client.rb

@@ -699,6 +699,9 @@ module Pgbus
         synchronized { @pgmq.drop_queue(name) }
       end
       @queues_created.delete(name)
+      # Failed-event rows are keyed by the name the executor saw (physical or
+      # logical); a recreated queue reuses msg_ids, so neither may survive.
+      FailedEventRecorder.clear_queue!([name, name.delete_prefix("#{config.queue_prefix}_")].uniq)
       result
     end
 

data/lib/pgbus/configuration.rb

@@ -12,6 +12,12 @@ module Pgbus
 
     # Worker settings
     attr_accessor :polling_interval, :prefetch_limit, :execution_mode
+    # read_ahead (issue #486): how many messages a worker or event consumer
+    # claims beyond its free threads and holds, heartbeated, until a thread
+    # frees. Under database latency one read then feeds many jobs instead of
+    # one. 0 (default) is off. Overridable per capsule / event_consumers entry
+    # (`read_ahead:`); prefetch_limit still caps everything claimed.
+    attr_reader :read_ahead
     # visibility_heartbeat / visibility_heartbeat_interval: while a job runs,
     # its message's visibility timeout is re-armed every interval seconds
     # (default: a third of visibility_timeout), so a job that outlives the
@@ -277,6 +283,7 @@ module Pgbus
       @visibility_heartbeat_interval = nil
 
       @prefetch_limit = nil
+      @read_ahead = 0
       @execution_mode = :threads
 
       @max_jobs_per_worker = nil
@@ -573,6 +580,16 @@ module Pgbus
       (0...priority_levels).map { |p| priority_queue_name(name, p) }
     end
 
+    def read_ahead=(value)
+      @read_ahead = value.nil? ? 0 : value
+    end
+
+    # Read-ahead for one capsule or event_consumers entry, falling back to
+    # the global read_ahead (mirrors execution_mode_for).
+    def read_ahead_for(entry)
+      entry.fetch(:read_ahead, nil) || read_ahead
+    end
+
     # Returns the execution mode for a specific worker config hash,
     # falling back to the global execution_mode setting.
     def execution_mode_for(worker_config)
@@ -828,6 +845,8 @@ module Pgbus
               "prefetch_limit must be > 0"
       end
 
+      validate_read_ahead!
+
       if priority_levels && !(priority_levels.is_a?(Integer) && priority_levels >= 1 && priority_levels <= 10)
         raise Pgbus::ConfigurationError, "priority_levels must be an integer between 1 and 10"
       end
@@ -846,6 +865,33 @@ module Pgbus
       self
     end
 
+    # Global, per-capsule and per-consumer read_ahead: a non-negative Integer.
+    def validate_read_ahead!
+      settings = [["read_ahead", read_ahead]]
+      Array(workers).each { |w| settings << ["worker read_ahead", w[:read_ahead]] unless w[:read_ahead].nil? }
+      Array(event_consumers).each { |c| settings << ["event consumer read_ahead", c[:read_ahead]] unless c[:read_ahead].nil? }
+
+      settings.each do |name, value|
+        next if value.is_a?(Integer) && !value.negative?
+
+        raise Pgbus::ConfigurationError, "#{name} must be a non-negative Integer (got #{value.inspect})"
+      end
+      warn_read_ahead_without_heartbeat(settings)
+    end
+
+    # Buffered claims are kept invisible only by the visibility heartbeat.
+    # Without it a message buffered longer than visibility_timeout can be
+    # claimed by another worker while it still waits here. Legal, but warned.
+    def warn_read_ahead_without_heartbeat(settings)
+      return if visibility_heartbeat
+      return unless settings.any? { |_name, value| value.positive? }
+
+      Pgbus.logger.warn do
+        "[Pgbus] read_ahead is on but visibility_heartbeat is false — a message buffered longer than " \
+          "visibility_timeout (#{visibility_timeout}s) can be claimed and run by another worker"
+      end
+    end
+
     # An explicit shutdown_timeout must be a positive number; nil keeps the
     # derived drain_timeout + margin default. A value below drain_timeout is
     # legal but self-defeating (the supervisor SIGKILLs workers mid-drain), so

data/lib/pgbus/doctor.rb

@@ -5,7 +5,7 @@ require "pgbus/mcp/health_analyzer"
 
 module Pgbus
   # Preflight diagnostics for a pgbus deployment — the single command that
-  # answers "is this environment healthy enough to run?". Runs eleven checks and
+  # answers "is this environment healthy enough to run?". Runs twelve checks and
   # returns a machine-readable result plus a human report, so `pgbus doctor`
   # and `rake pgbus:doctor` can gate a deploy or CI run (exit 0 on success,
   # 1 on any failure).
@@ -32,6 +32,7 @@ module Pgbus
     # stable identity of each check (used in the report and to select subsets).
     CHECKS = {
       "Configuration" => :check_configuration,
+      "Ruby JIT" => :check_ruby_jit,
       "Database" => :check_database,
       "PGMQ schema" => :check_pgmq_schema,
       "Queues" => :check_queues,
@@ -166,6 +167,33 @@ module Pgbus
       Check.new(name: "Configuration", status: :fail, detail: "#{e.class}: #{e.message}")
     end
 
+    # 1b. Ruby JIT (issue #484). With Postgres close by, a worker is GVL-bound
+    # and YJIT is worth ~15-20% jobs/s (docs/performance.md). Rails enables it via
+    # config.yjit (load_defaults 7.2+, or 8.0+ outside local envs). Reports
+    # only — enabling a JIT is the application's decision, never pgbus's.
+    def check_ruby_jit
+      label = RubyJit.label
+      return Check.new(name: "Ruby JIT", status: :ok, detail: "#{label.upcase} enabled") unless label == "none"
+      return Check.new(name: "Ruby JIT", status: :ok, detail: "no YJIT available on this Ruby") unless RubyJit.yjit_available?
+      return Check.new(name: "Ruby JIT", status: :ok, detail: "YJIT off in a local environment (expected)") if local_env?
+
+      Check.new(name: "Ruby JIT", status: :warn,
+                detail: "YJIT is available but off — a CPU-bound worker (Postgres nearby) runs ~15% fewer jobs/s " \
+                        "without it; no measurable effect when network-bound. " \
+                        "Enable it with config.yjit = true (or load_defaults 7.2+) or RUBY_YJIT_ENABLE=1")
+    rescue StandardError => e
+      Check.new(name: "Ruby JIT", status: :warn, detail: "could not determine (#{e.class}: #{e.message})")
+    end
+
+    # A Rails app outside development/test. Without Rails the environment is
+    # unknown, so assume local and stay quiet rather than warn on a guess.
+    def local_env?
+      return true unless defined?(Rails) && Rails.respond_to?(:env) && Rails.env
+
+      env = Rails.env
+      env.respond_to?(:local?) ? env.local? : %w[development test].include?(env.to_s)
+    end
+
     # 2. Database connectivity — SELECT 1 via Client#ping.
     def check_database
       @client.ping

data/lib/pgbus/failed_event_recorder.rb

@@ -47,6 +47,23 @@ module Pgbus
         false
       end
 
+      # Drops every row recorded under any of `queue_names`. Called when a
+      # queue is dropped: PGMQ restarts msg_ids on recreate, so a surviving
+      # row would aim the dashboard's retry/discard at an unrelated message.
+      # Queue names are validated word characters, so the array literal is safe.
+      def clear_queue!(queue_names)
+        connection.exec_delete(
+          "DELETE FROM pgbus_failed_events WHERE queue_name = ANY($1::text[])",
+          "FailedEvent Clear Queue",
+          ["{#{queue_names.join(",")}}"]
+        )
+      rescue StandardError => e
+        Pgbus.logger.error do
+          "[Pgbus] Failed to clear failed events for dropped queue(s) #{queue_names.join(", ")}: " \
+            "#{e.class}: #{e.message}"
+        end
+      end
+
       def clear!(queue_name:, msg_id:)
         connection.exec_delete(
           "DELETE FROM pgbus_failed_events WHERE queue_name = $1 AND msg_id = $2",

data/lib/pgbus/process/claim_buffer.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Process
+    # The read-ahead buffer a Worker or Consumer owns (issue #486).
+    #
+    # Under database latency the claim loop used to issue one read round trip
+    # per job: once the pool is full, slots free one at a time and each loop
+    # step read `qty = free slots` = 1. With `read_ahead = N` the loop claims
+    # up to N messages beyond its free slots and parks them here, so one read
+    # returns a batch and the pool never waits on the reader.
+    #
+    # Surplus claims cannot live inside the execution pool: AsyncPool#post
+    # raises at zero capacity and a queued block could not be handed back on
+    # drain. So the buffer is drained into the pool only while it has a free
+    # slot, and returned to the queue (vt: 0) on drain, recycle or shutdown.
+    #
+    # Every buffered message is kept invisible by a VisibilityHeartbeat hold
+    # from claim until the run starts, under the executor's key
+    # (`source_queue || queue_name`, `prefixed: source_queue.nil?`), so the
+    # run's own tracking takes over the same entry with no gap. The hold does
+    # not know the job class, so a job that opted out with
+    # `pgbus_visibility_heartbeat false` is still held while it waits here:
+    # the opt-out covers its run, not the wait. With the heartbeat disabled
+    # globally there is no hold at all (Configuration#validate! warns).
+    #
+    # Only ever touched from the owning process's loop thread, so no mutex.
+    class ClaimBuffer
+      Claim = Struct.new(:queue_name, :message, :source_queue, :hold)
+
+      HOLD_LABEL = "(read-ahead)"
+
+      def initialize(config: Pgbus.configuration)
+        @config = config
+        @claims = []
+      end
+
+      def size
+        @claims.size
+      end
+
+      def empty?
+        @claims.empty?
+      end
+
+      def push(queue_name, message, source_queue = nil, client: Pgbus.client)
+        hold = VisibilityHeartbeat.hold(
+          client: client, queue_name: source_queue || queue_name, prefixed: source_queue.nil?,
+          msg_id: message.msg_id, job_class: HOLD_LABEL, config: @config
+        )
+        @claims << Claim.new(queue_name, message, source_queue, hold)
+        self
+      end
+
+      def shift
+        @claims.shift
+      end
+
+      # Yields the oldest claims, one per free pool slot, and returns how many.
+      # Capacity is re-read before every claim: the block's post takes a slot.
+      def drain_into(pool)
+        drained = 0
+        while !@claims.empty? && pool.available_capacity.positive?
+          yield @claims.shift
+          drained += 1
+        end
+        drained
+      end
+
+      # How many messages the next read should claim: enough to fill the free
+      # slots and top the buffer back up to `read_ahead`, never more than
+      # `prefetch_room` (prefetch_limit minus everything already claimed).
+      # With read_ahead 0 and an empty buffer this is `free_slots`: the
+      # pre-#486 qty.
+      def deficit(free_slots:, read_ahead:, prefetch_room: nil)
+        want = free_slots + read_ahead - @claims.size
+        want = [want, prefetch_room].min if prefetch_room
+        want.clamp(0..)
+      end
+
+      # Hand every buffered message back to the queue right away instead of
+      # leaving it invisible until its timeout. Their read_ct has already been
+      # bumped, the same cost a crash or a stale claim pays. A failed return
+      # is logged and skipped: the hold is already dropped, so the message
+      # reappears when its current timeout runs out. Returns the count. One
+      # claim at a time, so #size stays true while the returns are written.
+      def return_all!(client: Pgbus.client)
+        returned = 0
+        while (claim = @claims.shift)
+          return_claim(claim, client)
+          returned += 1
+        end
+        returned
+      end
+
+      private
+
+      # The hold goes first: a heartbeat tick that still held the entry could
+      # otherwise write its extension after the vt: 0 and hide the message
+      # again for a full visibility_timeout. (VisibilityHeartbeat#extend!
+      # re-checks registration, which shrinks the remaining window to the
+      # tick's own check-then-write.)
+      def return_claim(claim, client)
+        VisibilityHeartbeat.release(claim.hold)
+        queue = claim.source_queue || claim.queue_name
+        client.set_visibility_timeout(queue, claim.message.msg_id.to_i, vt: 0, prefixed: claim.source_queue.nil?)
+      rescue StandardError => e
+        Pgbus.logger.warn do
+          "[Pgbus] Could not return read-ahead message msg_id=#{claim.message.msg_id} queue=#{queue}: " \
+            "#{e.class}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/process/consumer.rb

@@ -7,7 +7,7 @@ module Pgbus
     class Consumer
       include SignalHandler
 
-      attr_reader :topics, :threads, :config, :execution_mode,
+      attr_reader :topics, :threads, :config, :execution_mode, :read_ahead,
                   :queue_names, :wake_signal, :notify_retry_backoff, :circuit_breaker
       # notify_listener is writable so tests can simulate a start_notify_listener
       # success from inside a stub (production sets it in start_notify_listener).
@@ -30,6 +30,11 @@ module Pgbus
         @jobs_processed.value
       end
 
+      # Messages claimed by read-ahead and not yet handed to the pool (#486).
+      def buffered
+        @claim_buffer.size
+      end
+
       # Seed the processed-job counter. Used by tests to drive the recycle
       # thresholds without running thousands of real jobs; production only ever
       # increments it via the AtomicFixnum during message handling.
@@ -60,7 +65,7 @@ module Pgbus
                      queue_names: nil, liveness_pipe: nil, stat_buffer: :default,
                      notify_listener: nil, notify_retry_at: 0.0,
                      notify_retry_backoff: NOTIFY_RETRY_BASE_SECONDS,
-                     started_at_monotonic: nil, wake_pipe: nil)
+                     started_at_monotonic: nil, wake_pipe: nil, read_ahead: nil)
         @topics = Array(topics)
         @threads = threads
         @config = config
@@ -68,6 +73,8 @@ module Pgbus
         @shutting_down = false
         @recycling = false
         @jobs_processed = Concurrent::AtomicFixnum.new(0)
+        @read_ahead = read_ahead || config.read_ahead
+        @claim_buffer = ClaimBuffer.new(config: config)
         @loop_tick_at = Concurrent::AtomicReference.new(nil)
         @started_at_monotonic = started_at_monotonic || monotonic_now
         @wake_signal = WakeSignal.new
@@ -134,7 +141,12 @@ module Pgbus
           check_recycle
           ensure_notify_listener
 
-          break if @shutting_down
+          if @shutting_down
+            # No drain loop here: buffered claims go straight back to the
+            # queue; shutdown then waits for the ones already running.
+            @claim_buffer.return_all!(client: Pgbus.client) unless @claim_buffer.empty?
+            break
+          end
 
           consume
           @stat_buffer&.flush_if_due
@@ -171,20 +183,35 @@ module Pgbus
         @queue_names = @registry.queue_names_for_topics(topics)
       end
 
+      # Same loop step as Worker#claim_and_execute (issue #486): feed
+      # buffered claims to free slots, read the deficit, feed again, and wait
+      # only when the step moved nothing.
       def consume
-        idle = @pool.available_capacity
-        return @wake_signal.wait(timeout: wake_timeout) if idle <= 0
-
-        tagged_messages = fetch_messages(idle)
-
-        if tagged_messages.empty?
-          @wake_signal.wait(timeout: wake_timeout)
-          return
+        drained = drain_claim_buffer
+        claimed = claim_deficit
+        drained += drain_claim_buffer
+        @wake_signal.wait(timeout: wake_timeout) if drained.zero? && claimed.zero?
+      end
+
+      # The hold is released before handle_message's own heartbeat tracking
+      # registers the same key, so the message is never untracked in between.
+      def drain_claim_buffer
+        @claim_buffer.drain_into(@pool) do |claim|
+          @pool.post do
+            VisibilityHeartbeat.release(claim.hold)
+            handle_message(claim.message, claim.queue_name)
+          end
         end
+      end
 
-        tagged_messages.each do |queue_name, message|
-          @pool.post { handle_message(message, queue_name) }
-        end
+      def claim_deficit
+        want = @claim_buffer.deficit(free_slots: @pool.available_capacity, read_ahead: @read_ahead)
+        return 0 if want.zero?
+
+        tagged_messages = fetch_messages(want)
+        client = Pgbus.client
+        tagged_messages.each { |queue_name, message| @claim_buffer.push(queue_name, message, client: client) }
+        tagged_messages.size
       end
 
       # Returns an array of [queue_name, message] pairs. Queues whose circuit

data/lib/pgbus/process/supervisor.rb

@@ -171,7 +171,7 @@ module Pgbus
       private_constant :ROLE_FLAGS
 
       def log_boot_banner
-        Pgbus.logger.info { "[Pgbus] boot: pgbus #{Pgbus::VERSION} pid=#{::Process.pid}" }
+        Pgbus.logger.info { "[Pgbus] boot: pgbus #{Pgbus::VERSION} pid=#{::Process.pid} jit=#{RubyJit.label}" }
         Pgbus.logger.info do
           "[Pgbus] boot: connection=#{redacted_connection_target} pool=#{banner_field { config.resolved_pool_size }}"
         end
@@ -330,6 +330,7 @@ module Pgbus
             queues: queues, threads: threads, config: config,
             single_active_consumer: single_active, consumer_priority: priority,
             execution_mode: exec_mode, group_mode: grp_mode,
+            read_ahead: config.read_ahead_for(worker_config),
             liveness_pipe: liveness_writer, wake_pipe: wake_reader
           )
           worker.run
@@ -498,6 +499,7 @@ module Pgbus
           setup_child_process
           load_rails_app
           consumer = Consumer.new(topics: topics, threads: threads, config: config,
+                                  read_ahead: config.read_ahead_for(consumer_config),
                                   liveness_pipe: liveness_writer, wake_pipe: wake_reader)
           consumer.run
         end

data/lib/pgbus/process/worker.rb

@@ -7,7 +7,7 @@ module Pgbus
     class Worker
       include SignalHandler
 
-      attr_reader :queues, :threads, :config, :execution_mode,
+      attr_reader :queues, :threads, :config, :execution_mode, :read_ahead,
                   :rate_counter, :wake_signal, :restore_streak, :lifecycle
       # stat_buffer is writable so a test can swap in a buffer double after
       # construction to assert graceful_shutdown / check_recycle flush it. The
@@ -35,7 +35,7 @@ module Pgbus
                      rate_counter: nil, wake_signal: nil, stat_buffer: :default,
                      notify_listener: nil, notify_retry_at: 0.0,
                      notify_retry_backoff: NOTIFY_RETRY_BASE_SECONDS,
-                     started_at_monotonic: nil, wake_pipe: nil)
+                     started_at_monotonic: nil, wake_pipe: nil, read_ahead: nil)
         @queues = Array(queues)
         @initial_queues = @queues.dup.freeze
         @wildcard = @queues.include?("*")
@@ -65,7 +65,10 @@ module Pgbus
         @last_wildcard_resolve = nil
         @jobs_processed = Concurrent::AtomicFixnum.new(0)
         @jobs_failed = Concurrent::AtomicFixnum.new(0)
+        # in_flight counts every claimed message: buffered and running.
         @in_flight = Concurrent::AtomicFixnum.new(0)
+        @read_ahead = read_ahead || config.read_ahead
+        @claim_buffer = ClaimBuffer.new(config: config)
         @loop_tick_at = Concurrent::AtomicReference.new(nil)
         @rate_counter = rate_counter || RateCounter.new(:processed, :failed, :dequeued)
         @started_at = Time.current
@@ -119,6 +122,7 @@ module Pgbus
           jobs_processed: @jobs_processed.value,
           jobs_failed: @jobs_failed.value,
           in_flight: @in_flight.value,
+          buffered: @claim_buffer.size,
           state: @lifecycle.state,
           execution_mode: @execution_mode,
           consumer_priority: @consumer_priority,
@@ -184,6 +188,9 @@ module Pgbus
           check_recycle
           refresh_wildcard_queues
           ensure_notify_listener
+          # Draining, paused or stopped: claims nobody will run here go back
+          # to the queue now rather than when their timeout runs out.
+          return_claims unless @lifecycle.can_process?
 
           break if @lifecycle.stopped?
           # quiesced? (all slots free), not idle? (any slot free) — exiting
@@ -240,32 +247,53 @@ module Pgbus
 
       private
 
+      # One loop step (issue #486): feed buffered claims to free slots, read
+      # the deficit (free slots + read_ahead - buffered, capped by
+      # prefetch_limit), feed again. With read_ahead 0 the buffer never
+      # outlives the step and qty is the free slot count, as before. Waits
+      # only when the step moved nothing, so a full pool with a topped-up
+      # buffer sleeps until a slot frees (the pool's on_state_change wakes it).
       def claim_and_execute
-        poll_interval = wake_timeout
-
-        idle = @pool.available_capacity
-        return @wake_signal.wait(timeout: poll_interval) if idle <= 0
-
-        if config.prefetch_limit
-          available = config.prefetch_limit - @in_flight.value
-          return @wake_signal.wait(timeout: poll_interval) if available <= 0
-
-          idle = [idle, available].min
+        drained = drain_claim_buffer
+        claimed = claim_deficit
+        drained += drain_claim_buffer
+        @wake_signal.wait(timeout: wake_timeout) if drained.zero? && claimed.zero?
+      end
+
+      # The hold is released before the executor's own heartbeat tracking
+      # registers the same key, so the message is never untracked in between.
+      def drain_claim_buffer
+        @claim_buffer.drain_into(@pool) do |claim|
+          @pool.post do
+            VisibilityHeartbeat.release(claim.hold)
+            process_message(claim.message, claim.queue_name, source_queue: claim.source_queue)
+          end
         end
+      end
 
-        tagged_messages = fetch_messages(idle)
+      def claim_deficit
+        prefetch_room = config.prefetch_limit && (config.prefetch_limit - @in_flight.value)
+        want = @claim_buffer.deficit(free_slots: @pool.available_capacity, read_ahead: @read_ahead,
+                                     prefetch_room: prefetch_room)
+        return 0 if want.zero?
 
-        if tagged_messages.empty?
-          @wake_signal.wait(timeout: poll_interval)
-          return
-        end
+        tagged_messages = fetch_messages(want)
+        return 0 if tagged_messages.empty?
 
         @rate_counter.increment(:dequeued, tagged_messages.size)
+        client = Pgbus.client
         tagged_messages.each do |queue_name, message, source_queue|
           detect_zombie(queue_name, message)
           @in_flight.increment
-          @pool.post { process_message(message, queue_name, source_queue: source_queue) }
+          @claim_buffer.push(queue_name, message, source_queue, client: client)
         end
+        tagged_messages.size
+      end
+
+      def return_claims
+        return if @claim_buffer.empty?
+
+        @in_flight.decrement(@claim_buffer.return_all!(client: Pgbus.client))
       end
 
       # Returns an array of [queue_name, message] pairs so we always know
@@ -831,7 +859,8 @@ module Pgbus
           "rates" => @rate_counter.rates.transform_keys(&:to_s),
           "jobs_processed" => @jobs_processed.value,
           "jobs_failed" => @jobs_failed.value,
-          "in_flight" => @in_flight.value
+          "in_flight" => @in_flight.value,
+          "buffered" => @claim_buffer.size
         }
       end
 

data/lib/pgbus/ruby_jit.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Pgbus
+  # Reports which Ruby JIT this process runs under (issue #484). Read-only:
+  # Rails owns turning YJIT on (config.yjit), pgbus only makes the state
+  # visible in the boot log and `pgbus doctor`.
+  module RubyJit
+    module_function
+
+    def label
+      return "yjit" if yjit_available? && RubyVM::YJIT.enabled?
+      return "zjit" if defined?(RubyVM::ZJIT) && RubyVM::ZJIT.enabled?
+
+      "none"
+    end
+
+    def yjit_available?
+      defined?(RubyVM::YJIT) ? true : false
+    end
+  end
+end

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.17.0"
+  VERSION = "0.17.1"
 end

data/lib/pgbus/visibility_heartbeat.rb

@@ -30,8 +30,9 @@ module Pgbus
     #
     # The ninth member takes the struct out of the 80-byte slot it used to fit
     # (measured: 80 → 160). That is paid at most once per in-flight message, so
-    # the whole table is bounded by the execution pool's capacity — a handful of
-    # entries per process, not one per enqueued job.
+    # the whole table is bounded by the execution pool's capacity plus the
+    # read-ahead buffer (threads + read_ahead per process, issue #486) — a
+    # handful of entries per process, not one per enqueued job.
     Entry = Struct.new(:client, :queue_name, :prefixed, :msg_id, :job_class, :extended_at, :extensions,
                        :concurrency, :on_beat, keyword_init: true)
 
@@ -81,6 +82,25 @@ module Pgbus
         end
       end
 
+      # Keep a claimed-but-not-started message invisible until #release.
+      # Used by Process::ClaimBuffer for read-ahead (issue #486): a buffered
+      # message waits for a free slot and must not be redelivered meanwhile.
+      # Same key as #track, so the run's own tracking takes over after the
+      # hold is released. Returns the entry, or nil when the heartbeat is off.
+      def hold(client:, queue_name:, msg_id:, prefixed: true, job_class: nil, config: Pgbus.configuration)
+        return unless config.visibility_heartbeat
+
+        entry = Entry.new(client: client, queue_name: queue_name, prefixed: prefixed, msg_id: msg_id.to_i,
+                          job_class: job_class, extended_at: monotonic_now, extensions: 0)
+        register(entry, config)
+        entry
+      end
+
+      # Drop a #hold. A nil entry (heartbeat off) is a no-op.
+      def release(entry)
+        unregister(entry) if entry
+      end
+
       # Extend every tracked message whose last extension is older than the
       # heartbeat interval. Public so tests and callers without the thread
       # can drive it.
@@ -127,11 +147,22 @@ module Pgbus
         end
       end
 
+      # Only the entry that is registered under the key: a stale hold released
+      # after #track re-registered the same message must not drop the running
+      # job's entry (issue #486).
       def unregister(entry)
-        synchronize { entries.delete(key_for(entry)) }
+        synchronize do
+          key = key_for(entry)
+          entries.delete(key) if entries[key].equal?(entry)
+        end
       end
 
       def extend!(entry, now:, config:)
+        # tick! picked this entry under the mutex but runs here without it: if
+        # the entry was released meanwhile (a read-ahead claim handed back with
+        # vt: 0, a job that finished), extending it would undo that.
+        return unless registered?(entry)
+
         vt = config.visibility_timeout
         entry.client.set_visibility_timeout(entry.queue_name, entry.msg_id, vt: vt, prefixed: entry.prefixed)
         entry.extended_at = now
@@ -218,6 +249,10 @@ module Pgbus
         @entries ||= {}
       end
 
+      def registered?(entry)
+        synchronize { entries[key_for(entry)].equal?(entry) }
+      end
+
       def key_for(entry)
         [entry.queue_name, entry.msg_id]
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.17.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -348,6 +348,7 @@ files:
 - lib/pgbus/pgmq_schema/pgmq_v1.11.1.sql
 - lib/pgbus/pgmq_schema/pgmq_v1.12.0.sql
 - lib/pgbus/pgmq_schema/pgmq_v1.13.0.sql
+- lib/pgbus/process/claim_buffer.rb
 - lib/pgbus/process/consumer.rb
 - lib/pgbus/process/consumer_priority.rb
 - lib/pgbus/process/dispatcher.rb
@@ -376,6 +377,7 @@ files:
 - lib/pgbus/recurring/scheduler.rb
 - lib/pgbus/recurring/task.rb
 - lib/pgbus/retry_backoff.rb
+- lib/pgbus/ruby_jit.rb
 - lib/pgbus/serializer.rb
 - lib/pgbus/stat_buffer.rb
 - lib/pgbus/streams.rb