async-background 0.4.5 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9a1ac97495dc7d6a39adf802a847b62e3601df0fe0ef4aa70dbcc248a2f77b8
-  data.tar.gz: 74bab717411caf3e8a7b469666e9df5f8f59d540ebd98446c5e44e167cacd3c9
+  metadata.gz: 5959a648b21b8312d1b2d8d566ade149e736b6386eff0cf1fb9acd09801ba748
+  data.tar.gz: 839fd36e05ee3ef845ba1f2afaef50a5c996edf9812240a61198cb2f203d0e9a
 SHA512:
-  metadata.gz: fe41a129f66a72c51016397b866ee9ff31b973d5e92ee6af1f61c05ce87f8f85f9824a68499caefcf950cdb33186c74749817e0ae8b89a483ede580d412e13fc
-  data.tar.gz: 92208ce41c49095cdf652b798ed892e4db5ae12c504cfe94c45bf124054256a94906fba14f68365f938a6d7289c76ca79d7ae7f6fac53bb76d8097d463db684f
+  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,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
@@ -56,16 +60,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 +83,6 @@ module Async
           @db.execute("ROLLBACK") rescue nil
           raise
         end
-
         def complete(job_id)
           ensure_connection
           @complete_stmt.execute(job_id)
@@ -134,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)
@@ -142,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
@@ -180,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,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.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.5
+  version: 0.5.0
 platform: ruby
 authors:
 - Roman Hajdarov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-29 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