async-background 0.4.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db310afc2038735e979a5041ff92998de5ff27655457569e588ab952c8e2cde0
-  data.tar.gz: b079e4f9769ffb917afa2b6f7eac860e92a7dd93f6b5b73a5b32b76fbbb9e683
+  metadata.gz: 5959a648b21b8312d1b2d8d566ade149e736b6386eff0cf1fb9acd09801ba748
+  data.tar.gz: 839fd36e05ee3ef845ba1f2afaef50a5c996edf9812240a61198cb2f203d0e9a
 SHA512:
-  metadata.gz: 99e68ef3c3ee9899f8072d2eb7cc2e6a0da4745b637bc849835927a5390cabcdd81f3beb30cc3587618da230000d9f6b193101bed31f7a910ef62855e79cd24e
-  data.tar.gz: a8d683c78a0720c04e9c2b9b70a3f5f90c9caf34b495867e8c78ef14bc1270b3001ca8a04ca01dbd70e784d9a4f1b62d7a459845f7436997fccbbf88cb75ce15
+  metadata.gz: 408c3267a1acd854448a4dec42d0a3ab30a3ed8e40d40e5c841aca6c29cd2dc3378683ef7c5b305fa419b4fefea80292968efa67e1ff6eb8a4de5d7a5c403e00
+  data.tar.gz: 7d7af316122b5208e7adaaf681be8075821936fda225e78def6f8a9b76cf5350e50cd0bf6015888e585c149101c741de2d5f52ba82ffa4aa35734a3d86183511

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,8 @@ module Async
   module Background
     module Queue
       class Notifier
+        IO_ERRORS = [IO::WaitReadable, EOFError, IOError].freeze
+
         attr_reader :reader, :writer
 
         def initialize
@@ -51,7 +53,7 @@ module Async
         def drain
           loop do
             @reader.read_nonblock(256)
-          rescue IO::WaitReadable, EOFError
+          rescue *IO_ERRORS
             break
           end
           nil

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

@@ -1,41 +1,50 @@
 # 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 (
             id         INTEGER PRIMARY KEY,
             class_name TEXT    NOT NULL,
             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 ON jobs(status);
+          CREATE INDEX IF NOT EXISTS idx_jobs_status_run_at_id ON jobs(status, run_at, id);
         SQL
 
-        PRAGMAS = <<~SQL
-          PRAGMA journal_mode       = WAL;
-          PRAGMA synchronous        = NORMAL;
-          PRAGMA mmap_size          = 0;
-          PRAGMA cache_size         = -16000;
-          PRAGMA temp_store         = MEMORY;
-          PRAGMA busy_timeout       = 5000;
-          PRAGMA journal_size_limit = 67108864;
-        SQL
+        MMAP_SIZE = 268_435_456
+        PRAGMAS = ->(mmap_size) {
+          <<~SQL
+            PRAGMA journal_mode       = WAL;
+            PRAGMA synchronous        = NORMAL;
+            PRAGMA mmap_size          = #{mmap_size};
+            PRAGMA cache_size         = -16000;
+            PRAGMA temp_store         = MEMORY;
+            PRAGMA busy_timeout       = 5000;
+            PRAGMA journal_size_limit = 67108864;
+          SQL
+        }.freeze
 
         CLEANUP_INTERVAL = 300
         CLEANUP_AGE      = 3600
 
         attr_reader :path
 
-        def initialize(path: self.class.default_path)
+        def initialize(path: self.class.default_path, mmap: true)
           @path = path
+          @mmap = mmap
           @db   = nil
           @schema_checked = false
           @last_cleanup_at = nil
@@ -44,28 +53,36 @@ module Async
         def ensure_database!
           require_sqlite3
           db = SQLite3::Database.new(@path)
-          db.execute_batch(PRAGMAS)
+          db.execute_batch(PRAGMAS.call(@mmap ? MMAP_SIZE : 0))
           db.execute_batch(SCHEMA)
           db.execute("PRAGMA wal_checkpoint(TRUNCATE)")
           db.close
           @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
-          row = @fetch_stmt.execute(worker_id, realtime_now).first
+          now = realtime_now
+          @db.execute("BEGIN IMMEDIATE")
+          results = @fetch_stmt.execute(worker_id, now, now)
+          row = results.first
+          @fetch_stmt.reset!
+          @db.execute("COMMIT")
           return unless row
 
           maybe_cleanup
           { id: row[0], class_name: row[1], args: JSON.parse(row[2]) }
+        rescue
+          @db.execute("ROLLBACK") rescue nil
+          raise
         end
-
         def complete(job_id)
           ensure_connection
           @complete_stmt.execute(job_id)
@@ -86,7 +103,7 @@ module Async
           return unless @db && !@db.closed?
 
           finalize_statements
-          @db.execute("PRAGMA optimize")
+          @db.execute("PRAGMA optimize") rescue nil
           @db.close
           @db = nil
         end
@@ -111,7 +128,7 @@ module Async
           require_sqlite3
           finalize_statements
           @db = SQLite3::Database.new(@path)
-          @db.execute_batch(PRAGMAS)
+          @db.execute_batch(PRAGMAS.call(@mmap ? MMAP_SIZE : 0))
 
           unless @schema_checked
             @db.execute_batch(SCHEMA)
@@ -124,7 +141,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)
@@ -132,8 +149,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
@@ -151,10 +168,10 @@ module Async
         end
 
         def finalize_statements
-          %i[@enqueue_stmt @fetch_stmt @complete_stmt @fail_stmt @requeue_stmt @cleanup_stmt].each do |name|
-            stmt = instance_variable_get(name)
+          %i[enqueue_stmt fetch_stmt complete_stmt fail_stmt requeue_stmt cleanup_stmt].each do |name|
+            stmt = instance_variable_get(:"@#{name}")
             stmt&.close rescue nil
-            instance_variable_set(name, nil)
+            instance_variable_set(:"@#{name}", nil)
           end
         end
 
@@ -170,13 +187,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,17 +7,19 @@ 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
-      attr_reader :logger, :semaphore, :heap, :worker_index, :total_workers, :shutdown, :metrics
+      include Clock
+
+      attr_reader :logger, :semaphore, :heap, :worker_index, :total_workers, :shutdown, :metrics, :queue_store
 
       def initialize(
         config_path:, job_count: 2, worker_index:, total_workers:,
-        queue_notifier: nil, queue_db_path: nil
+        queue_notifier: nil, queue_db_path: nil, queue_mmap: true
       )
         @logger        = Console.logger
         @worker_index  = worker_index
@@ -31,7 +33,7 @@ module Async
         @semaphore = ::Async::Semaphore.new(job_count)
         @heap      = build_heap(config_path)
 
-        setup_queue(queue_notifier, queue_db_path)
+        setup_queue(queue_notifier, queue_db_path, queue_mmap)
       end
 
       def run
@@ -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?
@@ -62,7 +64,7 @@ module Async
 
       private
 
-      def setup_queue(queue_notifier, queue_db_path)
+      def setup_queue(queue_notifier, queue_db_path, queue_mmap)
         @listen_queue = false
         return unless queue_notifier
 
@@ -76,7 +78,10 @@ module Async
 
         @listen_queue   = true
         @queue_notifier = queue_notifier
-        @queue_store    = Queue::Store.new(path: queue_db_path || Queue::Store.default_path)
+        @queue_store    = Queue::Store.new(
+          path: queue_db_path || Queue::Store.default_path,
+          mmap: queue_mmap
+        )
 
         recovered = @queue_store.recover(worker_index)
         logger.info { "Async::Background queue: recovered #{recovered} stale jobs" } if recovered > 0
@@ -93,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)
@@ -107,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)
@@ -137,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
@@ -161,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
@@ -249,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
@@ -271,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.4'
+    VERSION = '0.5.0'
   end
 end

data/lib/async/background.rb

@@ -7,7 +7,10 @@ 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/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.4
+  version: 0.5.0
 platform: ruby
 authors:
 - Roman Hajdarov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-28 00:00:00.000000000 Z
+date: 2026-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -91,7 +91,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - 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