good_job 1.2.4 → 1.2.5

data/lib/good_job/lockable.rb

@@ -1,10 +1,33 @@
 module GoodJob
+  #
+  # Adds Postgres advisory locking capabilities to an ActiveRecord record.
+  # For details on advisory locks, see the Postgres documentation:
+  # - {https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS Advisory Locks Overview}
+  # - {https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS Advisory Locks Functions}
+  #
+  # @example Add this concern to a +MyRecord+ class:
+  #   class MyRecord < ActiveRecord::Base
+  #     include Lockable
+  #
+  #     def my_method
+  #       ...
+  #     end
+  #   end
+  #
   module Lockable
     extend ActiveSupport::Concern
 
+    # Indicates an advisory lock is already held on a record by another
+    # database session.
     RecordAlreadyAdvisoryLockedError = Class.new(StandardError)
 
     included do
+      # Attempt to acquire an advisory lock on the selected records and
+      # return only those records for which a lock could be acquired.
+      # @!method advisory_lock
+      # @!scope class
+      # @return [ActiveRecord::Relation]
+      #   A relation selecting only the records that were locked.
       scope :advisory_lock, (lambda do
         original_query = self
 
@@ -13,35 +36,92 @@ module GoodJob
 
         query = cte_table.project(cte_table[:id])
                   .with(composed_cte)
-                  .where(Arel.sql(sanitize_sql_for_conditions(["pg_try_advisory_lock(('x'||substr(md5(:table_name || \"#{cte_table.name}\".\"#{primary_key}\"::text), 1, 16))::bit(64)::bigint)", { table_name: table_name }])))
+                  .where(Arel.sql(sanitize_sql_for_conditions(["pg_try_advisory_lock(('x' || substr(md5(:table_name || #{connection.quote_table_name(cte_table.name)}.#{quoted_primary_key}::text), 1, 16))::bit(64)::bigint)", { table_name: table_name }])))
 
         limit = original_query.arel.ast.limit
         query.limit = limit.value if limit.present?
 
-        unscoped.where(arel_table[:id].in(query)).merge(original_query.only(:order))
+        unscoped.where(arel_table[primary_key].in(query)).merge(original_query.only(:order))
       end)
 
+      # Joins the current query with Postgres's +pg_locks+ table (it provides
+      # data about existing locks) such that each row in the main query joins
+      # to all the advisory locks associated with that row.
+      #
+      # For details on +pg_locks+, see
+      # {https://www.postgresql.org/docs/current/view-pg-locks.html}.
+      # @!method joins_advisory_locks
+      # @!scope class
+      # @return [ActiveRecord::Relation]
+      # @example Get the records that have a session awaiting a lock:
+      #   MyLockableRecord.joins_advisory_locks.where("pg_locks.granted = ?", false)
       scope :joins_advisory_locks, (lambda do
         join_sql = <<~SQL
           LEFT JOIN pg_locks ON pg_locks.locktype = 'advisory'
             AND pg_locks.objsubid = 1
-            AND pg_locks.classid = ('x'||substr(md5(:table_name || #{quoted_table_name}.#{quoted_primary_key}::text), 1, 16))::bit(32)::int
-            AND pg_locks.objid = (('x'||substr(md5(:table_name || #{quoted_table_name}.#{quoted_primary_key}::text), 1, 16))::bit(64) << 32)::bit(32)::int
+            AND pg_locks.classid = ('x' || substr(md5(:table_name || #{quoted_table_name}.#{quoted_primary_key}::text), 1, 16))::bit(32)::int
+            AND pg_locks.objid = (('x' || substr(md5(:table_name || #{quoted_table_name}.#{quoted_primary_key}::text), 1, 16))::bit(64) << 32)::bit(32)::int
         SQL
 
         joins(sanitize_sql_for_conditions([join_sql, { table_name: table_name }]))
       end)
 
+      # Find records that do not have an advisory lock on them.
+      # @!method advisory_unlocked
+      # @!scope class
+      # @return [ActiveRecord::Relation]
       scope :advisory_unlocked, -> { joins_advisory_locks.where(pg_locks: { locktype: nil }) }
+
+      # Find records that have an advisory lock on them.
+      # @!method advisory_locked
+      # @!scope class
+      # @return [ActiveRecord::Relation]
       scope :advisory_locked, -> { joins_advisory_locks.where.not(pg_locks: { locktype: nil }) }
+
+      # Find records with advisory locks owned by the current Postgres
+      # session/connection.
+      # @!method advisory_locked
+      # @!scope class
+      # @return [ActiveRecord::Relation]
       scope :owns_advisory_locked, -> { joins_advisory_locks.where('"pg_locks"."pid" = pg_backend_pid()') }
 
+      # @!attribute [r] create_with_advisory_lock
+      # @return [Boolean]
+      # Whether an advisory lock should be acquired in the same transaction
+      # that created the record.
+      #
+      # This helps prevent another thread or database session from acquiring a
+      # lock on the record between the time you create it and the time you
+      # request a lock, since other sessions will not be able to see the new
+      # record until the transaction that creates it is completed (at which
+      # point you have already acquired the lock).
+      #
+      # @example
+      #   record = MyLockableRecord.create(create_with_advisory_lock: true)
+      #   record.advisory_locked?
+      #   => true
       attr_accessor :create_with_advisory_lock
 
       after_create -> { advisory_lock }, if: :create_with_advisory_lock
     end
 
     class_methods do
+      # Acquires an advisory lock on the selected record(s) and safely releases
+      # it after the passed block is completed. The block will be passed an
+      # array of the locked records as its first argument.
+      #
+      # Note that this will not block and wait for locks to be acquired.
+      # Instead, it will acquire a lock on all the selected records that it
+      # can (as in {Lockable.advisory_lock}) and only pass those that could be
+      # locked to the block.
+      #
+      # @yield [Array<Lockable>] the records that were successfully locked.
+      # @return [Object] the result of the block.
+      #
+      # @example Work on the first two +MyLockableRecord+ objects that could be locked:
+      #   MyLockableRecord.order(created_at: :asc).limit(2).with_advisory_lock do |record|
+      #     do_something_with record
+      #   end
       def with_advisory_lock
         raise ArgumentError, "Must provide a block" unless block_given?
 
@@ -54,25 +134,51 @@ module GoodJob
       end
     end
 
+    # Acquires an advisory lock on this record if it is not already locked by
+    # another database session. Be careful to ensure you release the lock when
+    # you are done with {#advisory_unlock} (or {#advisory_unlock!} to release
+    # all remaining locks).
+    # @return [Boolean] whether the lock was acquired.
     def advisory_lock
       where_sql = <<~SQL
-        pg_try_advisory_lock(('x'||substr(md5(:table_name || :id::text), 1, 16))::bit(64)::bigint)
+        pg_try_advisory_lock(('x' || substr(md5(:table_name || :id::text), 1, 16))::bit(64)::bigint)
       SQL
       self.class.unscoped.where(where_sql, { table_name: self.class.table_name, id: send(self.class.primary_key) }).exists?
     end
 
+    # Releases an advisory lock on this record if it is locked by this database
+    # session. Note that advisory locks stack, so you must call
+    # {#advisory_unlock} and {#advisory_lock} the same number of times.
+    # @return [Boolean] whether the lock was released.
     def advisory_unlock
       where_sql = <<~SQL
-        pg_advisory_unlock(('x'||substr(md5(:table_name || :id::text), 1, 16))::bit(64)::bigint)
+        pg_advisory_unlock(('x' || substr(md5(:table_name || :id::text), 1, 16))::bit(64)::bigint)
       SQL
       self.class.unscoped.where(where_sql, { table_name: self.class.table_name, id: send(self.class.primary_key) }).exists?
     end
 
+    # Acquires an advisory lock on this record or raises
+    # {RecordAlreadyAdvisoryLockedError} if it is already locked by another
+    # database session.
+    # @raise [RecordAlreadyAdvisoryLockedError]
+    # @return [Boolean] +true+
     def advisory_lock!
       result = advisory_lock
       result || raise(RecordAlreadyAdvisoryLockedError)
     end
 
+    # Acquires an advisory lock on this record and safely releases it after the
+    # passed block is completed. If the record is locked by another database
+    # session, this raises {RecordAlreadyAdvisoryLockedError}.
+    #
+    # @yield Nothing
+    # @return [Object] The result of the block.
+    #
+    # @example
+    #   record = MyLockableRecord.first
+    #   record.with_advisory_lock do
+    #     do_something_with record
+    #   end
     def with_advisory_lock
       raise ArgumentError, "Must provide a block" unless block_given?
 
@@ -82,14 +188,21 @@ module GoodJob
       advisory_unlock unless $ERROR_INFO.is_a? RecordAlreadyAdvisoryLockedError
     end
 
+    # Tests whether this record has an advisory lock on it.
+    # @return [Boolean]
     def advisory_locked?
       self.class.unscoped.advisory_locked.where(id: send(self.class.primary_key)).exists?
     end
 
+    # Tests whether this record is locked by the current database session.
+    # @return [Boolean]
     def owns_advisory_lock?
       self.class.unscoped.owns_advisory_locked.where(id: send(self.class.primary_key)).exists?
     end
 
+    # Releases all advisory locks on the record that are held by the current
+    # database session.
+    # @return [void]
     def advisory_unlock!
       advisory_unlock while advisory_locked?
     end

data/lib/good_job/log_subscriber.rb

@@ -1,6 +1,22 @@
 module GoodJob
+  #
+  # Listens to GoodJob notifications and logs them.
+  #
+  # Each method corresponds to the name of a notification. For example, when
+  # the {Scheduler} shuts down, it sends a notification named
+  # +"scheduler_shutdown.good_job"+ and the {#scheduler_shutdown} method will
+  # be called here. See the
+  # {https://api.rubyonrails.org/classes/ActiveSupport/LogSubscriber.html ActiveSupport::LogSubscriber}
+  # documentation for more.
+  #
   class LogSubscriber < ActiveSupport::LogSubscriber
+    # @!group Notifications
+
+    # @!macro notification_responder
+    #   Responds to the +$0.good_job+ notification.
+    #   @return [void]
     def create(event)
+      # FIXME: This method does not match any good_job notifications.
       good_job = event.payload[:good_job]
 
       debug do
@@ -8,7 +24,9 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def timer_task_finished(event)
+      # FIXME: This method does not match any good_job notifications.
       exception = event.payload[:error]
       return unless exception
 
@@ -17,7 +35,9 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def job_finished(event)
+      # FIXME: This method does not match any good_job notifications.
       exception = event.payload[:error]
       return unless exception
 
@@ -26,6 +46,7 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def scheduler_create_pools(event)
       max_threads = event.payload[:max_threads]
       poll_interval = event.payload[:poll_interval]
@@ -37,6 +58,7 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def scheduler_shutdown_start(event)
       process_id = event.payload[:process_id]
 
@@ -45,6 +67,7 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def scheduler_shutdown(event)
       process_id = event.payload[:process_id]
 
@@ -53,6 +76,7 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def scheduler_restart_pools(event)
       process_id = event.payload[:process_id]
 
@@ -61,6 +85,7 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def perform_job(event)
       good_job = event.payload[:good_job]
       process_id = event.payload[:process_id]
@@ -71,12 +96,14 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def notifier_listen(_event)
       info do
         "Notifier subscribed with LISTEN"
       end
     end
 
+    # @macro notification_responder
     def notifier_notified(event)
       payload = event.payload[:payload]
 
@@ -85,6 +112,7 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def notifier_notify_error(event)
       error = event.payload[:error]
 
@@ -93,12 +121,14 @@ module GoodJob
       end
     end
 
+    # @macro notification_responder
     def notifier_unlisten(_event)
       info do
         "Notifier unsubscribed with UNLISTEN"
       end
     end
 
+    # @macro notification_responder
     def cleanup_preserved_jobs(event)
       timestamp = event.payload[:timestamp]
       deleted_records_count = event.payload[:deleted_records_count]
@@ -108,11 +138,34 @@ module GoodJob
       end
     end
 
+    # @!endgroup
+
+    # Get the logger associated with this {LogSubscriber} instance.
+    # @return [Logger]
+    def logger
+      GoodJob::LogSubscriber.logger
+    end
+
     class << self
+      # Tracks all loggers that {LogSubscriber} is writing to. You can write to
+      # multiple logs by appending to this array. After updating it, you should
+      # usually call {LogSubscriber.reset_logger} to make sure they are all
+      # written to.
+      #
+      # Defaults to {GoodJob.logger}.
+      # @return [Array<Logger>]
+      # @example Write to STDOUT and to a file:
+      #   GoodJob::LogSubscriber.loggers << ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new(STDOUT))
+      #   GoodJob::LogSubscriber.loggers << ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new("log/my_logs.log"))
+      #   GoodJob::LogSubscriber.reset_logger
       def loggers
         @_loggers ||= [GoodJob.logger]
       end
 
+      # Represents all the loggers attached to {LogSubscriber} with a single
+      # logging interface. Writing to this logger is a shortcut for writing to
+      # each of the loggers in {LogSubscriber.loggers}.
+      # @return [Logger]
       def logger
         @_logger ||= begin
                       logger = Logger.new(StringIO.new)
@@ -123,17 +176,22 @@ module GoodJob
                     end
       end
 
+      # Reset {LogSubscriber.logger} and force it to rebuild a new shortcut to
+      # all the loggers in {LogSubscriber.loggers}. You should usually call
+      # this after modifying the {LogSubscriber.loggers} array.
+      # @return [void]
       def reset_logger
         @_logger = nil
       end
     end
 
-    def logger
-      GoodJob::LogSubscriber.logger
-    end
-
     private
 
+    # Add "GoodJob" plus any specified tags to every
+    # {ActiveSupport::TaggedLogging} logger in {LogSubscriber.loggers}. Tags
+    # are only applicable inside the block passed to this method.
+    # @yield [void]
+    # @return [void]
     def tag_logger(*tags, &block)
       tags = tags.dup.unshift("GoodJob").compact
 
@@ -152,6 +210,14 @@ module GoodJob
       end.call
     end
 
+    # Ensure that the standard logging methods include "GoodJob" as a tag and
+    # that they include a second argument allowing callers to specify ad-hoc
+    # tags to include in the message.
+    #
+    # For example, to include the tag "ForFunsies" on an +info+ message:
+    #
+    #     self.info("Some message", tags: ["ForFunsies"])
+    #
     %w(info debug warn error fatal unknown).each do |level|
       class_eval <<-METHOD, __FILE__, __LINE__ + 1
         def #{level}(progname = nil, tags: [], &block)

data/lib/good_job/multi_scheduler.rb

@@ -1,23 +1,29 @@
 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|

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,13 +21,17 @@ 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
@@ -29,8 +39,11 @@ module GoodJob # :nodoc:
       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 jobs 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