async-background 0.4.5 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9a1ac97495dc7d6a39adf802a847b62e3601df0fe0ef4aa70dbcc248a2f77b8
-  data.tar.gz: 74bab717411caf3e8a7b469666e9df5f8f59d540ebd98446c5e44e167cacd3c9
+  metadata.gz: 26e459d9e86a150ff8b3126ce8899ac9beb60355e3313d5510c1c0c6dec0bfd7
+  data.tar.gz: 93a52a9139f902e1acee7b58ea98dceadba2219537329b785f3a103009f72401
 SHA512:
-  metadata.gz: fe41a129f66a72c51016397b866ee9ff31b973d5e92ee6af1f61c05ce87f8f85f9824a68499caefcf950cdb33186c74749817e0ae8b89a483ede580d412e13fc
-  data.tar.gz: 92208ce41c49095cdf652b798ed892e4db5ae12c504cfe94c45bf124054256a94906fba14f68365f938a6d7289c76ca79d7ae7f6fac53bb76d8097d463db684f
+  metadata.gz: 3dcfcc9089b2bb8b5b3fb01341039fa1dea32896f6e3845f137bd9e307b366b2716208d4ecb533b266cf31c3b0466535817d7dc9d6c1a0876e113519417a0512
+  data.tar.gz: ece53f421338c16a02548754a6c1a2e8a62988659a83f4575e8ad23d01fd987958e6d3fb94360607444ff34a4dc0fb8844fdfdbca9228c2c8af09b1aec486b36

data/CHANGELOG.md

@@ -0,0 +1,160 @@
+# Changelog
+
+## 0.5.1
+
+### Testing Infrastructure
+- **Comprehensive CI setup** — full Docker-based integration testing environment with `Dockerfile.ci`, `docker-compose.ci.yml`, and `Gemfile.ci`
+- **End-to-end scenario testing** — new `ci/scenario_test.rb` validates real-world scenarios with forked workers:
+  - Normal execution of fast/slow/failing jobs across multiple workers
+  - Crash recovery after SIGKILL with automatic job pickup by remaining workers
+  - No duplicate execution guarantees under worker crashes
+  - Proper job distribution validation across worker pool
+- **Test fixtures** — dedicated `ci/fixtures/jobs.rb` and `ci/fixtures/schedule.yml` for scenario testing
+
+### Bug Fixes  
+- **SQLite busy timeout** — added `PRAGMA busy_timeout = 5000` to `Queue::Store` to prevent `SQLITE_BUSY` errors under concurrent multi-process database access
+- **Enhanced Queue::Notifier error handling** — restructured IO error handling with clearer categorization:
+  - `WRITE_DROPPED` for write failures (`IO::WaitWritable`, `Errno::EAGAIN`, `IOError`, `Errno::EPIPE`) — all non-fatal as job is already in store
+  - `READ_EXHAUSTED` for read exhaustion (`IO::WaitReadable`, `EOFError`, `IOError`) — normal drain completion
+  - Added explanatory comments for each error type and handling strategy
+
+## 0.5.0
+
+### Features
+- **Delayed jobs** — full support for scheduling jobs in the future
+  - `Queue::Client#push_in(delay, class_name, args)` — enqueue with delay in seconds
+  - `Queue::Client#push_at(time, class_name, args)` — enqueue at a specific time
+  - `Queue.enqueue_in(delay, job_class, *args)` — class-level delayed enqueue
+  - `Queue.enqueue_at(time, job_class, *args)` — class-level scheduled enqueue
+  - New `run_at` column in SQLite `jobs` table — jobs are only fetched when `run_at <= now`
+- **Job module** — Sidekiq-like `include Async::Background::Job` interface
+  - `perform_async(*args)` — immediate queue execution
+  - `perform_in(delay, *args)` — delayed execution after N seconds
+  - `perform_at(time, *args)` — scheduled execution at a specific time
+  - Instance-level `#perform` with class-level `perform_now` delegation
+- **Clock module** — shared `monotonic_now` / `realtime_now` helpers extracted into `Async::Background::Clock`, included by `Runner`, `Queue::Store`, and `Queue::Client`
+
+### Bug Fixes
+- **Runner: incorrect task in `with_timeout`** — `semaphore.async { |job_task| ... }` now correctly receives the child task instead of capturing the parent `task` from the outer scope. Previously, `with_timeout` was applied to the parent task, which could cancel unrelated work
+
+### Improvements
+- **Job API: `#perform` instead of `#perform_now`** — job classes now define `#perform` instance method. The class-level `perform_now` creates instance and calls `#perform`, aligning with ActiveJob / Sidekiq conventions
+- Updated error messages: validation failures now suggest `must include Async::Background::Job` instead of `must implement .perform_now`
+- `Queue::Client` — extracted private `ensure_configured!` and `resolve_class_name` methods for cleaner validation and class name resolution logic
+- `Queue::Notifier` — extracted `IO_ERRORS` constant (`IO::WaitReadable`, `EOFError`, `IOError`) for cleaner `rescue` in `drain`
+- `Queue::Store` — replaced index `idx_jobs_status_id(status, id)` with `idx_jobs_status_run_at_id(status, run_at, id)` for efficient delayed job lookups
+- `Queue::Store` — `fetch` SQL now uses `WHERE status = 'pending' AND run_at <= ?` with `ORDER BY run_at, id` to process jobs in scheduled order
+- Removed duplicated `monotonic_now` / `realtime_now` from `Runner` and `Store` — now provided by `Clock` module
+- Updated documentation: README (Job module examples, Queue architecture diagram, Clock section), GET_STARTED (delayed jobs guide, Job module usage, minimal queue-only example)
+
+## 0.4.5
+
+### Breaking Changes
+- `PRAGMAS` is now a frozen lambda `PRAGMAS.call(mmap_size)` instead of a static string — if you referenced this constant directly, update your code
+
+### Features
+- New `queue_mmap:` parameter on `Runner` (default: `true`) — allows disabling SQLite mmap for environments where it's unsafe (Docker overlay2)
+- New `mmap:` parameter on `Queue::Store` (default: `true`) — controls `PRAGMA mmap_size` (256 MB when enabled, 0 when disabled)
+- Public `attr_reader :queue_store` on `Runner` — eliminates need for `instance_variable_get` when sharing Store with Client
+
+### Bug Fixes
+- **CRITICAL: fetch race condition** — wrapped `UPDATE ... RETURNING` in `BEGIN IMMEDIATE` transaction to prevent two workers from picking up the same job simultaneously
+- **CRITICAL: mmap + Docker overlay2** — `overlay2` filesystem does not guarantee `write()`/`mmap()` coherence, causing SQLite WAL corruption under concurrent multi-process access. mmap is now configurable via `queue_mmap: false` instead of being hardcoded. Documented proper Docker setup with named volumes in `docs/GET_STARTED.md`
+- **`PRAGMA optimize` on shutdown** — wrapped in `rescue nil` to prevent `SQLite3::BusyException` when another process holds the write lock during graceful shutdown
+- **`PRAGMA incremental_vacuum` was a no-op** — added `PRAGMA auto_vacuum = INCREMENTAL` to schema. Without it, `incremental_vacuum` does nothing. Note: only takes effect on newly created databases; existing databases require a one-time `VACUUM`
+
+### Improvements
+- Replaced index `idx_jobs_status(status)` with composite `idx_jobs_status_id(status, id)` — eliminates sort step in `fetch` query (`ORDER BY id LIMIT 1` is now a direct B-tree lookup)
+- Fixed `finalize_statements` — changed `%i[@enqueue_stmt ...]` to `%i[enqueue_stmt ...]` with `:"@#{name}"` interpolation for idiomatic `instance_variable_get`/`set` usage
+- Added documentation: `README.md` (concise, with warning markers) and `docs/GET_STARTED.md` (step-by-step guide covering schedule config, Falcon integration, Docker setup, dynamic queue)
+
+## 0.4.0
+
+### Features
+- **Dynamic job queue** — enqueue jobs at runtime from any process (web, console, rake) with automatic execution by background workers
+  - `Queue::Store` — SQLite-backed persistent storage with WAL mode, prepared statements, and optimized pragmas
+  - `Queue::Notifier` — `IO.pipe`-based zero-cost wakeup between producer and consumer processes (no polling)
+  - `Queue::Client` — public API: `Async::Background::Queue.enqueue(JobClass, *args)`
+  - Automatic recovery of stale `running` jobs on worker restart
+  - Periodic cleanup of completed jobs (piggyback on fetch, every 5 minutes)
+  - `PRAGMA incremental_vacuum` when cleanup removes 100+ rows
+  - Worker isolation via `ISOLATION_FORKS` env variable — exclude specific workers from queue processing
+  - Custom database path via `queue_db_path` parameter
+  - Requires optional `sqlite3` gem (`~> 2.0`) — not included by default, must be added to Gemfile explicitly
+- New Runner parameters: `queue_notifier:` and `queue_db_path:`
+
+### Improvements
+- Unified `monotonic_now` usage across `run_job` and `run_queue_job` (was using direct `Process.clock_gettime` call in `run_job`)
+- `Queue::Notifier#drain` — moved `rescue` inside the loop to avoid stack unwinding on each drain cycle
+
+## 0.3.0
+
+### Features
+- Added optional metrics collection system using shared memory
+- New `Metrics` class with worker-specific performance tracking
+- Public API: `runner.metrics.enabled?`, `runner.metrics.values`, `Metrics.read_all()`
+- Tracks total runs, successes, failures, timeouts, skips, active jobs, and execution times
+- Requires optional `async-utilization` gem dependency
+- Metrics stored in `/tmp/async-background.shm` with lock-free updates per worker
+
+## 0.2.6
+
+### Improvements
+- Micro-optimization in `wait_with_shutdown` method: use passed `task` parameter instead of `Async::Task.current` for better consistency and slight performance improvement
+
+## 0.2.5
+
+### Features
+- Added graceful shutdown via signal handlers for SIGINT and SIGTERM
+- Enhanced process lifecycle management with proper signal handling using `Signal.trap` and IO.pipe for async communication
+- Improved robustness for production deployments and container orchestration
+- Updated dependencies to work with latest Async 2.x API (removed deprecated `:parent` parameter usage)
+
+## 0.2.4
+
+### Improvements
+- Removed hardcoded version warning from main module (was checking against fixed list: 0.1.0, 0.2.2, 0.2.3). Use semantic versioning with pre-release suffixes for unstable versions (e.g., 0.3.0.alpha1) instead
+- Removed hardcoded stable versions list from gemspec description — metadata should describe functionality, not versioning
+- Changed `while true` to idiomatic `loop do` in run method
+- Added `Gemfile.lock` to .gitignore (gems should not commit lockfile)
+- Updated README: clarified that job class must respond to `.perform_now` class method (removed confusing mention of instance `#perform`)
+
+## 0.2.2
+
+### Bug Fixes
+- **CRITICAL**: Removed logger parameter from Runner initialize (was unused). Fixed initialization to use Console.logger directly which now properly initializes in forked processes with correct context
+
+## 0.2.1
+
+### Bug Fixes
+- **CRITICAL**: Added missing `require 'console'` in main module. Logger was nil because Console gem was not imported, causing `undefined method 'info' for nil` errors on worker initialization
+
+## 0.2.0
+
+### Bug Fixes
+- **CRITICAL**: Removed hidden ActiveSupport dependency. Replaced `safe_constantize` with `Object.const_get` + `NameError` handling
+- **CRITICAL**: Fixed validator mismatch: now validates `.perform_now` (class method) instead of `.perform` (instance method)
+- **CRITICAL**: Fixed race condition where entry could disappear from heap during execution. `reschedule` and `heap.push` now always execute after job processing
+- Added full exception backtrace to error logs for production debugging
+- Improved YAML security by removing `Symbol` from `permitted_classes`
+- Removed Mutex from graceful shutdown (anti-pattern in Async). Boolean assignment is atomic in MRI
+
+### Features
+- Added optional `logger` parameter to Runner constructor for custom loggers (Rails.logger, etc.)
+- Added `stop()` method for graceful shutdown
+- Added `running?()` method to check scheduler status
+
+### Breaking Changes
+- Job class validation now checks for `.perform_now` class method (was checking for `.perform` instance method)
+
+## 0.1.0
+
+- Initial release
+- Single event loop with min-heap timer (O(log N) scheduling)
+- Skip overlapping execution
+- Startup jitter to prevent thundering herd
+- Monotonic clock for interval jobs, wall clock for cron jobs
+- Deterministic worker sharding via Zlib.crc32
+- Semaphore-based concurrency control
+- Per-job timeout protection
+- Structured logging via Console

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haydarov Roman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,193 @@
+# Async::Background
+
+A lightweight, production-grade cron/interval scheduler for Ruby's [Async](https://github.com/socketry/async) ecosystem. Designed for [Falcon](https://github.com/socketry/falcon) but works with any Async-based application.
+
+## What It Does
+
+- **Cron & interval scheduling** — single event loop + min-heap, scales to hundreds of jobs
+- **Dynamic job queue** — enqueue jobs at runtime via SQLite, pick up by background workers
+- **Delayed jobs** — schedule jobs for future execution with `perform_in` / `perform_at` (Sidekiq-like API)
+- **Multi-process safe** — deterministic worker sharding via `Zlib.crc32`, no duplicate execution
+- **Skip overlapping** — if a job is still running when its next tick arrives, the tick is skipped
+- **Timeout protection** — per-job configurable timeout via `Async::Task#with_timeout`
+- **Startup jitter** — random delay to prevent thundering herd after restart
+- **Optional metrics** — shared memory performance tracking with `async-utilization`
+
+## Requirements
+
+- **Ruby >= 3.3** — Fiber Scheduler production-ready ([why?](#why-ruby-33))
+- **Async ~> 2.0** — Fiber Scheduler-based concurrency
+- **Fugit ~> 1.0** — cron expression parsing
+
+## Installation
+
+```ruby
+# Gemfile
+gem "async-background"
+
+# Optional
+gem "sqlite3", "~> 2.0"           # for dynamic job queue
+gem "async-utilization", "~> 0.3"  # for metrics
+```
+
+## ➡️ [Get Started](docs/GET_STARTED.md)
+
+Step-by-step setup guide: schedule config, Falcon integration, Docker, dynamic queue, delayed jobs.
+
+---
+
+## Quick Example: Job Module
+
+Include `Async::Background::Job` for a Sidekiq-like interface:
+
+```ruby
+class SendEmailJob
+  include Async::Background::Job
+
+  def perform(user_id, template)
+    user = User.find(user_id)
+    Mailer.send(user, template)
+  end
+end
+
+# Immediate execution in the queue
+SendEmailJob.perform_async(user_id, "welcome")
+
+# Execute after 5 minutes
+SendEmailJob.perform_in(300, user_id, "reminder")
+
+# Execute at a specific time
+SendEmailJob.perform_at(Time.new(2026, 4, 1, 9, 0, 0), user_id, "scheduled")
+```
+
+Or use the lower-level API directly:
+
+```ruby
+Async::Background::Queue.enqueue(SendEmailJob, user_id, "welcome")
+Async::Background::Queue.enqueue_in(300, SendEmailJob, user_id, "reminder")
+Async::Background::Queue.enqueue_at(Time.new(2026, 4, 1, 9, 0, 0), SendEmailJob, user_id, "scheduled")
+```
+
+---
+
+## ⚠️ Important Notes
+
+### Docker: SQLite requires a named volume
+
+The SQLite database **must not** live on Docker's `overlay2` filesystem. The `overlay2` driver breaks coherence between `write()` and `mmap()`, which corrupts SQLite WAL under concurrent access.
+
+```yaml
+# docker-compose.yml
+volumes:
+  - queue-data:/app/tmp/queue   # ← named volume, NOT overlay2
+
+volumes:
+  queue-data:
+```
+
+Without this, you will get database crashes in multi-process mode. See [Get Started → Step 3](docs/GET_STARTED.md#step-3-docker) for details.
+
+### Fork safety
+
+SQLite connections **must not** cross `fork()` boundaries. Always open connections **after** fork (inside `container.run` block), never before. The gem handles this internally via lazy `ensure_connection`, but if you create a `Queue::Store` manually for schema setup, close it before fork:
+
+```ruby
+store = Async::Background::Queue::Store.new(path: db_path)
+store.ensure_database!
+store.close  # ← before fork
+```
+
+### Clock handling
+
+The `Clock` module provides shared time helpers used across the codebase:
+
+- **`monotonic_now`** (`CLOCK_MONOTONIC`) — for in-process intervals and durations, immune to NTP drift / wall-clock jumps
+- **`realtime_now`** (`CLOCK_REALTIME`) — for persisted timestamps (SQLite `run_at`, `created_at`, `locked_at`)
+
+Interval jobs use monotonic clock. Cron jobs use `Time.now` because "every day at 3am" must respect real time. These are different clocks by design.
+
+---
+
+## Architecture
+
+```
+schedule.yml
+     │
+     ▼
+ build_heap          ← parse config, validate, assign workers
+     │
+     ▼
+ MinHeap<Entry>      ← O(log N) push/pop, sorted by next_run_at
+     │
+     ▼
+ 1 scheduler loop    ← single Async task, sleeps until next entry
+     │
+     ▼
+ Semaphore           ← limits concurrent job execution
+     │
+     ▼
+ run_job             ← timeout, logging, error handling
+```
+
+### Queue Architecture
+
+```
+Producer (web/console)          Consumer (background worker)
+     │                                │
+     ▼                                ▼
+ Queue::Client                   Queue::Store.fetch
+     │                           (WHERE run_at <= now)
+     ├─ push(class, args, run_at)     │
+     ├─ push_in(delay, class, args)   ▼
+     └─ push_at(time, class, args)  run_queue_job
+     │                                │
+     ▼                                ▼
+ Queue::Store ──── SQLite ──── Queue::Notifier
+ (INSERT job)    (jobs table)    (IO.pipe wakeup)
+```
+
+## Schedule Config
+
+| Key | Required | Description |
+|---|---|---|
+| `class` | yes | Must include `Async::Background::Job` |
+| `every` | one of | Interval in seconds between runs |
+| `cron` | one of | Cron expression (parsed by Fugit) |
+| `timeout` | no | Max execution time in seconds (default: 30) |
+| `worker` | no | Pin to specific worker index. If omitted — `crc32(name) % total_workers` |
+
+## SQLite Pragmas
+
+| Pragma | Value | Why |
+|---|---|---|
+| `journal_mode` | WAL | Concurrent reads during writes |
+| `synchronous` | NORMAL | Safe with WAL, lower fsync overhead |
+| `mmap_size` | 256 MB | Fast reads ([requires proper filesystem](#docker-sqlite-requires-a-named-volume)) |
+| `cache_size` | 16000 pages | ~64 MB page cache |
+| `busy_timeout` | 5000 ms | Wait instead of failing on lock contention |
+
+## Metrics
+
+When `async-utilization` gem is available, metrics are collected in shared memory (`/tmp/async-background.shm`) with lock-free updates per worker.
+
+```ruby
+runner.metrics.values
+# => { total_runs: 142, total_successes: 140, total_failures: 2,
+#      total_timeouts: 0, total_skips: 5, active_jobs: 1,
+#      last_run_at: 1774445243, last_duration_ms: 1250 }
+
+# Read all workers at once (no server needed)
+Async::Background::Metrics.read_all(total_workers: 2)
+```
+
+Without the gem — metrics are silently disabled, zero overhead.
+
+## Why Ruby 3.3?
+
+- Ruby 3.0 introduced Fiber Scheduler but had critical bugs
+- Ruby 3.2 is the first production-ready release (per Samuel Williams)
+- `io-event >= 1.14` (pulled by latest `async`) requires Ruby `>= 3.3`
+
+## License
+
+MIT

data/async-background.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'lib/async/background/version'
+
+Gem::Specification.new do |spec|
+  spec.name    = 'async-background'
+  spec.version = Async::Background::VERSION
+  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.homepage = 'https://github.com/roman-haidarov/async-background'
+  spec.license  = 'MIT'
+
+  spec.metadata = {
+    'source_code_uri' => 'https://github.com/roman-haidarov/async-background',
+    'changelog_uri'   => 'https://github.com/roman-haidarov/async-background/blob/main/CHANGELOG.md',
+    'bug_tracker_uri' => 'https://github.com/roman-haidarov/async-background/issues'
+  }
+
+  spec.files         = Dir.glob('lib/**/*', base: __dir__) +
+                       %w[README.md CHANGELOG.md LICENSE async-background.gemspec]
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 3.3'
+
+  spec.add_dependency 'async',   '~> 2.0'
+  spec.add_dependency 'console', '~> 1.0'
+  spec.add_dependency 'fugit',   '~> 1.0'
+
+  # Optional: add to your own Gemfile if you need these features
+  #   gem 'sqlite3',          '~> 2.0'  # dynamic job queue
+  #   gem 'async-utilization', '~> 0.3' # shared-memory worker metrics
+
+  spec.add_development_dependency 'rake',  '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+end

data/lib/async/background/clock.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Async
+  module Background
+    # Shared clock helpers used across Runner, Queue::Store, and Queue::Client.
+    #
+    # monotonic_now — CLOCK_MONOTONIC, for in-process intervals and durations
+    #                 (immune to NTP drift / wall-clock jumps)
+    #
+    # realtime_now  — CLOCK_REALTIME, for persisted timestamps (SQLite run_at,
+    #                 created_at, locked_at) and human-readable metrics
+    #
+    module Clock
+      private
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def realtime_now
+        Process.clock_gettime(Process::CLOCK_REALTIME)
+      end
+    end
+  end
+end

data/lib/async/background/entry.rb

@@ -3,8 +3,6 @@
 module Async
   module Background
     class Entry
-      MIN_SLEEP_TIME = 0.1
-
       attr_reader :name, :job_class, :interval, :cron, :timeout
       attr_accessor :next_run_at, :running
 
@@ -25,7 +23,7 @@ module Async
         else
           now_wall = Time.now
           wait = cron.next_time(now_wall).to_f - now_wall.to_f
-          @next_run_at = monotonic_now + [wait, MIN_SLEEP_TIME].max
+          @next_run_at = monotonic_now + [wait, Async::Background::MIN_SLEEP_TIME].max
         end
       end
     end

data/lib/async/background/job.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Async
+  module Background
+    module Job
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def perform_now(*args)
+          new.perform(*args)
+        end
+
+        def perform_async(*args)
+          Async::Background::Queue.enqueue(self, *args)
+        end
+
+        def perform_in(delay, *args)
+          Async::Background::Queue.enqueue_in(delay, self, *args)
+        end
+
+        def perform_at(time, *args)
+          Async::Background::Queue.enqueue_at(time, self, *args)
+        end
+      end
+
+      def perform(*args)
+        raise NotImplementedError, "#{self.class} must implement #perform"
+      end
+    end
+  end
+end

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

@@ -1,38 +1,64 @@
 # frozen_string_literal: true
 
+require_relative '../clock'
+
 module Async
   module Background
     module Queue
-      # Usage:
-      #   Async::Background::Queue.enqueue(SendEmailJob, user_id, "welcome")
-      #
       class Client
+        include Clock
+
         def initialize(store:, notifier: nil)
           @store    = store
           @notifier = notifier
         end
 
-        def push(class_name, args = [])
-          id = @store.enqueue(class_name, args)
+        def push(class_name, args = [], run_at = nil)
+          id = @store.enqueue(class_name, args, run_at)
           @notifier&.notify
           id
         end
+
+        def push_in(delay, class_name, args = [])
+          run_at = realtime_now + delay.to_f
+          push(class_name, args, run_at)
+        end
+
+        def push_at(time, class_name, args = [])
+          run_at = time.respond_to?(:to_f) ? time.to_f : time
+          push(class_name, args, run_at)
+        end
       end
 
       class << self
         attr_accessor :default_client
 
         def enqueue(job_class, *args)
+          ensure_configured!
+          default_client.push(resolve_class_name(job_class), args)
+        end
+
+        def enqueue_in(delay, job_class, *args)
+          ensure_configured!
+          default_client.push_in(delay, resolve_class_name(job_class), args)
+        end
+
+        def enqueue_at(time, job_class, *args)
+          ensure_configured!
+          default_client.push_at(time, resolve_class_name(job_class), args)
+        end
+
+        private
+
+        def ensure_configured!
           raise "Async::Background::Queue not configured" unless default_client
+        end
 
-          if job_class.is_a?(String)
-            class_name = job_class
-          else
-            raise ArgumentError, "#{job_class} must implement .perform_now" unless job_class.respond_to?(:perform_now)
-            class_name = job_class.name
-          end
+        def resolve_class_name(job_class)
+          return job_class if job_class.is_a?(String)
+          return job_class.name if job_class.respond_to?(:perform_now)
 
-          default_client.push(class_name, args)
+          raise ArgumentError, "#{job_class} must include Async::Background::Job"
         end
       end
     end

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

@@ -4,6 +4,20 @@ module Async
   module Background
     module Queue
       class Notifier
+        #  Error groups
+        WRITE_DROPPED = [
+          IO::WaitWritable,  # buffer full — consumer is behind, skip
+          Errno::EAGAIN,     # same as above on some platforms
+          IOError,           # our own writer end has been closed
+          Errno::EPIPE       # the reader end is gone (consumer crashed) — skip
+        ].freeze
+
+        READ_EXHAUSTED = [
+          IO::WaitReadable,  # nothing left in the buffer — normal exit
+          EOFError,          # writer end closed — no more data ever
+          IOError            # our own reader end has been closed
+        ].freeze
+
         attr_reader :reader, :writer
 
         def initialize
@@ -14,10 +28,10 @@ module Async
 
         def notify
           @writer.write_nonblock("\x01")
-        rescue IO::WaitWritable, Errno::EAGAIN
-          # pipe buffer full — consumer is already behind, skip
-        rescue IOError
-          # pipe closed
+        rescue *WRITE_DROPPED
+          # All write failures are non-fatal: the job is already in the
+          # store, and missing one wake-up only delays pickup by at most
+          # one poll interval.
         end
 
         def wait(timeout: nil)
@@ -51,7 +65,7 @@ module Async
         def drain
           loop do
             @reader.read_nonblock(256)
-          rescue IO::WaitReadable, EOFError
+          rescue *READ_EXHAUSTED
             break
           end
           nil

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require 'json'
+require_relative '../clock'
 
 module Async
   module Background
     module Queue
       class Store
+        include Clock
+
         SCHEMA = <<~SQL
           PRAGMA auto_vacuum = INCREMENTAL;
           CREATE TABLE IF NOT EXISTS jobs (
@@ -14,10 +17,11 @@ module Async
             args       TEXT    NOT NULL DEFAULT '[]',
             status     TEXT    NOT NULL DEFAULT 'pending',
             created_at REAL    NOT NULL,
+            run_at     REAL    NOT NULL,
             locked_by  INTEGER,
             locked_at  REAL
           );
-          CREATE INDEX IF NOT EXISTS idx_jobs_status_id ON jobs(status, id);
+          CREATE INDEX IF NOT EXISTS idx_jobs_status_run_at_id ON jobs(status, run_at, id);
         SQL
 
         MMAP_SIZE = 268_435_456
@@ -49,6 +53,7 @@ module Async
         def ensure_database!
           require_sqlite3
           db = SQLite3::Database.new(@path)
+          db.execute('PRAGMA busy_timeout = 5000')
           db.execute_batch(PRAGMAS.call(@mmap ? MMAP_SIZE : 0))
           db.execute_batch(SCHEMA)
           db.execute("PRAGMA wal_checkpoint(TRUNCATE)")
@@ -56,16 +61,20 @@ module Async
           @schema_checked = true
         end
 
-        def enqueue(class_name, args = [])
+        def enqueue(class_name, args = [], run_at = nil)
           ensure_connection
-          @enqueue_stmt.execute(class_name, JSON.generate(args), realtime_now)
+          run_at ||= realtime_now
+          @enqueue_stmt.execute(class_name, JSON.generate(args), realtime_now, run_at)
           @db.last_insert_row_id
         end
 
         def fetch(worker_id)
           ensure_connection
+          now = realtime_now
           @db.execute("BEGIN IMMEDIATE")
-          row = @fetch_stmt.execute(worker_id, realtime_now).first
+          results = @fetch_stmt.execute(worker_id, now, now)
+          row = results.first
+          @fetch_stmt.reset!
           @db.execute("COMMIT")
           return unless row
 
@@ -75,7 +84,6 @@ module Async
           @db.execute("ROLLBACK") rescue nil
           raise
         end
-
         def complete(job_id)
           ensure_connection
           @complete_stmt.execute(job_id)
@@ -121,6 +129,7 @@ module Async
           require_sqlite3
           finalize_statements
           @db = SQLite3::Database.new(@path)
+          @db.execute('PRAGMA busy_timeout = 5000')
           @db.execute_batch(PRAGMAS.call(@mmap ? MMAP_SIZE : 0))
 
           unless @schema_checked
@@ -134,7 +143,7 @@ module Async
 
         def prepare_statements
           @enqueue_stmt = @db.prepare(
-            "INSERT INTO jobs (class_name, args, created_at) VALUES (?, ?, ?)"
+            "INSERT INTO jobs (class_name, args, created_at, run_at) VALUES (?, ?, ?, ?)"
           )
 
           @fetch_stmt = @db.prepare(<<~SQL)
@@ -142,8 +151,8 @@ module Async
             SET    status = 'running', locked_by = ?, locked_at = ?
             WHERE  id = (
               SELECT id FROM jobs
-              WHERE  status = 'pending'
-              ORDER BY id
+              WHERE  status = 'pending' AND run_at <= ?
+              ORDER BY run_at, id
               LIMIT 1
             )
             RETURNING id, class_name, args
@@ -180,13 +189,6 @@ module Async
           end
         end
 
-        def realtime_now
-          Process.clock_gettime(Process::CLOCK_REALTIME)
-        end
-
-        def monotonic_now
-          Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        end
       end
     end
   end

data/lib/async/background/runner.rb

@@ -7,12 +7,14 @@ module Async
   module Background
     class ConfigError < StandardError; end
 
-    DEFAULT_TIMEOUT = 30
-    MIN_SLEEP_TIME  = 0.1
-    MAX_JITTER      = 5
+    DEFAULT_TIMEOUT     = 30
+    MIN_SLEEP_TIME      = 0.1
+    MAX_JITTER          = 5
     QUEUE_POLL_INTERVAL = 5
 
     class Runner
+      include Clock
+
       attr_reader :logger, :semaphore, :heap, :worker_index, :total_workers, :shutdown, :metrics, :queue_store
 
       def initialize(
@@ -53,7 +55,7 @@ module Async
         @running = false
         logger.info { "Async::Background: stopping gracefully" }
         shutdown.signal
-        @queue_notifier&.notify  # unblock queue listener from @reader.wait_readable
+        @queue_notifier&.notify
       end
 
       def running?
@@ -96,13 +98,13 @@ module Async
               job = @queue_store.fetch(worker_index)
               break unless job
 
-              semaphore.async { run_queue_job(task, job) }
+              semaphore.async { |job_task| run_queue_job(job_task, job) }
             end
           end
         end
       end
 
-      def run_queue_job(task, job)
+      def run_queue_job(job_task, job)
         class_name = job[:class_name]
         args       = job[:args]
         klass      = resolve_job_class(class_name)
@@ -110,7 +112,7 @@ module Async
         metrics.job_started(nil)
         t = monotonic_now
 
-        task.with_timeout(DEFAULT_TIMEOUT) { klass.perform_now(*args) }
+        job_task.with_timeout(DEFAULT_TIMEOUT) { klass.perform_now(*args) }
 
         duration = monotonic_now - t
         metrics.job_finished(nil, duration)
@@ -140,7 +142,7 @@ module Async
           mod.const_get(name, false)
         end
 
-        raise ConfigError, "#{class_name} must implement .perform_now" unless klass.respond_to?(:perform_now)
+        raise ConfigError, "#{class_name} must include Async::Background::Job" unless klass.respond_to?(:perform_now)
 
         klass
       end
@@ -164,8 +166,8 @@ module Async
               metrics.job_skipped(entry)
             else
               entry.running = true
-              semaphore.async do
-                run_job(task, entry)
+              semaphore.async do |job_task|
+                run_job(job_task, entry)
               ensure
                 entry.running = false
               end
@@ -252,7 +254,7 @@ module Async
           raise ConfigError, "[#{name}] unknown class: #{class_name}"
         end
 
-        raise ConfigError, "[#{name}] #{class_name} must implement .perform_now" unless job_class.respond_to?(:perform_now)
+        raise ConfigError, "[#{name}] #{class_name} must include Async::Background::Job" unless job_class.respond_to?(:perform_now)
 
         interval = config['every']&.then { |v|
           int = v.to_i
@@ -274,14 +276,10 @@ module Async
         }
       end
 
-      def monotonic_now
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
-
-      def run_job(task, entry)
+      def run_job(job_task, entry)
         metrics.job_started(entry)
         t = monotonic_now
-        task.with_timeout(entry.timeout) { entry.job_class.perform_now }
+        job_task.with_timeout(entry.timeout) { entry.job_class.perform_now }
 
         duration = monotonic_now - t
         metrics.job_finished(entry, duration)

data/lib/async/background/version.rb

@@ -2,6 +2,6 @@
 
 module Async
   module Background
-    VERSION = '0.4.5'
+    VERSION = '0.5.1'
   end
 end

data/lib/async/background.rb

@@ -7,7 +7,11 @@ require 'fugit'
 require 'tmpdir'
 
 require_relative 'background/version'
+require_relative 'background/clock'
 require_relative 'background/min_heap'
 require_relative 'background/entry'
 require_relative 'background/metrics'
 require_relative 'background/runner'
+require_relative 'background/queue/store'
+require_relative 'background/queue/client'
+require_relative 'background/job'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async-background
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.5.1
 platform: ruby
 authors:
 - Roman Hajdarov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-29 00:00:00.000000000 Z
+date: 2026-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -90,8 +90,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- async-background.gemspec
 - lib/async/background.rb
+- lib/async/background/clock.rb
 - lib/async/background/entry.rb
+- lib/async/background/job.rb
 - lib/async/background/metrics.rb
 - lib/async/background/min_heap.rb
 - lib/async/background/queue/client.rb