async-background 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 81377ce73dc827a65ac5710dcc5343a2c2d97d80800489f50c8c334a71cc5f76
+  data.tar.gz: 34f372d35ec9b98b88c3009268c2b4427e8d4211c6534d2f0ec9099be922ac5c
+SHA512:
+  metadata.gz: cdda5f36c0dcbcabc97b3d580af897ea466c382358848faa436b04d0bfe61e18e16e1743246848f57546ba4908c3876f83f314983b97caf419381757cb1849c7
+  data.tar.gz: 227eb8648f9a611e866766246b63c288a1d15dc2e7447c8323f11c1d1c7bae5ceebab215ec7922901cb1bb66c4c701bf4d2fcf1dadfcd18b1def693559490d2c

data/lib/async/background/entry.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+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
+
+      def initialize(name:, job_class:, interval:, cron:, timeout:, next_run_at:)
+        @name        = name
+        @job_class   = job_class
+        @interval    = interval
+        @cron        = cron
+        @timeout     = timeout
+        @next_run_at = next_run_at
+        @running     = false
+      end
+
+      def reschedule(monotonic_now)
+        if interval
+          @next_run_at += interval
+          @next_run_at = monotonic_now + interval if @next_run_at <= monotonic_now
+        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
+        end
+      end
+    end
+  end
+end

data/lib/async/background/min_heap.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Async
+  module Background
+    class MinHeap
+      def initialize
+        @data = []
+      end
+
+      def push(entry)
+        @data << entry
+        sift_up(@data.size - 1)
+      end
+
+      def pop
+        return if @data.empty?
+
+        swap(0, @data.size - 1)
+        entry = @data.pop
+        sift_down(0) unless @data.empty?
+        entry
+      end
+
+      def peek
+        @data.first
+      end
+
+      def empty?
+        @data.empty?
+      end
+
+      def size
+        @data.size
+      end
+
+      private
+
+      def sift_up(i)
+        while i > 0
+          parent = (i - 1) >> 1
+          break if @data[parent].next_run_at <= @data[i].next_run_at
+
+          swap(i, parent)
+          i = parent
+        end
+      end
+
+      def sift_down(i)
+        while true
+          smallest = i
+          left  = (i << 1) + 1
+          right = left + 1
+
+          smallest = left  if left < @data.size && @data[left].next_run_at < @data[smallest].next_run_at
+          smallest = right if right < @data.size && @data[right].next_run_at < @data[smallest].next_run_at
+
+          break if smallest == i
+
+          swap(i, smallest)
+          i = smallest
+        end
+      end
+
+      def swap(a, b)
+        @data[a], @data[b] = @data[b], @data[a]
+      end
+    end
+  end
+end

data/lib/async/background/runner.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'zlib'
+
+module Async
+  module Background
+    class ConfigError < StandardError; end
+
+    DEFAULT_TIMEOUT = 30
+    MIN_SLEEP_TIME  = 0.1
+    MAX_JITTER      = 5
+
+    class Runner
+      attr_reader :logger, :semaphore, :heap, :worker_index, :total_workers
+
+      def initialize(config_path:, job_count: 2, worker_index:, total_workers:)
+        @logger        = Console.logger
+        @worker_index  = worker_index
+        @total_workers = total_workers
+
+        logger.info { "Async::Background worker_index=#{worker_index}/#{total_workers}, job_count=#{job_count}" }
+
+        @semaphore = ::Async::Semaphore.new(job_count)
+        @heap      = build_heap(config_path)
+      end
+
+      def run
+        Async do |task|
+          while true
+            entry = heap.peek
+            break unless entry
+
+            now = monotonic_now
+            wait = [entry.next_run_at - now, MIN_SLEEP_TIME].max
+            task.sleep wait
+
+            now = monotonic_now
+            while (top = heap.peek) && top.next_run_at <= now
+              entry = heap.pop
+
+              if entry.running
+                logger.warn('Async::Background') { "#{entry.name}: skipped, previous run still active" }
+              else
+                entry.running = true
+                semaphore.async(parent: task) do
+                  run_job(task, entry)
+                ensure
+                  entry.running = false
+                end
+              end
+
+              entry.reschedule(monotonic_now)
+              heap.push(entry)
+            end
+          end
+        end
+      end
+
+      private
+
+      def build_heap(config_path)
+        raise ConfigError, "Schedule file not found: #{config_path}" unless File.exist?(config_path)
+
+        raw = YAML.safe_load_file(config_path, permitted_classes: [Symbol])
+        raise ConfigError, "Empty schedule: #{config_path}" unless raw&.any?
+
+        heap = MinHeap.new
+        now  = monotonic_now
+
+        raw.each do |name, config|
+          assigned = config['worker']&.to_i || ((Zlib.crc32(name) % total_workers) + 1)
+          next unless assigned == worker_index
+
+          task_config = build_task_config(name, config)
+          jitter = rand * [task_config[:interval] || MAX_JITTER, MAX_JITTER].min
+
+          next_run_at = if task_config[:interval]
+            now + jitter + task_config[:interval]
+          else
+            now_wall = Time.now
+            wall_wait = task_config[:cron].next_time(now_wall).to_f - now_wall.to_f
+            now + jitter + [wall_wait, MIN_SLEEP_TIME].max
+          end
+
+          heap.push(Entry.new(
+            name:        name,
+            job_class:   task_config[:job_class],
+            interval:    task_config[:interval],
+            cron:        task_config[:cron],
+            timeout:     task_config[:timeout],
+            next_run_at: next_run_at
+          ))
+        end
+
+        heap
+      end
+
+      def build_task_config(name, config)
+        class_name = config&.dig('class').to_s.strip
+        raise ConfigError, "[#{name}] missing class" if class_name.empty?
+
+        job_class = class_name.safe_constantize
+        raise ConfigError, "[#{name}] unknown class: #{class_name}" unless job_class
+        raise ConfigError, "[#{name}] #{class_name} must implement #perform" unless job_class.method_defined?(:perform)
+
+        interval = config['every']&.then { |v|
+          int = v.to_i
+          raise ConfigError, "[#{name}] 'every' must be > 0" unless int.positive?
+          int
+        }
+
+        cron = config['cron']&.then { |c|
+          Fugit::Cron.new(c) || raise(ConfigError, "[#{name}] invalid cron: #{c}")
+        }
+
+        raise ConfigError, "[#{name}] specify 'every' or 'cron'" unless interval || cron
+
+        {
+          job_class: job_class,
+          interval: interval,
+          cron: cron,
+          timeout: config.fetch('timeout', DEFAULT_TIMEOUT).to_i
+        }
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def run_job(task, entry)
+        t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        task.with_timeout(entry.timeout) { entry.job_class.perform_now }
+        logger.info('Async::Background') {
+          "#{entry.name}: completed in #{(Process.clock_gettime(Process::CLOCK_MONOTONIC) - t).round(2)}s"
+        }
+      rescue ::Async::TimeoutError
+        logger.error('Async::Background') { "#{entry.name}: timed out after #{entry.timeout}s" }
+      rescue => e
+        logger.error('Async::Background') { "#{entry.name}: #{e.class} #{e.message}" }
+      end
+    end
+  end
+end

data/lib/async/background/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Async
+  module Background
+    VERSION = '0.1.0'
+  end
+end

data/lib/async/background.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'async'
+require 'async/semaphore'
+require 'fugit'
+
+require_relative 'background/version'
+require_relative 'background/min_heap'
+require_relative 'background/entry'
+require_relative 'background/runner'

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: async-background
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Roman Hajdarov
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: console
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: fugit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+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.
+email:
+- romnhajdarov@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/async/background.rb
+- lib/async/background/entry.rb
+- lib/async/background/min_heap.rb
+- lib/async/background/runner.rb
+- lib/async/background/version.rb
+homepage: https://github.com/roman-haidarov/async-background
+licenses:
+- MIT
+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
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.22
+signing_key:
+specification_version: 4
+summary: Lightweight heap-based cron/interval scheduler for Async.
+test_files: []