good_job 1.2.4 → 1.3.2

data/lib/good_job/multi_scheduler.rb

@@ -1,33 +1,48 @@
 module GoodJob
+  # Delegates the interface of a single {Scheduler} to multiple Schedulers.
   class MultiScheduler
+    # @return [array<Scheduler>] List of the scheduler delegates
     attr_reader :schedulers
 
     def initialize(schedulers)
       @schedulers = schedulers
     end
 
+    # Delegates to {Scheduler#shutdown}.
     def shutdown(wait: true)
       schedulers.each { |s| s.shutdown(wait: wait) }
     end
 
+    # Delegates to {Scheduler#shutdown?}.
     def shutdown?
       schedulers.all?(&:shutdown?)
     end
 
+    # Delegates to {Scheduler#restart}.
     def restart(wait: true)
       schedulers.each { |s| s.restart(wait: wait) }
     end
 
+    # Delegates to {Scheduler#create_thread}.
     def create_thread(state = nil)
       results = []
-      any_true = schedulers.any? do |scheduler|
-        scheduler.create_thread(state).tap { |result| results << result }
+
+      if state
+        schedulers.any? do |scheduler|
+          scheduler.create_thread(state).tap { |result| results << result }
+        end
+      else
+        schedulers.each do |scheduler|
+          results << scheduler.create_thread(state)
+        end
       end
 
-      if any_true
+      if results.any?
         true
-      else
-        results.any? { |result| result == false } ? false : nil
+      elsif results.any? { |result| result == false }
+        false
+      else # rubocop:disable Style/EmptyElse
+        nil
       end
     end
   end

data/lib/good_job/notifier.rb

@@ -2,10 +2,16 @@ require 'concurrent/atomic/atomic_boolean'
 
 module GoodJob # :nodoc:
   #
-  # Wrapper for Postgres LISTEN/NOTIFY
+  # Notifiers hook into Postgres LISTEN/NOTIFY functionality to emit and listen for notifications across processes.
+  #
+  # Notifiers can emit NOTIFY messages through Postgres.
+  # A notifier will LISTEN for messages by creating a background thread that runs in an instance of +Concurrent::ThreadPoolExecutor+.
+  # When a message is received, the notifier passes the message to each of its recipients.
   #
   class Notifier
+    # Default Postgres channel for LISTEN/NOTIFY
     CHANNEL = 'good_job'.freeze
+    # Defaults for instance of Concurrent::ThreadPoolExecutor
     POOL_OPTIONS = {
       name: name,
       min_threads: 0,
@@ -15,22 +21,29 @@ module GoodJob # :nodoc:
       max_queue: 1,
       fallback_policy: :discard,
     }.freeze
+    # Seconds to block while LISTENing for a message
     WAIT_INTERVAL = 1
 
     # @!attribute [r] instances
     #   @!scope class
-    #   @return [array<GoodJob:Adapter>] the instances of +GoodJob::Notifier+
+    #   List of all instantiated Notifiers in the current process.
+    #   @return [array<GoodJob:Adapter>]
     cattr_reader :instances, default: [], instance_reader: false
 
+    # Send a message via Postgres NOTIFY
+    # @param message [#to_json]
     def self.notify(message)
       connection = ActiveRecord::Base.connection
-      connection.exec_query <<~SQL
+      connection.exec_query <<~SQL.squish
         NOTIFY #{CHANNEL}, #{connection.quote(message.to_json)}
       SQL
     end
 
+    # List of recipients that will receive notifications.
+    # @return [Array<#call, Array(Object, Symbol)>]
     attr_reader :recipients
 
+    # @param recipients [Array<#call, Array(Object, Symbol)>]
     def initialize(*recipients)
       @recipients = Concurrent::Array.new(recipients)
       @listening = Concurrent::AtomicBoolean.new(false)
@@ -41,16 +54,29 @@ module GoodJob # :nodoc:
       listen
     end
 
+    # Tests whether the notifier is active and listening for new messages.
+    # @return [true, false, nil]
     def listening?
       @listening.true?
     end
 
+    # Restart the notifier.
+    # When shutdown, start; or shutdown and start.
+    # @param wait [Boolean] Wait for background thread to finish
+    # @return [void]
     def restart(wait: true)
       shutdown(wait: wait)
       create_pool
       listen
     end
 
+    # Shut down the notifier.
+    # This stops the background LISTENing thread.
+    # If +wait+ is +true+, the notifier will wait for background thread to shutdown.
+    # If +wait+ is +false+, this method will return immediately even though threads may still be running.
+    # Use {#shutdown?} to determine whether threads have stopped.
+    # @param wait [Boolean] Wait for actively executing threads to finish
+    # @return [void]
     def shutdown(wait: true)
       return unless @pool.running?
 
@@ -58,6 +84,8 @@ module GoodJob # :nodoc:
       @pool.wait_for_termination if wait
     end
 
+    # Tests whether the notifier is shutdown.
+    # @return [true, false, nil]
     def shutdown?
       !@pool.running?
     end
@@ -70,38 +98,36 @@ module GoodJob # :nodoc:
 
     def listen
       future = Concurrent::Future.new(args: [@recipients, @pool, @listening], executor: @pool) do |recipients, pool, listening|
-        begin
-          with_listen_connection do |conn|
-            ActiveSupport::Notifications.instrument("notifier_listen.good_job") do
-              conn.async_exec "LISTEN #{CHANNEL}"
-            end
+        with_listen_connection do |conn|
+          ActiveSupport::Notifications.instrument("notifier_listen.good_job") do
+            conn.async_exec "LISTEN #{CHANNEL}"
+          end
 
-            ActiveSupport::Dependencies.interlock.permit_concurrent_loads do
-              while pool.running?
-                listening.make_true
-                conn.wait_for_notify(WAIT_INTERVAL) do |channel, _pid, payload|
-                  listening.make_false
-                  next unless channel == CHANNEL
-
-                  ActiveSupport::Notifications.instrument("notifier_notified.good_job", { payload: payload })
-                  parsed_payload = JSON.parse(payload, symbolize_names: true)
-                  recipients.each do |recipient|
-                    target, method_name = recipient.is_a?(Array) ? recipient : [recipient, :call]
-                    target.send(method_name, parsed_payload)
-                  end
-                end
+          ActiveSupport::Dependencies.interlock.permit_concurrent_loads do
+            while pool.running?
+              listening.make_true
+              conn.wait_for_notify(WAIT_INTERVAL) do |channel, _pid, payload|
                 listening.make_false
+                next unless channel == CHANNEL
+
+                ActiveSupport::Notifications.instrument("notifier_notified.good_job", { payload: payload })
+                parsed_payload = JSON.parse(payload, symbolize_names: true)
+                recipients.each do |recipient|
+                  target, method_name = recipient.is_a?(Array) ? recipient : [recipient, :call]
+                  target.send(method_name, parsed_payload)
+                end
               end
+              listening.make_false
             end
           end
-        rescue StandardError => e
-          ActiveSupport::Notifications.instrument("notifier_notify_error.good_job", { error: e })
-          raise
-        ensure
-          @listening.make_false
-          ActiveSupport::Notifications.instrument("notifier_unlisten.good_job") do
-            conn.async_exec "UNLISTEN *"
-          end
+        end
+      rescue StandardError => e
+        ActiveSupport::Notifications.instrument("notifier_notify_error.good_job", { error: e })
+        raise
+      ensure
+        @listening.make_false
+        ActiveSupport::Notifications.instrument("notifier_unlisten.good_job") do
+          conn.async_exec "UNLISTEN *"
         end
       end
 
@@ -121,7 +147,7 @@ module GoodJob # :nodoc:
       pg_conn.exec("SET application_name = #{pg_conn.escape_identifier(self.class.name)}")
       yield pg_conn
     ensure
-      ar_conn.disconnect!
+      ar_conn&.disconnect!
     end
   end
 end

data/lib/good_job/performer.rb

@@ -1,7 +1,33 @@
 module GoodJob
+  #
+  # Performer queries the database for jobs and performs them on behalf of a
+  # {Scheduler}. It mainly functions as glue between a {Scheduler} and the jobs
+  # it should be executing.
+  #
+  # The Performer enforces a callable that does not rely on scoped/closure
+  # variables because they might not be available when executed in a different
+  # thread.
+  #
   class Performer
+    # @!attribute [r] name
+    # @return [String]
+    #   a meaningful name to identify the performer in logs and for debugging.
+    #   This is usually set to the list of queues the performer will query,
+    #   e.g. +"-transactional_messages,batch_processing"+.
     attr_reader :name
 
+    # @param target [Object]
+    #   An object that can perform jobs. It must respond to +method_name+ by
+    #   finding and performing jobs and is usually a {Job} query,
+    #   e.g. +GoodJob::Job.where(queue_name: ['queue1', 'queue2'])+.
+    # @param method_name [Symbol]
+    #   The name of a method on +target+ that finds and performs jobs.
+    # @param name [String]
+    #   A name for the performer to be used in logs and for debugging.
+    # @param filter [#call]
+    #   Used to determine whether the performer should be used in GoodJob's
+    #   current state. GoodJob state is a +Hash+ that will be passed as the
+    #   first argument to +filter+ and includes info like the current queue.
     def initialize(target, method_name, name: nil, filter: nil)
       @target = target
       @method_name = method_name
@@ -9,10 +35,22 @@ module GoodJob
       @filter = filter
     end
 
+    # Find and perform any eligible jobs.
     def next
       @target.public_send(@method_name)
     end
 
+    # Tests whether this performer should be used in GoodJob's current state by
+    # calling the +filter+ callable set in {#initialize}. Always returns +true+
+    # if there is no filter.
+    #
+    # For example, state will be a LISTEN/NOTIFY message that is passed down
+    # from the Notifier to the Scheduler. The Scheduler is able to ask
+    # its performer "does this message relate to you?", and if not, ignore it
+    # to minimize thread wake-ups, database queries, and thundering herds.
+    #
+    # @return [Boolean] whether the performer's {#next} method should be
+    #   called in the current state.
     def next?(state = {})
       return true unless @filter.respond_to?(:call)
 

data/lib/good_job/poller.rb

@@ -0,0 +1,94 @@
+require 'concurrent/atomic/atomic_boolean'
+
+module GoodJob # :nodoc:
+  #
+  # Pollers regularly wake up execution threads to check for new work.
+  #
+  class Poller
+    # Defaults for instance of Concurrent::TimerTask.
+    # The timer controls how and when sleeping threads check for new work.
+    DEFAULT_TIMER_OPTIONS = {
+      execution_interval: Configuration::DEFAULT_POLL_INTERVAL,
+      timeout_interval: 1,
+      run_now: true,
+    }.freeze
+
+    # @!attribute [r] instances
+    #   @!scope class
+    #   List of all instantiated Pollers in the current process.
+    #   @return [array<GoodJob:Poller>]
+    cattr_reader :instances, default: [], instance_reader: false
+
+    def self.from_configuration(configuration)
+      GoodJob::Poller.new(poll_interval: configuration.poll_interval)
+    end
+
+    # List of recipients that will receive notifications.
+    # @return [Array<#call, Array(Object, Symbol)>]
+    attr_reader :recipients
+
+    # @param recipients [Array<#call, Array(Object, Symbol)>]
+    # @param poll_interval [Hash] number of seconds between polls
+    def initialize(*recipients, poll_interval: nil)
+      @recipients = Concurrent::Array.new(recipients)
+
+      @timer_options = DEFAULT_TIMER_OPTIONS.dup
+      @timer_options[:execution_interval] = poll_interval if poll_interval.present?
+
+      self.class.instances << self
+
+      create_pool
+    end
+
+    # Shut down the poller.
+    # If +wait+ is +true+, the poller will wait for background thread to shutdown.
+    # If +wait+ is +false+, this method will return immediately even though threads may still be running.
+    # Use {#shutdown?} to determine whether threads have stopped.
+    # @param wait [Boolean] Wait for actively executing threads to finish
+    # @return [void]
+    def shutdown(wait: true)
+      return unless @timer&.running?
+
+      @timer.shutdown
+      @timer.wait_for_termination if wait
+    end
+
+    # Tests whether the poller is shutdown.
+    # @return [true, false, nil]
+    def shutdown?
+      !@timer&.running?
+    end
+
+    # Restart the poller.
+    # When shutdown, start; or shutdown and start.
+    # @param wait [Boolean] Wait for background thread to finish
+    # @return [void]
+    def restart(wait: true)
+      shutdown(wait: wait)
+      create_pool
+    end
+
+    # Invoked on completion of TimerTask task.
+    # @!visibility private
+    # @return [void]
+    def timer_observer(time, executed_task, thread_error)
+      GoodJob.on_thread_error.call(thread_error) if thread_error && GoodJob.on_thread_error.respond_to?(:call)
+      instrument("finished_timer_task", { result: executed_task, error: thread_error, time: time })
+    end
+
+    private
+
+    def create_pool
+      return if @timer_options[:execution_interval] <= 0
+
+      @timer = Concurrent::TimerTask.new(@timer_options) do
+        recipients.each do |recipient|
+          target, method_name = recipient.is_a?(Array) ? recipient : [recipient, :call]
+          target.send(method_name)
+        end
+      end
+      @timer.add_observer(self, :timer_observer)
+      @timer.execute
+    end
+  end
+end

data/lib/good_job/railtie.rb

@@ -1,4 +1,5 @@
 module GoodJob
+  # Ruby on Rails integration.
   class Railtie < ::Rails::Railtie
     initializer "good_job.logger" do
       ActiveSupport.on_load(:good_job) { self.logger = ::Rails.logger }

data/lib/good_job/scheduler.rb

@@ -4,26 +4,22 @@ require "concurrent/utility/processor_counter"
 
 module GoodJob # :nodoc:
   #
-  # Schedulers are generic thread execution pools that are responsible for
-  # periodically checking for available execution tasks, executing tasks in a
-  # bounded thread-pool, and efficiently scaling execution threads.
+  # Schedulers are generic thread pools that are responsible for
+  # periodically checking for available tasks, executing tasks within a thread,
+  # and efficiently scaling active threads.
   #
-  # Schedulers are "generic" in the sense that they delegate task execution
-  # details to a "Performer" object that responds to #next.
+  # Every scheduler has a single {Performer} that will execute tasks.
+  # The scheduler is responsible for calling its performer efficiently across threads managed by an instance of +Concurrent::ThreadPoolExecutor+.
+  # If a performer does not have work, the thread will go to sleep.
+  # The scheduler maintains an instance of +Concurrent::TimerTask+, which wakes sleeping threads and causes them to check whether the performer has new work.
   #
   class Scheduler
-    # Defaults for instance of Concurrent::TimerTask
-    DEFAULT_TIMER_OPTIONS = {
-      execution_interval: 1,
-      timeout_interval: 1,
-      run_now: true,
-    }.freeze
-
     # Defaults for instance of Concurrent::ThreadPoolExecutor
+    # The thread pool is where work is performed.
     DEFAULT_POOL_OPTIONS = {
       name: name,
       min_threads: 0,
-      max_threads: Concurrent.processor_count,
+      max_threads: Configuration::DEFAULT_MAX_THREADS,
       auto_terminate: true,
       idletime: 60,
       max_queue: -1,
@@ -32,7 +28,7 @@ module GoodJob # :nodoc:
 
     # @!attribute [r] instances
     #   @!scope class
-    #   All instantiated Schedulers in the current process.
+    #   List of all instantiated Schedulers in the current process.
     #   @return [array<GoodJob:Scheduler>]
     cattr_reader :instances, default: [], instance_reader: false
 
@@ -48,7 +44,7 @@ module GoodJob # :nodoc:
         parsed = GoodJob::Job.queue_parser(queue_string)
         job_filter = proc do |state|
           if parsed[:exclude]
-            !parsed[:exclude].include? state[:queue_name]
+            parsed[:exclude].exclude?(state[:queue_name])
           elsif parsed[:include]
             parsed[:include].include? state[:queue_name]
           else
@@ -57,14 +53,7 @@ module GoodJob # :nodoc:
         end
         job_performer = GoodJob::Performer.new(job_query, :perform_with_advisory_lock, name: queue_string, filter: job_filter)
 
-        timer_options = {}
-        timer_options[:execution_interval] = configuration.poll_interval
-
-        pool_options = {
-          max_threads: max_threads,
-        }
-
-        GoodJob::Scheduler.new(job_performer, timer_options: timer_options, pool_options: pool_options)
+        GoodJob::Scheduler.new(job_performer, max_threads: max_threads)
       end
 
       if schedulers.size > 1
@@ -75,68 +64,65 @@ module GoodJob # :nodoc:
     end
 
     # @param performer [GoodJob::Performer]
-    # @param timer_options [Hash] Options to instantiate a Concurrent::TimerTask
-    # @param pool_options [Hash] Options to instantiate a Concurrent::ThreadPoolExecutor
-    def initialize(performer, timer_options: {}, pool_options: {})
+    # @param max_threads [Numeric, nil] number of seconds between polls for jobs
+    def initialize(performer, max_threads: nil)
       raise ArgumentError, "Performer argument must implement #next" unless performer.respond_to?(:next)
 
       self.class.instances << self
 
       @performer = performer
-      @pool_options = DEFAULT_POOL_OPTIONS.merge(pool_options)
-      @timer_options = DEFAULT_TIMER_OPTIONS.merge(timer_options)
 
-      @pool_options[:name] = "GoodJob::Scheduler(queues=#{@performer.name} max_threads=#{@pool_options[:max_threads]} poll_interval=#{@timer_options[:execution_interval]})"
+      @pool_options = DEFAULT_POOL_OPTIONS.dup
+      @pool_options[:max_threads] = max_threads if max_threads.present?
+      @pool_options[:name] = "GoodJob::Scheduler(queues=#{@performer.name} max_threads=#{@pool_options[:max_threads]})"
 
-      create_pools
+      create_pool
     end
 
-    # Shut down the Scheduler.
+    # Shut down the scheduler.
+    # This stops all threads in the pool.
+    # If +wait+ is +true+, the scheduler will wait for any active tasks to finish.
+    # If +wait+ is +false+, this method will return immediately even though threads may still be running.
+    # Use {#shutdown?} to determine whether threads have stopped.
     # @param wait [Boolean] Wait for actively executing jobs to finish
     # @return [void]
     def shutdown(wait: true)
-      @_shutdown = true
+      return unless @pool&.running?
 
       instrument("scheduler_shutdown_start", { wait: wait })
       instrument("scheduler_shutdown", { wait: wait }) do
-        if @timer&.running?
-          @timer.shutdown
-          @timer.wait_for_termination if wait
-        end
-
-        if @pool&.running?
-          @pool.shutdown
-          @pool.wait_for_termination if wait
-        end
+        @pool.shutdown
+        @pool.wait_for_termination if wait
+        # TODO: Should be killed if wait is not true
       end
     end
 
-    # True when the Scheduler is shutdown.
+    # Tests whether the scheduler is shutdown.
     # @return [true, false, nil]
     def shutdown?
-      @_shutdown
+      !@pool&.running?
     end
 
-    # Restart the Scheduler. When shutdown, start; or shutdown and start.
+    # Restart the Scheduler.
+    # When shutdown, start; or shutdown and start.
     # @param wait [Boolean] Wait for actively executing jobs to finish
     # @return [void]
     def restart(wait: true)
       instrument("scheduler_restart_pools") do
         shutdown(wait: wait) unless shutdown?
-        create_pools
-        @_shutdown = false
+        create_pool
       end
     end
 
-    # Triggers a Performer execution, if an execution thread is available.
-    # @param state [nil, Object] Allows Performer#next? to accept or reject the execution
-    # @return [nil, Boolean] if the thread was created
+    # Wakes a thread to allow the performer to execute a task.
+    # @param state [nil, Object] Contextual information for the performer. See {Performer#next?}.
+    # @return [nil, Boolean] Whether work was started.
+    #   Returns +nil+ if the scheduler is unable to take new work, for example if the thread pool is shut down or at capacity.
+    #   Returns +true+ if the performer started executing work.
+    #   Returns +false+ if the performer decides not to attempt to execute a task based on the +state+ that is passed to it.
     def create_thread(state = nil)
       return nil unless @pool.running? && @pool.ready_worker_count.positive?
-
-      if state
-        return false unless @performer.next?(state)
-      end
+      return false if state && !@performer.next?(state)
 
       future = Concurrent::Future.new(args: [@performer], executor: @pool) do |performer|
         output = nil
@@ -149,14 +135,6 @@ module GoodJob # :nodoc:
       true
     end
 
-    # Invoked on completion of TimerTask task.
-    # @!visibility private
-    # @return [void]
-    def timer_observer(time, executed_task, thread_error)
-      GoodJob.on_thread_error.call(thread_error) if thread_error && GoodJob.on_thread_error.respond_to?(:call)
-      instrument("finished_timer_task", { result: executed_task, error: thread_error, time: time })
-    end
-
     # Invoked on completion of ThreadPoolExecutor task
     # @!visibility private
     # @return [void]
@@ -168,15 +146,9 @@ module GoodJob # :nodoc:
 
     private
 
-    # @return [void]
-    def create_pools
-      instrument("scheduler_create_pools", { performer_name: @performer.name, max_threads: @pool_options[:max_threads], poll_interval: @timer_options[:execution_interval] }) do
+    def create_pool
+      instrument("scheduler_create_pool", { performer_name: @performer.name, max_threads: @pool_options[:max_threads] }) do
         @pool = ThreadPoolExecutor.new(@pool_options)
-        next unless @timer_options[:execution_interval].positive?
-
-        @timer = Concurrent::TimerTask.new(@timer_options) { create_thread }
-        @timer.add_observer(self, :timer_observer)
-        @timer.execute
       end
     end
 
@@ -189,19 +161,20 @@ module GoodJob # :nodoc:
 
       ActiveSupport::Notifications.instrument("#{name}.good_job", payload, &block)
     end
-  end
 
-  # Slightly customized sub-class of Concurrent::ThreadPoolExecutor
-  class ThreadPoolExecutor < Concurrent::ThreadPoolExecutor
-    # Number of idle or potential threads available to execute tasks
-    # https://github.com/ruby-concurrency/concurrent-ruby/issues/684#issuecomment-427594437
-    # @return [Integer]
-    def ready_worker_count
-      synchronize do
-        workers_still_to_be_created = @max_length - @pool.length
-        workers_created_but_waiting = @ready.length
-
-        workers_still_to_be_created + workers_created_but_waiting
+    # Custom sub-class of +Concurrent::ThreadPoolExecutor+ to add additional worker status.
+    # @private
+    class ThreadPoolExecutor < Concurrent::ThreadPoolExecutor
+      # Number of inactive threads available to execute tasks.
+      # https://github.com/ruby-concurrency/concurrent-ruby/issues/684#issuecomment-427594437
+      # @return [Integer]
+      def ready_worker_count
+        synchronize do
+          workers_still_to_be_created = @max_length - @pool.length
+          workers_created_but_waiting = @ready.length
+
+          workers_still_to_be_created + workers_created_but_waiting
+        end
       end
     end
   end