async-background 1.1.0 → 1.1.1

data/lib/async/background/runner.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'runtime'
+require_relative 'runner/lifecycle'
 require_relative 'runner/queue_execution'
 require_relative 'runner/schedule'
 
@@ -21,9 +22,16 @@ module Async
 
     class Runner
       include Clock
+      include Lifecycle
       include QueueExecution
       include Schedule
 
+      Settings = Data.define(
+        :config_path, :job_count, :queue_socket_dir, :queue_db_path, :queue_mmap,
+        :drain_timeout, :metrics_shm_path
+      )
+      private_constant :Settings
+
       attr_reader :logger,
                   :semaphore,
                   :heap,
@@ -35,33 +43,43 @@ module Async
                   :jobs,
                   :services
 
-      def initialize(
-        config_path: nil,
-        job_count: 2,
-        worker_index:,
-        total_workers:,
-        queue_socket_dir: nil,
-        queue_db_path: nil,
-        queue_mmap: true,
-        drain_timeout: DRAIN_GRACE,
-        metrics_shm_path: Metrics.default_shm_path
-      )
+      def initialize(worker_index:, total_workers:, **options)
+        settings = Settings.new(**default_settings.merge(options))
+        initialize_worker(worker_index, total_workers, settings)
+      end
+
+      def default_settings
+        {
+          config_path: nil,
+          job_count: 2,
+          queue_socket_dir: nil,
+          queue_db_path: nil,
+          queue_mmap: true,
+          drain_timeout: DRAIN_GRACE,
+          metrics_shm_path: Metrics.default_shm_path
+        }
+      end
+
+      def initialize_worker(worker_index, total_workers, settings)
+        config_path = settings.config_path
+        job_count = settings.job_count
         @logger = Console.logger
         @worker_index = worker_index
         @total_workers = total_workers
         @running = true
-        @drain_timeout = drain_timeout
+        @drain_timeout = settings.drain_timeout
         @shutdown = Runtime::Notification.new
-        @metrics = Metrics.new(worker_index: worker_index, total_workers: total_workers, shm_path: metrics_shm_path)
+        @metrics = Metrics.new(worker_index: worker_index, total_workers: total_workers, shm_path: settings.metrics_shm_path)
         logger.info { "Async::Background worker_index=#{worker_index}/#{total_workers}, job_count=#{job_count}" }
 
         @jobs = Runtime::TaskGroup.new(on_error: error_handler, on_release: method(:job_released))
         @services = Runtime::TaskGroup.new(on_error: error_handler)
         @semaphore = Runtime::Semaphore.new(job_count)
         @heap = config_path.nil? ? MinHeap.new : build_heap(config_path)
-        setup_queue(queue_socket_dir, queue_db_path, queue_mmap)
+        setup_queue(settings.queue_socket_dir, settings.queue_db_path, settings.queue_mmap)
         validate_work_source!(config_path)
       end
+      private :default_settings, :initialize_worker
 
       def run
         Runtime.scheduler!
@@ -142,8 +160,8 @@ module Async
         end
       end
 
-      def spawn_job(&block)
-        @jobs.spawn(name: 'job') { |task| semaphore.acquire { block.call(task) } }
+      def spawn_job
+        @jobs.spawn(name: 'job') { |task| semaphore.acquire { yield(task) } }
       end
 
       def job_released(_task)
@@ -154,134 +172,47 @@ module Async
 
       def run_job(job_task, entry)
         metrics_started = false
-        metrics.job_started(entry)
-        metrics_started = true
-        started_at = monotonic_now
-        job_task.with_timeout(entry.timeout) { entry.job_class.perform_now }
-
-        duration = monotonic_now - started_at
-        metrics.job_succeeded(entry, duration)
-        logger.info('Async::Background') { "#{entry.name}: completed in #{duration.round(2)}s" }
+        metrics_started = start_job_metrics(entry)
+        execute_entry_job(job_task, entry)
       rescue Runtime::TimeoutError
-        metrics.job_timed_out(entry)
-        logger.error('Async::Background') { "#{entry.name}: timed out after #{entry.timeout}s" }
-      rescue StandardError => error
-        metrics.job_failed(entry, error)
-        logger.error('Async::Background') {
-          "#{entry.name}: #{error.class} #{error.message}\n#{error.backtrace.join("\n")}"
-        }
+        record_job_timeout(entry)
+      rescue StandardError => e
+        record_job_failure(entry, e)
       ensure
         metrics.job_stopped(entry) if metrics_started
       end
 
-      def setup_signal_handlers
-        @signal_r, @signal_w = IO.pipe
-
-        %w[INT TERM].each do |signal|
-          Signal.trap(signal) do
-            @running = false
-            @signal_w.write_nonblock('.') rescue nil
-          end
-        end
+      def start_job_metrics(entry)
+        metrics.job_started(entry)
+        true
       end
 
-      def start_signal_watcher
-        @services.spawn(name: 'signal-watcher') do
-          while running?
-            begin
-              @signal_r.wait_readable
-              @signal_r.read_nonblock(256)
-            rescue IO::WaitReadable
-              next
-            rescue IOError, Errno::EBADF
-              break
-            end
-
-            logger.info { 'Async::Background: stopping gracefully' } unless running?
-
-            shutdown.signal_all
-            @queue_waker&.signal
-          end
-        end
+      def execute_entry_job(job_task, entry)
+        started_at = monotonic_now
+        job_task.with_timeout(entry.timeout) { entry.job_class.perform_now }
+        record_job_success(entry, monotonic_now - started_at)
       end
 
-      def error_handler
-        @error_handler ||= begin
-          log = logger
-          lambda do |task, error|
-            log.error('Async::Background') do
-              "task #{task&.name || 'unnamed'} died: #{error.class} #{error.message}\n" \
-                "#{Array(error.backtrace).join("\n")}"
-            end
-          end
-        end
+      def record_job_success(entry, duration)
+        metrics.job_succeeded(entry, duration)
+        logger.info('Async::Background') { "#{entry.name}: completed in #{duration.round(2)}s" }
       end
 
-      def warn_unsafe_timeouts
-        return if Runtime.native_timeouts?
-
-        logger.warn('Async::Background') do
-          "#{Fiber.scheduler.class} does not implement #timeout_after; job timeouts " \
-            'fall back to stdlib Timeout and may interrupt an unrelated fiber'
-        end
+      def record_job_timeout(entry)
+        metrics.job_timed_out(entry)
+        logger.error('Async::Background') { "#{entry.name}: timed out after #{entry.timeout}s" }
       end
 
-      def wake_signal_watcher
-        @signal_w&.write_nonblock('.')
-      rescue StandardError
-        nil
+      def record_job_failure(entry, error)
+        metrics.job_failed(entry, error)
+        logger.error('Async::Background') do
+          "#{entry.name}: #{error.class} #{error.message}\n#{error.backtrace.join("\n")}"
+        end
       end
 
       def wait_with_shutdown(duration)
         shutdown.wait(duration)
       end
-
-      def shutdown_gracefully
-        wake_services
-        drain_jobs
-        stop_services
-        close_queue
-        close_signal_pipe
-      end
-
-      def wake_services
-        shutdown.signal_all
-        wake_signal_watcher
-        @queue_waker&.signal
-      end
-
-      def drain_jobs
-        return if @jobs.empty?
-
-        logger.info { "Async::Background: draining #{@jobs.size} in-flight job(s)" }
-        @jobs.wait(@drain_timeout)
-      rescue Runtime::TimeoutError
-        logger.warn('Async::Background') do
-          "#{@jobs.size} job(s) still running after #{@drain_timeout}s, cancelling"
-        end
-        @jobs.stop_all(JOB_CANCEL_GRACE)
-      end
-
-      def stop_services
-        return if @services.empty?
-
-        @services.wait(SERVICE_SHUTDOWN_GRACE)
-      rescue Runtime::TimeoutError
-        logger.warn('Async::Background') { 'service tasks did not exit in time, cancelling' }
-        @services.stop_all(SERVICE_CANCEL_GRACE)
-      end
-
-      def close_queue
-        @queue_waker&.close
-        @queue_store&.close
-      end
-
-      def close_signal_pipe
-        @signal_r&.close
-        @signal_w&.close
-      rescue IOError
-        nil
-      end
     end
   end
 end

data/lib/async/background/runtime/notification.rb

@@ -31,7 +31,8 @@ module Async
         def signal_all
           return nil if @waiters.empty?
 
-          pending, @waiters = @waiters, []
+          pending = @waiters
+          @waiters = []
           pending.each { |waiter| Runtime.wake_dequeued(waiter, self) }
           nil
         end

data/lib/async/background/runtime/semaphore.rb

@@ -4,7 +4,7 @@ module Async
   module Background
     module Runtime
       class Semaphore
-        attr_reader :limit
+        attr_reader :limit, :available
 
         def initialize(limit)
           @limit = Integer(limit)
@@ -14,7 +14,6 @@ module Async
           @waiting = WaitList.new
         end
 
-        def available = @available
         def waiting = @waiting.size
 
         def acquire
@@ -47,17 +46,22 @@ module Async
           node = FiberNode.new(Fiber.current, self)
           @waiting.push(node)
           task&.enter_block(node.waiter)
+          wait_for_grant(node, task)
+        ensure
+          release_wait_state(node, task) if node
+        end
 
-          begin
-            until node.granted?
-              node.suspend
-              abandon_wait!(node, task) if task&.cancelled?
-            end
+        def wait_for_grant(node, task)
+          until node.granted?
+            node.suspend
             abandon_wait!(node, task) if task&.cancelled?
-          ensure
-            task&.exit_block
-            @waiting.remove(node) unless node.granted? || node.list.nil?
           end
+          abandon_wait!(node, task) if task&.cancelled?
+        end
+
+        def release_wait_state(node, task)
+          task&.exit_block
+          @waiting.remove(node) unless node.granted? || node.list.nil?
         end
 
         def abandon_wait!(node, task)
@@ -115,7 +119,7 @@ module Async
             @list = @prev = @next = nil
             @granted = false
             @scheduler = Runtime.scheduler!
-            @waiter = {fiber: fiber, scheduler: @scheduler, ready: false, blocker: blocker, queued: true}
+            @waiter = { fiber: fiber, scheduler: @scheduler, ready: false, blocker: blocker, queued: true }
           end
 
           def granted? = @granted

data/lib/async/background/runtime/task.rb

@@ -29,20 +29,7 @@ module Async
           @scheduler = Runtime.scheduler!
           takes_task = !block.arity.zero?
 
-          scheduled = Fiber.schedule do
-            adopt_fiber(Fiber.current)
-            previous = Runtime.current_task
-            Runtime.current_task = self
-            begin
-              complete(takes_task ? block.call(self) : block.call, nil)
-            rescue Cancel
-              complete(nil, nil)
-            rescue Exception => e # rubocop:disable Lint/RescueException
-              complete(nil, e)
-            ensure
-              Runtime.current_task = previous
-            end
-          end
+          scheduled = Fiber.schedule { run_scheduled_task { takes_task ? yield(self) : yield } }
 
           @fiber ||= scheduled if scheduled.is_a?(Fiber)
           self
@@ -92,15 +79,28 @@ module Async
 
         private
 
+        def run_scheduled_task
+          adopt_fiber(Fiber.current)
+          previous = Runtime.current_task
+          Runtime.current_task = self
+          complete(yield, nil)
+        rescue Cancel
+          complete(nil, nil)
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          complete(nil, e)
+        ensure
+          Runtime.current_task = previous
+        end
+
         def adopt_fiber(fiber)
-          @fiber ||= fiber
+          @adopt_fiber ||= fiber
         end
 
         def interrupt_fiber
           fiber = @fiber
           scheduler = @scheduler
           return false unless fiber&.alive?
-          return false unless scheduler&.respond_to?(:fiber_interrupt)
+          return false unless scheduler.respond_to?(:fiber_interrupt)
 
           result = scheduler.fiber_interrupt(fiber, Cancel.new('task stopped'))
           result != false
@@ -136,7 +136,8 @@ module Async
         def wake_waiters
           return if @waiters.nil? || @waiters.empty?
 
-          pending, @waiters = @waiters, []
+          pending = @waiters
+          @waiters = []
           pending.each { |waiter| Runtime.wake_dequeued(waiter, self) }
         end
       end

data/lib/async/background/runtime/task_group.rb

@@ -72,8 +72,8 @@ module Async
           handler = @on_release or return
 
           handler.call(task)
-        rescue StandardError => error
-          Runtime.report_error(task, error, @on_error)
+        rescue StandardError => e
+          Runtime.report_error(task, e, @on_error)
         end
       end
     end

data/lib/async/background/runtime.rb

@@ -48,6 +48,40 @@ module Async
 
       module_function
 
+      module FiberLocals
+        def current_task
+          fiber_local(CURRENT_TASK_KEY)
+        end
+
+        def current_task=(task)
+          set_fiber_local(CURRENT_TASK_KEY, task)
+        end
+
+        def fiber_local(key)
+          Fiber[key]
+        rescue ArgumentError, FiberError
+          fiber_local_fallback[key]
+        end
+
+        def set_fiber_local(key, value)
+          Fiber[key] = value
+        rescue ArgumentError, FiberError
+          fiber_local_fallback[key] = value
+        end
+
+        def clear_fiber_local(key, expected)
+          current = fiber_local(key)
+          set_fiber_local(key, nil) if current.equal?(expected)
+        end
+
+        def fiber_local_fallback
+          fiber = Fiber.current
+          store = fiber.instance_variable_get(:@async_background_locals)
+          store || fiber.instance_variable_set(:@async_background_locals, {})
+        end
+      end
+      extend FiberLocals
+
       def spawn(name: nil, on_error: UNSET, &block)
         Task.spawn(name: name, on_error: on_error, &block)
       end
@@ -64,14 +98,6 @@ module Async
         !target.nil? && target.respond_to?(:timeout_after)
       end
 
-      def current_task
-        fiber_local(CURRENT_TASK_KEY)
-      end
-
-      def current_task=(task)
-        set_fiber_local(CURRENT_TASK_KEY, task)
-      end
-
       def build_waiter(blocker)
         existing = fiber_local(WAITER_KEY)
         if existing&.[](:blocker)
@@ -94,25 +120,29 @@ module Async
         scheduler = waiter[:scheduler]
         task = current_task
         task&.enter_block(waiter)
+        park_until_ready(scheduler, blocker, waiter, deadline, task) { yield }
+      ensure
+        waiter[:blocker] = nil
+        clear_fiber_local(WAITER_KEY, waiter)
+        task&.exit_block
+      end
 
+      def park_until_ready(scheduler, blocker, waiter, deadline, task)
         until waiter[:ready] || yield
-          if deadline
-            remaining = deadline - monotonic_now
-            return false if remaining <= 0
-
-            scheduler.block(blocker, remaining)
-          else
-            scheduler.block(blocker, nil)
-          end
+          return false if wait_for_blocker(scheduler, blocker, deadline) == :expired
 
           task&.raise_if_cancelled!
         end
-
         true
-      ensure
-        waiter[:blocker] = nil
-        clear_fiber_local(WAITER_KEY, waiter)
-        task&.exit_block
+      end
+
+      def wait_for_blocker(scheduler, blocker, deadline)
+        return scheduler.block(blocker, nil) unless deadline
+
+        remaining = deadline - monotonic_now
+        return :expired if remaining <= 0
+
+        scheduler.block(blocker, remaining)
       end
 
       def with_waiter(blocker, waiters)
@@ -153,13 +183,9 @@ module Async
         monotonic_now + seconds
       end
 
-      def error_handler=(handler)
-        @error_handler = handler
-      end
-
-      def error_handler
-        @error_handler
-      end
+      attr_writer :error_handler
+      attr_reader :error_handler
+      module_function :error_handler=, :error_handler
 
       def with_error_handler(handler)
         previous = @error_handler
@@ -179,37 +205,14 @@ module Async
         false
       end
 
-      def fiber_local(key)
-        Fiber[key]
-      rescue ArgumentError, FiberError
-        fiber_local_fallback[key]
-      end
-
-      def set_fiber_local(key, value)
-        Fiber[key] = value
-      rescue ArgumentError, FiberError
-        fiber_local_fallback[key] = value
-      end
-
-      def clear_fiber_local(key, expected)
-        current = fiber_local(key)
-        set_fiber_local(key, nil) if current.equal?(expected)
-      end
-
-      def fiber_local_fallback
-        fiber = Fiber.current
-        store = fiber.instance_variable_get(:@async_background_locals)
-        store || fiber.instance_variable_set(:@async_background_locals, {})
-      end
-
-      def with_timeout(duration, on_timeout: UNSET)
+      def with_timeout(duration, on_timeout: UNSET, &block)
         return yield if duration.nil?
 
         seconds = Float(duration)
         raise ArgumentError, 'timeout must be positive and finite' unless seconds.finite? && seconds.positive?
 
         begin
-          arm_deadline(seconds) { yield }
+          arm_deadline(seconds, &block)
         rescue Deadline => e
           raise TimeoutError, e.message if UNSET.equal?(on_timeout)
 

data/lib/async/background/scheduler.rb

@@ -32,7 +32,7 @@ module Async
 
       def run(kind = nil, &block)
         raise ArgumentError, 'block required' unless block
-        return block.call if installed?
+        return yield if installed?
 
         case resolve(kind)
         when :async then run_async(&block)
@@ -75,7 +75,7 @@ module Async
         require 'async'
 
         result = nil
-        send(:Async) { result = block.call }
+        send(:Async) { result = yield }
         result
       end
 
@@ -101,7 +101,7 @@ module Async
 
         begin
           Fiber.schedule do
-            result = block.call
+            result = yield
           rescue Exception => e # rubocop:disable Lint/RescueException
             failure = e
           ensure
@@ -130,7 +130,7 @@ module Async
         thread = Thread.new do
           Fiber.set_scheduler(scheduler_class.new)
           Fiber.schedule do
-            result = block.call
+            result = yield
           rescue Exception => e # rubocop:disable Lint/RescueException
             failure = e
           end

data/lib/async/background/version.rb

@@ -2,6 +2,6 @@
 
 module Async
   module Background
-    VERSION = '1.1.0'
+    VERSION = '1.1.1'
   end
 end

data/lib/async/background/web/app.rb

@@ -35,9 +35,18 @@ module Async
         LIST_ROUTES = {
           executing: [:executing, :executing, nil].freeze,
           claimed: [:claimed, :claimed, nil].freeze,
-          done: [:recent_done, :done, :finished_cursor].freeze,
-          failed: [:recent_failed, :failed, :finished_cursor].freeze,
-          pending: [:pending, :pending, :pending_cursor].freeze
+          done: %i[recent_done done finished_cursor].freeze,
+          failed: %i[recent_failed failed finished_cursor].freeze,
+          pending: %i[pending pending pending_cursor].freeze
+        }.freeze
+        STATIC_ROUTES = {
+          index: :index_response,
+          javascript: :javascript_response,
+          stylesheet: :stylesheet_response,
+          overview: :overview_response,
+          metrics: :metrics_response,
+          config: :config_response,
+          stream: :stream_response
         }.freeze
 
         def handle(env, head:)
@@ -51,15 +60,15 @@ module Async
           end
 
           dispatch(route, env)
-        rescue RequestError => error
-          Response.bad_request(error.message)
+        rescue RequestError => e
+          Response.bad_request(e.message)
         rescue UnavailableError, ClosedError
           Response.unavailable
-        rescue StandardError => error
+        rescue StandardError => e
           # Do not turn internal class names, paths or database errors into an
           # unauthenticated information disclosure channel — but do surface
           # them to the operator via the configured logger.
-          log_internal_error(env, error)
+          log_internal_error(env, e)
           Response.internal_error
         end
 
@@ -78,25 +87,23 @@ module Async
         def dispatch(route, env)
           return list_response(route, env) if LIST_ROUTES.key?(route)
 
-          case route
-          when :index then Response.html(Assets.render_index(@config))
-          when :javascript then Response.javascript(Assets::JS)
-          when :stylesheet then Response.stylesheet(Assets::CSS)
-          when :overview then overview_response
-          when :metrics then metrics_response
-          when :config then config_response
-          when :stream then stream_response
-          else Response.not_found
-          end
+          handler = STATIC_ROUTES[route]
+          handler ? send(handler) : Response.not_found
         end
 
+        def index_response = Response.html(Assets.render_index(@config))
+
+        def javascript_response = Response.javascript(Assets::JS)
+
+        def stylesheet_response = Response.stylesheet(Assets::CSS)
+
         def list_response(route, env)
           reader, shape, cursor_kind = LIST_ROUTES.fetch(route)
           request = Request.new(env, @config)
 
           unless cursor_kind
             rows = @snapshot.public_send(reader, limit: request.limit)
-            return Response.json({items: @serializer.public_send(shape, rows)})
+            return Response.json({ items: @serializer.public_send(shape, rows) })
           end
 
           rows = @snapshot.public_send(reader, limit: request.limit, cursor: request.public_send(cursor_kind))
@@ -144,7 +151,7 @@ module Async
 
         def log_internal_error(env, error)
           @logger&.error(
-            "[async-background-web] internal error on " \
+            '[async-background-web] internal error on ' \
             "#{env['REQUEST_METHOD']} #{env['PATH_INFO']}: " \
             "#{error.class}: #{error.message}"
           )