async-background 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b412d31294adfc8d7a2586f31f42f47cd0a004e992016615dff81fc1828b7e90
-  data.tar.gz: 3d629e5272bd5f819e8fe2f3ed4507e73b720ce13c71c06433f1d7f3f9e9f563
+  metadata.gz: 00b7ba6035c743fb4c4568d2309da4bc7f454a3cbe5e17ac5d2251a417a4a31c
+  data.tar.gz: a3dff9b2b51f590a095120a18f1e3d5424b339ab5a6cff90b148f8e9316ee242
 SHA512:
-  metadata.gz: 9eab99f4c978281eea0689a96dfc45b356e82991fc177bf57ab919f688c397d6361f348fc0451c20b45207c124f15106e9b4bd6e637866103830fd64937266a0
-  data.tar.gz: 15b3e8677ec777ae4395d87fbfca81ce9b79fa67d3e2c1b425cbcdac17c12df5f382550a13593f1d71518e0f6ead48e31dd5e474c99634aedc7bea6fa4afe9ba
+  metadata.gz: b9c36893b1cb14ba251d9c5a1c614ac50b988ffcbd69c43a876c1e0a2995ee749592618c2e328d2e05573ccf46186616a59615d7c01a785b28fe5897a1e0650f
+  data.tar.gz: 3f47cf30226b45b6c543f48812e95778206e9cccc07445c5066e32cdf88a71f68bf88be9f0134750344cd7e0ed8df1a907107d0e5a3c910ce00a3a493ea700e7

data/lib/async/background/metrics.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Async
+  module Background
+    class Metrics
+      SCHEMA_FIELDS = {
+        total_runs:       :u64,
+        total_successes:  :u64,
+        total_failures:   :u64,
+        total_timeouts:   :u64,
+        total_skips:      :u64,
+        active_jobs:      :u32,
+        last_run_at:      :u64,
+        last_duration_ms: :u32
+      }.freeze
+
+      attr_reader :registry
+
+      def initialize(worker_index:, total_workers:, shm_path: self.class.default_shm_path)
+        require 'async/utilization'
+
+        @registry = nil
+        @enabled  = false
+        @registry = ::Async::Utilization::Registry.new
+        @enabled  = true
+
+        ensure_shm!(total_workers, shm_path)
+        attach_observer!(worker_index, total_workers, shm_path)
+      rescue LoadError
+      end
+
+      def enabled?
+        @enabled
+      end
+
+      def job_started(entry)
+        return unless @enabled
+
+        @registry.increment(:total_runs)
+        @registry.increment(:active_jobs)
+        @registry.set(:last_run_at, Process.clock_gettime(Process::CLOCK_REALTIME).to_i)
+      end
+
+      def job_finished(entry, duration)
+        return unless @enabled
+
+        @registry.decrement(:active_jobs)
+        @registry.increment(:total_successes)
+        @registry.set(:last_duration_ms, (duration * 1000).to_i)
+      end
+
+      def job_failed(entry, error)
+        return unless @enabled
+
+        @registry.decrement(:active_jobs)
+        @registry.increment(:total_failures)
+      end
+
+      def job_timed_out(entry)
+        return unless @enabled
+
+        @registry.decrement(:active_jobs)
+        @registry.increment(:total_timeouts)
+      end
+
+      def job_skipped(entry)
+        return unless @enabled
+
+        @registry.increment(:total_skips)
+      end
+
+      def values
+        return {} unless @enabled
+
+        @registry.values
+      end
+
+      def self.schema
+        require 'async/utilization'
+        ::Async::Utilization::Schema.build(SCHEMA_FIELDS)
+      end
+
+      # Read metrics for all workers from the shm file.
+      # No server needed — just reads the mmap'd file.
+      #
+      #   Async::Background::Metrics.read_all(total_workers: 2)
+      #   # => [
+      #   #   { worker: 1, total_runs: 142, active_jobs: 1, ... },
+      #   #   { worker: 2, total_runs: 98,  active_jobs: 0, ... }
+      #   # ]
+      #
+      def self.read_all(total_workers:, path: default_shm_path)
+        require 'async/utilization'
+
+        s = schema
+        segment = segment_size
+        file_size = segment * total_workers
+
+        buffer = File.open(path, "rb") do |f|
+          IO::Buffer.map(f, file_size, 0)
+        end
+
+        (1..total_workers).map do |i|
+          base = (i - 1) * segment
+          row = { worker: i }
+          s.fields.each do |field|
+            row[field.name] = buffer.get_value(field.type, base + field.offset)
+          end
+          row
+        end
+      end
+
+      def self.default_shm_path
+        File.join(Dir.tmpdir, "async-background.shm")
+      end
+
+      def self.segment_size
+        SCHEMA_FIELDS.sum { |_, type| IO::Buffer.size_of(type) }
+      end
+
+      private
+
+      def ensure_shm!(total_workers, path)
+        required = self.class.segment_size * total_workers
+
+        File.open(path, File::CREAT | File::RDWR, 0644) do |f|
+          f.flock(File::LOCK_EX)
+          f.truncate(required) if f.size < required
+          f.flock(File::LOCK_UN)
+        end
+      end
+
+      def attach_observer!(worker_index, total_workers, path)
+        segment = self.class.segment_size
+        offset  = (worker_index - 1) * segment
+        observer = ::Async::Utilization::Observer.open(
+          self.class.schema, path, segment, offset
+        )
+        @registry.observer = observer
+      end
+    end
+  end
+end

data/lib/async/background/min_heap.rb

@@ -21,6 +21,11 @@ module Async
         entry
       end
 
+      def replace_top(entry)
+        @data[0] = entry
+        sift_down(0)
+      end
+
       def peek
         @data.first
       end

data/lib/async/background/runner.rb

@@ -12,7 +12,7 @@ module Async
     MAX_JITTER      = 5
 
     class Runner
-      attr_reader :logger, :semaphore, :heap, :worker_index, :total_workers, :shutdown
+      attr_reader :logger, :semaphore, :heap, :worker_index, :total_workers, :shutdown, :metrics
 
       def initialize(config_path:, job_count: 2, worker_index:, total_workers:)
         @logger        = Console.logger
@@ -20,6 +20,7 @@ module Async
         @total_workers = total_workers
         @running       = true
         @shutdown      = ::Async::Condition.new
+        @metrics       = Metrics.new(worker_index: worker_index, total_workers: total_workers)
 
         logger.info { "Async::Background worker_index=#{worker_index}/#{total_workers}, job_count=#{job_count}" }
 
@@ -30,6 +31,7 @@ module Async
       def run
         Async do |task|
           setup_signal_handlers
+          start_signal_watcher(task)
 
           loop do
             entry = heap.peek
@@ -41,13 +43,12 @@ module Async
             break unless running?
 
             now = monotonic_now
-            while (top = heap.peek) && top.next_run_at <= now
+            while (entry = heap.peek) && entry.next_run_at <= now
               break unless running?
 
-              entry = heap.pop
-
               if entry.running
                 logger.warn('Async::Background') { "#{entry.name}: skipped, previous run still active" }
+                metrics.job_skipped(entry)
               else
                 entry.running = true
                 semaphore.async do
@@ -58,7 +59,7 @@ module Async
               end
 
               entry.reschedule(monotonic_now)
-              heap.push(entry)
+              heap.replace_top(entry)
             end
           end
 
@@ -91,21 +92,20 @@ module Async
         end
       end
 
-      def wait_with_shutdown(task, duration)
-        timer = task.async(transient: true) do
-          task.sleep duration
-          shutdown.signal
-        end
-
-        watcher = task.async(transient: true) do
-          @signal_r.wait_readable
-          @signal_r.read_nonblock(256) rescue nil
-          shutdown.signal
+      def start_signal_watcher(task)
+        task.async(transient: true) do
+          loop do
+            @signal_r.wait_readable
+            @signal_r.read_nonblock(256) rescue nil
+            shutdown.signal
+            break unless running?
+          end
         end
+      end
 
-        shutdown.wait
-        timer.stop
-        watcher.stop
+      def wait_with_shutdown(task, duration)
+        task.with_timeout(duration) { shutdown.wait }
+      rescue ::Async::TimeoutError
       end
 
       def build_heap(config_path)
@@ -182,14 +182,20 @@ module Async
       end
 
       def run_job(task, entry)
+        metrics.job_started(entry)
         t = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         task.with_timeout(entry.timeout) { entry.job_class.perform_now }
+
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t
+        metrics.job_finished(entry, duration)
         logger.info('Async::Background') {
-          "#{entry.name}: completed in #{(Process.clock_gettime(Process::CLOCK_MONOTONIC) - t).round(2)}s"
+          "#{entry.name}: completed in #{duration.round(2)}s"
         }
       rescue ::Async::TimeoutError
+        metrics.job_timed_out(entry)
         logger.error('Async::Background') { "#{entry.name}: timed out after #{entry.timeout}s" }
       rescue => e
+        metrics.job_failed(entry, e)
         logger.error('Async::Background') {
           "#{entry.name}: #{e.class} #{e.message}\n#{e.backtrace.join("\n")}"
         }

data/lib/async/background/version.rb

@@ -2,6 +2,6 @@
 
 module Async
   module Background
-    VERSION = '0.2.5'
+    VERSION = '0.3.0'
   end
 end

data/lib/async/background.rb

@@ -4,8 +4,10 @@ require 'async'
 require 'async/semaphore'
 require 'console'
 require 'fugit'
+require 'tmpdir'
 
 require_relative 'background/version'
 require_relative 'background/min_heap'
 require_relative 'background/entry'
+require_relative 'background/metrics'
 require_relative 'background/runner'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async-background
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Roman Hajdarov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-20 00:00:00.000000000 Z
+date: 2026-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -92,6 +92,7 @@ extra_rdoc_files: []
 files:
 - lib/async/background.rb
 - lib/async/background/entry.rb
+- lib/async/background/metrics.rb
 - lib/async/background/min_heap.rb
 - lib/async/background/runner.rb
 - lib/async/background/version.rb
@@ -117,7 +118,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
+rubygems_version: 3.3.27
 signing_key:
 specification_version: 4
 summary: Lightweight heap-based cron/interval scheduler for Async.