good_job 1.2.4 → 1.2.5

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/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,15 +4,18 @@ 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
+    # Defaults for instance of Concurrent::TimerTask.
+    # The timer controls how and when sleeping threads check for new work.
     DEFAULT_TIMER_OPTIONS = {
       execution_interval: 1,
       timeout_interval: 1,
@@ -20,6 +23,7 @@ module GoodJob # :nodoc:
     }.freeze
 
     # Defaults for instance of Concurrent::ThreadPoolExecutor
+    # The thread pool is where work is performed.
     DEFAULT_POOL_OPTIONS = {
       name: name,
       min_threads: 0,
@@ -32,11 +36,12 @@ 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
 
     # Creates GoodJob::Scheduler(s) and Performers from a GoodJob::Configuration instance.
+    # TODO: move this to GoodJob::Configuration
     # @param configuration [GoodJob::Configuration]
     # @return [GoodJob::Scheduler, GoodJob::MultiScheduler]
     def self.from_configuration(configuration)
@@ -78,6 +83,7 @@ module GoodJob # :nodoc:
     # @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: {})
+      # TODO: Replace `timer_options` and `pool_options` with only `poll_interval` and `max_threads`
       raise ArgumentError, "Performer argument must implement #next" unless performer.respond_to?(:next)
 
       self.class.instances << self
@@ -91,7 +97,11 @@ module GoodJob # :nodoc:
       create_pools
     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)
@@ -102,22 +112,25 @@ module GoodJob # :nodoc:
         if @timer&.running?
           @timer.shutdown
           @timer.wait_for_termination if wait
+          # TODO: Should be killed if wait is not true
         end
 
         if @pool&.running?
           @pool.shutdown
           @pool.wait_for_termination if wait
+          # TODO: Should be killed if wait is not true
         end
       end
     end
 
-    # True when the Scheduler is shutdown.
+    # Tests whether the scheduler is shutdown.
     # @return [true, false, nil]
     def shutdown?
       @_shutdown
     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)
@@ -128,15 +141,15 @@ module GoodJob # :nodoc:
       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
@@ -168,7 +181,6 @@ 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
         @pool = ThreadPoolExecutor.new(@pool_options)
@@ -191,9 +203,10 @@ module GoodJob # :nodoc:
     end
   end
 
-  # Slightly customized sub-class of Concurrent::ThreadPoolExecutor
+  # Custom sub-class of +Concurrent::ThreadPoolExecutor+ to add additional worker status.
+  # @private
   class ThreadPoolExecutor < Concurrent::ThreadPoolExecutor
-    # Number of idle or potential threads available to execute tasks
+    # 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

data/lib/good_job/version.rb

@@ -1,3 +1,4 @@
 module GoodJob
-  VERSION = '1.2.4'.freeze
+  # GoodJob gem version.
+  VERSION = '1.2.5'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: good_job
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.2.5
 platform: ruby
 authors:
 - Ben Sheldon
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-01 00:00:00.000000000 Z
+date: 2020-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.1.0
+        version: 5.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.1.0
+        version: 5.2.0
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.1.0
+        version: 5.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.1.0
+        version: 5.2.0
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -72,14 +72,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.1.0
+        version: 5.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.1.0
+        version: 5.2.0
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.14.1
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  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: appraisal
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +122,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: database_cleaner
   requirement: !ruby/object:Gem::Requirement
@@ -136,6 +164,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: erb_lint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: foreman
   requirement: !ruby/object:Gem::Requirement
@@ -332,6 +374,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: selenium-webdriver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: sigdump
   requirement: !ruby/object:Gem::Requirement
@@ -360,6 +416,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard-activesupport-concern
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A multithreaded, Postgres-based ActiveJob backend for Ruby on Rails
 email:
 - bensheldon@gmail.com
@@ -374,6 +444,22 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- engine/app/controllers/good_job/active_jobs_controller.rb
+- engine/app/controllers/good_job/base_controller.rb
+- engine/app/controllers/good_job/dashboards_controller.rb
+- engine/app/helpers/good_job/application_helper.rb
+- engine/app/views/assets/_style.css.erb
+- engine/app/views/good_job/active_jobs/show.html.erb
+- engine/app/views/good_job/dashboards/index.html.erb
+- engine/app/views/layouts/good_job/base.html.erb
+- engine/app/views/shared/_chart.erb
+- engine/app/views/shared/_jobs_table.erb
+- engine/app/views/vendor/bootstrap/_bootstrap-native.js.erb
+- engine/app/views/vendor/bootstrap/_bootstrap.css.erb
+- engine/app/views/vendor/chartist/_chartist.css.erb
+- engine/app/views/vendor/chartist/_chartist.js.erb
+- engine/config/routes.rb
+- engine/lib/good_job/engine.rb
 - exe/good_job
 - lib/active_job/queue_adapters/good_job_adapter.rb
 - lib/generators/good_job/install_generator.rb
@@ -412,11 +498,12 @@ rdoc_options:
 - "--quiet"
 require_paths:
 - lib
+- engine/lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="