async-background 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 823b13ecbf3740e79a15a9c24f0195a2d09bbc49bb189885d0738a0636cf913c
-  data.tar.gz: 4424725707108aaf8249b8ea62e500ccaa884bbc5392a4691cdcdc540ea5fda4
+  metadata.gz: 1da83cfa99bb2a77a32b8bd72dd5bee692f94f87b453706f4443cc015e065ac4
+  data.tar.gz: b0c60214b0e13a7a0c346f5e681d78b1701a7de95e5e816f84193d6593f2c282
 SHA512:
-  metadata.gz: 3e0d13f6b354efdd47fe4d93c464eb4411eb4658bd91fc9f3a2a154fd0300d72982680d98b454180c958ac93c15c3a7500df6c0ec346508c0791f6503525c042
-  data.tar.gz: 53a18f4ce6f47db152a303f456f5ba80cd3b706ceaee4e1aac35d752e8067c2e1eb807765117a77837e838376740a61c91690ac4714dd5853ae062c41cbd6c3e
+  metadata.gz: 6cdc11bc1e0bbfb5d76e8d26bb80a71d498c3a04a0fbd1a7e3212640c3f0ae1513fb8bb18784e1dfdd7b96aafc1771ed8cf0db00ac1fedde8e63579943df1e2b
+  data.tar.gz: ed97b4b602abb304db44199247b533d2fce410ab8a3a80182e9a08ac65eff680d0df198f529ef53b87e947ccf8114b4e89e333f5695928fc1b0137b6dff90c53

data/CHANGELOG.md

@@ -1,5 +1,158 @@
 # Changelog
 
+## 1.1.0
+
+The gem no longer depends on `async`. The same worker runs under any
+`Fiber::Scheduler` the host installs — Falcon/Async, Itsi, or another
+implementation.
+
+### Breaking
+
+- `Runner#run` no longer starts a reactor. It needs an active
+  `Fiber.scheduler` and raises `Runtime::SchedulerRequired` without one:
+
+  ```ruby
+  Async { runner.run }                             # Falcon / Async
+  Async::Background::Scheduler.run { runner.run }  # async or itsi via ENV
+  ```
+
+- Job timeouts raise `Async::Background::Runtime::TimeoutError` instead of
+  `Async::TimeoutError`. Update rescue sites and any stored `error_class`.
+- `Runner#drain_jobs` is bounded (`drain_timeout:` default 30s). In-flight jobs
+  that outlive it are cancelled. Pass `drain_timeout: nil` for an unbounded wait.
+- `TaskGroup#stop_all(grace = nil)` returns whether the group drained, not a
+  count of cancelled tasks.
+- `Async::Background::Error` is the base class for `Runtime::Error` and
+  `ConfigError`. Both are still `StandardError`.
+
+### Added
+
+- `Async::Background::Runtime` — `Task`, `TaskGroup`, `Semaphore`,
+  `Notification`, `with_timeout`, `native_timeouts?`, `with_error_handler`.
+- `Async::Background::Scheduler` — optional bootstrap
+  (`require "async/background/scheduler"`) that installs `async` or
+  `itsi-scheduler` from `ASYNC_BACKGROUND_SCHEDULER`. `Scheduler.preload!`
+  loads the gem before fork. `Scheduler.run` on Itsi uses the current thread;
+  `ASYNC_BACKGROUND_SCHEDULER_THREAD=1` restores a dedicated thread.
+
+### Fixed
+
+- The saturated-queue wake-up fires from `TaskGroup#on_release`, after the job
+  has left `@jobs`. Signalling from the task's `ensure` left the listener
+  seeing a full group on any scheduler that resumes `unblock` immediately.
+- `Runtime.with_timeout` calls `scheduler.timeout_after` when the hook exists.
+  The `::Timeout.timeout` fallback uses `Thread#raise` and can hit the wrong
+  fiber; a missing hook now warns once per scheduler class.
+- `SocketWaker#close` stops the accept loop before the self-connect that
+  unblocks it, and hangs up tracked client sockets. A fiber parked in
+  `IO#wait_readable` is not cancellable via `Task#stop` on a scheduler without
+  `#fiber_interrupt`.
+- `Runtime.error_handler` is scoped per runner (`on_error:` /
+  `with_error_handler`). A process-global handler was overwritten by the next
+  runner and never restored.
+- A failure awaited via `Task#wait` is no longer also sent to the error handler.
+- `Semaphore.new(0)` raises `ArgumentError` instead of deadlocking on acquire.
+
+### Changed
+
+- `async` is a development dependency. Runtime gems are `console`, `fugit`
+  and `base64`.
+- `SocketWaker#start_accept_loop` no longer needs a parent task (the
+  argument is still accepted and ignored).
+- Shutdown closes the waker before the store, so the listener cannot be inside
+  `Store#fetch` when the connection disappears.
+
+### Unchanged
+
+- Dashboard, `perform_async` / `perform_in` / `perform_at`, SQLite schema,
+  and the cross-process wake protocol.
+
+## 1.0.2
+
+Queue maintenance bug fix plus profiler-driven work on the hot paths that
+actually showed up in StackProf: the sqlite3 statement wrapper, transaction
+control, and the socket notifier.
+
+### Fixed
+
+- `Store#cleanup_finished_jobs` tested `@db.changes` after running *both*
+  DELETEs. `sqlite3_changes()` reports only the most recent statement, so the
+  incremental-vacuum decision saw the failed-job count alone and ignored every
+  deleted done-job. On a busy queue, where done-jobs vastly outnumber failed
+  ones, the vacuum effectively never ran and the database file grew without
+  bound. Both counts are now summed.
+- `PRAGMA incremental_vacuum` ran without a page limit, releasing every free
+  page in a single blocking call — an unbounded reactor stall proportional to
+  the accumulated free list. Now capped at 64 pages per call
+  (`SQL::INCREMENTAL_VACUUM_PAGES`).
+- `SocketWaker` signalled its notification only from the `ensure` block, so a
+  wake-up was really driven by the client disconnecting rather than by the
+  wake byte arriving. It happened to work because `SocketNotifier` closes
+  immediately after writing, but it made the protocol depend on a disconnect.
+  The signal now fires for every byte received; the `ensure` still signals so a
+  disconnect racing with a read cannot drop a wake-up.
+
+### Performance
+
+Measured on the `enqueue_stress` CI scenario (2.1M inserts / 30s, two producer
+processes). `SQLite3::Statement#step` accounts for ~82% of producer wall time
+and is irreducible; the changes below target what surrounded it.
+
+- `Store#enqueue` and `Store#fetch` bind and step their prepared statements
+  directly instead of calling `Statement#execute`. The wrapper built a splat
+  array, ran `Array#flatten` over it and allocated a `ResultSet` — roughly 8%
+  of producer wall time, and `Array#flatten` alone was 5.8% of all object
+  allocations. Behaviour is unchanged: `execute` only steps when
+  `column_count == 0`, which is exactly what the INSERT path needed, and the
+  `UPDATE ... RETURNING` fetch still consumes a single row.
+- `SocketNotifier` caches its socket paths at construction. It previously ran
+  `File.join` plus a string interpolation on every enqueue attempt —
+  13.3% of allocations in the normal scenario.
+- `SocketNotifier` remembers unreachable workers for `DEAD_WORKER_TTL` (5s)
+  instead of reconnecting to them on every enqueue. Because the scan started at
+  a random index, a dead worker was re-probed indefinitely and each attempt
+  raised and swallowed an `Errno`; `SystemCallError#initialize` alone was 6.8%
+  of allocations. A worker that starts during the TTL window is still picked up
+  by the listener's own polling fallback.
+- `SocketNotifier` rotates its scan start with a cursor rather than calling
+  `rand` per enqueue, which also spreads wake-ups deterministically.
+- `Errno::EAGAIN` on the wake byte (`IO::WaitWritable`) is now treated as
+  success rather than falling through to the generic rescue and logging a
+  warning: a full send buffer means the worker already has unread wake-ups.
+- `Store#transaction` runs `BEGIN IMMEDIATE`, `COMMIT` and `ROLLBACK` as
+  prepared statements. They previously went through `Database#execute`, which
+  compiles a fresh `Statement` and builds a `ResultSet` on every call: 26
+  allocations per BEGIN+COMMIT pair against 2 prepared, and 6x the wall time
+  over 30k pairs. Every `fetch` paid this twice, and it was 11.8% of worker
+  allocations in the object profile.
+- `mark_started!`, `complete`, `fail`, `retry_job!`, `recover`,
+  `stored_options_for`, `lease_alive?`, `next_pending_run_at` and the two
+  cleanup DELETEs now bind and step directly, like `enqueue` and `fetch`
+  already did. `Statement#execute` is gone from the Store entirely;
+  `Database#execute` remains only on the cold pragma path. This is what was
+  still leaving `Array#flatten` at 4.9% of worker allocations and
+  `Statement#execute` at 10.8% of worker wall time.
+- Combined effect on a full job cycle (enqueue omitted; fetch + mark_started +
+  complete, 8000 jobs, measured twice): **49 -> 18 allocations per job**, wall
+  time down roughly 10-20% depending on run.
+- `@db.changes` and `@db.last_insert_row_id` are read after the statement is
+  reset; both were verified to survive `sqlite3_reset()`, so the claim-token
+  lease checks behave exactly as before (valid token true, stale token false,
+  repeat completion false).
+
+### Notes
+
+- `SocketNotifier` still opens a fresh connection per notification. This is
+  the largest remaining win and it is paid on both sides: 8.5% of producer wall
+  time in the scenario where workers are actually up, plus 16.4% of worker
+  allocations, because every connection makes `SocketWaker#handle_client` spawn
+  a fresh `Async::Task` and fiber. Persistent connections require the
+  `SocketWaker` fix above to be deployed on every worker first — a 1.0.2 producer holding a connection open
+  to a 1.0.1 worker would never wake it, silently degrading queue latency to
+  the 5s poll interval. Deferred until 1.0.2 is the deployed floor.
+- No schema change; `Schema::VERSION` is untouched and 1.0.2 is a drop-in
+  replacement for 1.0.1 on an existing database.
+
 ## 1.0.1
 
 Dashboard security headers and a fiber-native rewrite of the SSE stream.

data/README.md

@@ -1,8 +1,8 @@
 # Async::Background
 
-A lightweight cron, interval, and job-queue scheduler for Ruby's
-[Async](https://github.com/socketry/async) ecosystem. Built for
-[Falcon](https://github.com/socketry/falcon), works with any Async app.
+A lightweight cron, interval, and job-queue scheduler for Ruby fibers.
+Works with any `Fiber::Scheduler` — [Falcon](https://github.com/socketry/falcon) /
+[Async](https://github.com/socketry/async), [Itsi](https://itsi.fyi), or your own.
 
 - **Cron & interval scheduling** on a single event loop with a min-heap.
 - **Dynamic job queue** backed by SQLite, with delayed jobs
@@ -15,11 +15,11 @@ A lightweight cron, interval, and job-queue scheduler for Ruby's
 
 ---
 
-## Why Async? Why fibers?
+## Why fibers?
 
-The whole gem is built around the assumption that Falcon's reactor schedules
-many fibers on top of one OS thread per process — so the dashboard's SSE
-stream, the cron scheduler, and the queue worker all share that one thread
+The whole gem is built around the assumption that the host schedules many
+fibers on top of one OS thread per process — so the dashboard's SSE stream,
+the cron scheduler, and the queue worker all share that one thread
 cooperatively. A blocked fiber yields; a blocked thread doesn't.
 
 ![Threads vs fibers under different Ruby web servers](docs/fibers-vs-threads.svg)
@@ -30,13 +30,31 @@ open tab.
 
 ---
 
+## Fiber scheduler
+
+`Runner#run` does not start a reactor. The host must install a
+`Fiber.scheduler` first:
+
+```ruby
+Async { runner.run }  # Falcon / Async
+
+require "async/background/scheduler"
+Async::Background::Scheduler.run { runner.run }  # ASYNC_BACKGROUND_SCHEDULER=async|itsi
+```
+
+Without a scheduler it raises `Runtime::SchedulerRequired`.
+Worker setup for Falcon and Itsi is in [Get started](docs/GET_STARTED.md).
+
+---
+
 ## Requirements
 
 | Dependency           | Version          | Required?            |
 | -------------------- | ---------------- | -------------------- |
 | Ruby                 | `>= 3.3`         | yes                  |
-| `async`              | `~> 2.0`         | yes                  |
+| a `Fiber::Scheduler` | `async ~> 2.0`, `itsi-scheduler`, … | yes — installed by the host, not by this gem |
 | `fugit`              | `~> 1.0`         | yes                  |
+| `console`            | `~> 1.0`         | yes                  |
 | `sqlite3`            | `~> 2.0`         | for the queue & dashboard |
 | `async-utilization`  | `>= 0.3, < 0.5`  | for metrics          |
 
@@ -48,16 +66,16 @@ open tab.
 # Gemfile
 gem "async-background"
 
-gem "sqlite3",           "~> 2.0"          # if you use the queue or dashboard
-gem "async-utilization", ">= 0.3", "< 0.5" # if you want worker metrics
+gem "async", "~> 2.0"          # or `itsi-scheduler`
+gem "sqlite3", "~> 2.0"        # queue / dashboard
+gem "async-utilization", ">= 0.3", "< 0.5"  # optional metrics
 ```
 
 ---
 
 ## ➡️ [Get started](docs/GET_STARTED.md)
 
-A four-step walkthrough: schedule config, Falcon integration, Docker, queue,
-delayed jobs.
+Schedule config, Falcon or Itsi workers, Docker, queue, delayed jobs.
 
 ---
 
@@ -120,9 +138,12 @@ jobs use wall-clock time, because "every day at 3am" needs to mean 3am.
 
 ## How it works
 
-A single Async task sleeps until the next entry is due, then dispatches it
-under a semaphore that caps concurrency. Overlapping ticks are skipped and
-rescheduled.
+A single fiber sleeps until the next entry is due, then dispatches it under a
+semaphore that caps concurrency. Overlapping ticks are skipped and rescheduled.
+Every dispatched job is tracked in a `Runtime::TaskGroup`, so shutdown drains
+in-flight work before the SQLite store and the wake-up socket are closed. The
+drain is bounded by `drain_timeout:` (30s by default; pass `nil` for the old
+unbounded wait) so one wedged job cannot turn SIGTERM into SIGKILL.
 
 ```
 schedule.yml → build_heap → MinHeap<Entry> → scheduler loop → Semaphore → run_job

data/async-background.gemspec

@@ -8,12 +8,13 @@ Gem::Specification.new do |spec|
   spec.authors = ['Roman Hajdarov']
   spec.email   = ['romnhajdarov@gmail.com']
 
-  spec.summary     = 'Lightweight heap-based cron/interval scheduler for Async.'
-  spec.description = 'A production-grade lightweight scheduler built on top of Async. ' \
-                     'Single event loop with min-heap timer, skip-overlapping execution, ' \
-                     'jitter, monotonic clock intervals, semaphore concurrency control, ' \
-                     'and deterministic worker sharding. Designed for Falcon but works ' \
-                     'with any Async-based application.'
+  spec.summary     = 'Lightweight heap-based cron/interval scheduler for any Fiber scheduler.'
+  spec.description = 'A production-grade lightweight background job scheduler built on the ' \
+                     'Fiber::Scheduler interface itself, not on any one implementation: it ' \
+                     'runs under Async/Falcon, Itsi, or anything else that installs a ' \
+                     'scheduler. Single event loop with min-heap timer, skip-overlapping ' \
+                     'execution, jitter, monotonic clock intervals, semaphore concurrency ' \
+                     'control, and deterministic worker sharding.'
 
   spec.homepage = 'https://github.com/roman-haidarov/async-background'
   spec.license  = 'MIT'
@@ -30,15 +31,20 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 3.3'
 
-  spec.add_dependency 'async',   '~> 2.0'
+  # No scheduler dependency on purpose. The gem uses the Fiber::Scheduler
+  # interface (Fiber.schedule, #block/#unblock, Timeout) and requires the host
+  # to install an implementation.
   spec.add_dependency 'console', '~> 1.0'
   spec.add_dependency 'fugit',   '~> 1.0'
   spec.add_dependency 'base64',  '~> 0.2'
 
   # Optional: add to your own Gemfile if you need these features
+  #   gem 'async', '~> 2.0'                      # or any other Fiber scheduler
+  #   gem 'itsi-scheduler'                       # ... such as this one
   #   gem 'sqlite3', '~> 2.0'
   #   gem 'async-utilization', '>= 0.3', '< 0.5' # shared-memory worker metrics
 
+  spec.add_development_dependency 'async', '~> 2.0'
   spec.add_development_dependency 'rake',  '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.12'
   spec.add_development_dependency 'rack',  '~> 3.0'

data/lib/async/background/metrics.rb

@@ -127,9 +127,7 @@ module Async
         end
 
         def decode_workers(buffer, schema, segment, total_workers)
-          (1..total_workers).map do |worker|
-            decode_worker(buffer, schema, segment, worker)
-          end.freeze
+          (1..total_workers).map { |worker| decode_worker(buffer, schema, segment, worker) }.freeze
         end
 
         def decode_worker(buffer, schema, segment, worker)

data/lib/async/background/queue/schema.rb

@@ -29,11 +29,9 @@ module Async
 
           enable_incremental_vacuum!(db) unless jobs_table?(db)
 
-          with_migration_timeout(db) do
-            immediate_transaction(db) do
-              reject_future_version!(db)
-              upgrade!(db) unless current?(db)
-            end
+          synchronized_change(db) do
+            reject_future_version!(db)
+            upgrade!(db) unless current?(db)
           end
         end
 
@@ -41,20 +39,20 @@ module Async
           migrate!(db)
           return if dashboard_indexes_current?(db)
 
-          with_migration_timeout(db) do
-            immediate_transaction(db) do
-              create_dashboard_indexes!(db) unless dashboard_indexes_current?(db)
-            end
+          synchronized_change(db) do
+            create_dashboard_indexes!(db) unless dashboard_indexes_current?(db)
           end
         end
 
+        def synchronized_change(db, &change)
+          with_migration_timeout(db) { immediate_transaction(db, &change) }
+        end
+
         def current?(db)
           jobs_table?(db) && version(db) == VERSION && core_indexes_current?(db)
         end
 
-        def dashboard_indexes_current?(db)
-          (DASHBOARD_INDEXES - index_names(db)).empty?
-        end
+        def dashboard_indexes_current?(db) = indexes_present?(db, DASHBOARD_INDEXES)
 
         def version(db)
           db.get_first_value(SQL::USER_VERSION).to_i
@@ -101,8 +99,10 @@ module Async
           SQL::CREATE_DASHBOARD_INDEXES.each { |statement| db.execute(statement) }
         end
 
-        def core_indexes_current?(db)
-          (CORE_INDEXES - index_names(db)).empty?
+        def core_indexes_current?(db) = indexes_present?(db, CORE_INDEXES)
+
+        def indexes_present?(db, names)
+          (names - index_names(db)).empty?
         end
 
         def jobs_table?(db)

data/lib/async/background/queue/socket_notifier.rb

@@ -2,10 +2,14 @@
 
 require 'socket'
 
+require_relative '../clock'
+
 module Async
   module Background
     module Queue
       class SocketNotifier
+        include Clock
+
         # Errors that indicate a worker is unavailable - silently skip and try the next.
         UNAVAILABLE = [
           Errno::ENOENT,        # Socket file doesn't exist (worker hasn't started yet)
@@ -14,41 +18,68 @@ module Async
           Errno::ECONNRESET     # Connection reset by peer
         ].freeze
 
+        DEAD_WORKER_TTL = 5.0
+        WAKE_BYTE = "\x01".freeze
+
         def initialize(socket_dir:, total_workers:)
           @socket_dir = socket_dir
           @total_workers = total_workers
+          @paths = build_paths
+          @dead_until = Array.new([@total_workers, 0].max, 0.0)
+          @cursor = 0
         end
 
         def notify_all
-          return if @total_workers <= 0
+          return false if @total_workers <= 0
+
+          now = monotonic_now
+          start = advance_cursor
 
-          start = rand(@total_workers)
-          @total_workers.times do |i|
-            worker_index = ((start + i) % @total_workers) + 1
-            return if notify_one(worker_index)
+          @total_workers.times do |offset|
+            index = (start + offset) % @total_workers
+            return true if notify_one(index, now)
           end
+
+          false
         end
 
         private
 
-        def notify_one(worker_index)
-          path = socket_path(worker_index)
-          sock = UNIXSocket.new(path)
+        def build_paths
+          return [].freeze if @total_workers <= 0
+
+          Array.new(@total_workers) do |index|
+            File.join(@socket_dir, "async_bg_worker_#{index + 1}.sock").freeze
+          end.freeze
+        end
+
+        def advance_cursor
+          @cursor = (@cursor + 1) % @total_workers
+        end
+
+        def notify_one(index, now)
+          return false if @dead_until[index] > now
+
+          socket = UNIXSocket.new(@paths[index])
           begin
-            sock.write_nonblock("\x01")
+            socket.write_nonblock(WAKE_BYTE)
           ensure
-            sock.close rescue nil
+            socket.close rescue nil
           end
           true
+        rescue IO::WaitWritable
+          true
         rescue *UNAVAILABLE
+          mark_dead(index, now)
           false
         rescue => e
-          Console.logger.warn(self) { "SocketNotifier#notify_one(#{worker_index}) failed: #{e.class} #{e.message}" } rescue nil
+          mark_dead(index, now)
+          Console.logger.warn(self) { "SocketNotifier#notify_one(#{index + 1}) failed: #{e.class} #{e.message}" } rescue nil
           false
         end
 
-        def socket_path(worker_index)
-          File.join(@socket_dir, "async_bg_worker_#{worker_index}.sock")
+        def mark_dead(index, now)
+          @dead_until[index] = now + DEAD_WORKER_TTL
         end
       end
     end