que 0.14.3 → 1.0.0.beta

data/lib/que/job.rb

@@ -1,11 +1,36 @@
 # frozen_string_literal: true
 
+# The class that jobs should generally inherit from.
+
 module Que
   class Job
-    attr_reader :attrs, :_error
+    include JobMethods
+
+    MAXIMUM_TAGS_COUNT = 5
+    MAXIMUM_TAG_LENGTH = 100
+
+    SQL[:insert_job] =
+      %{
+        INSERT INTO public.que_jobs
+        (queue, priority, run_at, job_class, args, data)
+        VALUES
+        (
+          coalesce($1, 'default')::text,
+          coalesce($2, 100)::smallint,
+          coalesce($3, now())::timestamptz,
+          $4::text,
+          coalesce($5, '[]')::jsonb,
+          coalesce($6, '{}')::jsonb
+        )
+        RETURNING *
+      }
+
+    attr_reader :que_attrs
+    attr_accessor :que_error, :que_resolved
 
     def initialize(attrs)
-      @attrs = attrs
+      @que_attrs = attrs
+      Que.internal_log(:job_instantiate, self) { attrs }
     end
 
     # Subclasses should define their own run methods, but keep an empty one
@@ -13,185 +38,111 @@ module Que
     def run(*args)
     end
 
-    def _run
-      run(*attrs[:args])
-      destroy unless @destroyed
-    rescue => error
-      @_error = error
-      run_error_notifier = handle_error(error)
-      destroy unless @retried || @destroyed
-
-      if run_error_notifier && Que.error_notifier
-        # Protect the work loop from a failure of the error notifier.
-        Que.error_notifier.call(error, @attrs) rescue nil
-      end
-    end
-
     private
 
-    def error_count
-      @attrs[:error_count]
-    end
-
-    def error_message
-      self.class.send(:error_message, @_error)
-    end
-
-    def handle_error(error)
-      error_count = @attrs[:error_count] += 1
-      retry_interval = self.class.retry_interval || Job.retry_interval
-      wait = retry_interval.respond_to?(:call) ? retry_interval.call(error_count) : retry_interval
-      retry_in(wait)
-    end
-
-    def retry_in(period)
-      Que.execute :set_error, [period, error_message] + @attrs.values_at(:queue, :priority, :run_at, :job_id)
-      @retried = true
+    # Have the job helper methods act on this object.
+    def que_target
+      self
     end
 
-    def destroy
-      Que.execute :destroy_job, attrs.values_at(:queue, :priority, :run_at, :job_id)
-      @destroyed = true
-    end
-
-    @retry_interval = proc { |count| count ** 4 + 3 }
-
     class << self
-      attr_reader :retry_interval
-
-      def enqueue(*args)
-        if args.last.is_a?(Hash)
-          options   = args.pop
-          queue     = options.delete(:queue) || '' if options.key?(:queue)
-          job_class = options.delete(:job_class)
-          run_at    = options.delete(:run_at)
-          priority  = options.delete(:priority)
-          args << options if options.any?
-        end
-
-        attrs = {:job_class => job_class || to_s, :args => args}
-
-        warn "@default_run_at in #{to_s} has been deprecated and will be removed in Que version 1.0.0. Please use @run_at instead." if @default_run_at
-
-        if t = run_at || @run_at && @run_at.call || @default_run_at && @default_run_at.call
-          attrs[:run_at] = t
-        end
-
-        warn "@default_priority in #{to_s} has been deprecated and will be removed in Que version 1.0.0. Please use @priority instead." if @default_priority
-
-        if p = priority || @priority || @default_priority
-          attrs[:priority] = p
-        end
+      # Job class configuration options.
+      attr_accessor \
+        :run_synchronously,
+        :retry_interval,
+        :maximum_retry_count,
+        :queue,
+        :priority,
+        :run_at
+
+      def enqueue(
+        *args,
+        queue:     nil,
+        priority:  nil,
+        run_at:    nil,
+        job_class: nil,
+        tags:      nil,
+        **arg_opts
+      )
+
+        args << arg_opts if arg_opts.any?
+
+        if tags
+          if tags.length > MAXIMUM_TAGS_COUNT
+            raise Que::Error, "Can't enqueue a job with more than #{MAXIMUM_TAGS_COUNT} tags! (passed #{tags.length})"
+          end
 
-        if q = queue || @queue
-          attrs[:queue] = q
+          tags.each do |tag|
+            if tag.length > MAXIMUM_TAG_LENGTH
+              raise Que::Error, "Can't enqueue a job with a tag longer than 100 characters! (\"#{tag}\")"
+            end
+          end
         end
 
-        if Que.mode == :sync && !t
-          run(*attrs[:args])
+        attrs = {
+          queue:    queue    || resolve_que_setting(:queue) || Que.default_queue,
+          priority: priority || resolve_que_setting(:priority),
+          run_at:   run_at   || resolve_que_setting(:run_at),
+          args:     Que.serialize_json(args),
+          data:     tags ? Que.serialize_json(tags: tags) : "{}",
+          job_class: \
+            job_class || name ||
+              raise(Error, "Can't enqueue an anonymous subclass of Que::Job"),
+        }
+
+        if attrs[:run_at].nil? && resolve_que_setting(:run_synchronously)
+          attrs[:args] = Que.deserialize_json(attrs[:args])
+          attrs[:data] = Que.deserialize_json(attrs[:data])
+          _run_attrs(attrs)
         else
-          values = Que.execute(:insert_job, attrs.values_at(:queue, :priority, :run_at, :job_class, :args)).first
-          Que.adapter.wake_worker_after_commit unless t
+          values =
+            Que.execute(
+              :insert_job,
+              attrs.values_at(:queue, :priority, :run_at, :job_class, :args, :data),
+            ).first
+
           new(values)
         end
       end
 
-      def queue(*args)
-        warn "#{to_s}.queue(*args) is deprecated and will be removed in Que version 1.0.0. Please use #{to_s}.enqueue(*args) instead."
-        enqueue(*args)
-      end
-
       def run(*args)
+        # Make sure things behave the same as they would have with a round-trip
+        # to the DB.
+        args = Que.deserialize_json(Que.serialize_json(args))
+
         # Should not fail if there's no DB connection.
-        new(:args => args).tap { |job| job.run(*args) }
+        _run_attrs(args: args)
       end
 
-      def work(queue = '')
-        # Since we're taking session-level advisory locks, we have to hold the
-        # same connection throughout the process of getting a job, working it,
-        # deleting it, and removing the lock.
-        return_value =
-          Que.adapter.checkout do
-            begin
-              if job = Que.execute(:lock_job, [queue]).first
-                # Edge case: It's possible for the lock_job query to have
-                # grabbed a job that's already been worked, if it took its MVCC
-                # snapshot while the job was processing, but didn't attempt the
-                # advisory lock until it was finished. Since we have the lock, a
-                # previous worker would have deleted it by now, so we just
-                # double check that it still exists before working it.
-
-                # Note that there is currently no spec for this behavior, since
-                # I'm not sure how to reliably commit a transaction that deletes
-                # the job in a separate thread between lock_job and check_job.
-                if Que.execute(:check_job, job.values_at(:queue, :priority, :run_at, :job_id)).none?
-                  {:event => :job_race_condition}
-                else
-                  klass = class_for(job[:job_class])
-                  instance = klass.new(job)
-                  instance._run
-                  if e = instance._error
-                    {:event => :job_errored, :job => job, :error => e}
-                  else
-                    {:event => :job_worked, :job => job}
-                  end
-                end
-              else
-                {:event => :job_unavailable}
-              end
-            rescue => error
-              begin
-                if job
-                  count    = job[:error_count].to_i + 1
-                  interval = klass && klass.respond_to?(:retry_interval) && klass.retry_interval || retry_interval
-                  delay    = interval.respond_to?(:call) ? interval.call(count) : interval
-                  message  = error_message(error)
-                  Que.execute :set_error, [delay, message] + job.values_at(:queue, :priority, :run_at, :job_id)
-                end
-              rescue
-                # If we can't reach the database for some reason, too bad, but
-                # don't let it crash the work loop.
-              end
-
-              if Que.error_notifier
-                # Similarly, protect the work loop from a failure of the error notifier.
-                Que.error_notifier.call(error, job) rescue nil
-              end
-
-              return {:event => :job_errored, :error => error, :job => job}
-            ensure
-              # Clear the advisory lock we took when locking the job. Important
-              # to do this so that they don't pile up in the database. Again, if
-              # we can't reach the database, don't crash the work loop.
-              begin
-                Que.execute "SELECT pg_advisory_unlock($1)", [job[:job_id]] if job
-              rescue
-              end
-            end
-          end
-
-        Que.adapter.cleanup!
+      def resolve_que_setting(setting, *args)
+        value = send(setting) if respond_to?(setting)
 
-        return_value
+        if !value.nil?
+          value.respond_to?(:call) ? value.call(*args) : value
+        else
+          c = superclass
+          if c.respond_to?(:resolve_que_setting)
+            c.resolve_que_setting(setting, *args)
+          end
+        end
       end
 
       private
 
-      def error_message(error)
-        message = error.class.to_s
+      def _run_attrs(attrs)
+        attrs[:error_count] = 0
+        Que.recursively_freeze(attrs)
 
-        unless error.message.nil? || error.message.strip.empty?
-          message << ": #{error.message}"
+        new(attrs).tap do |job|
+          Que.run_middleware(job) do
+            job._run(reraise_errors: true)
+          end
         end
-
-        message = message.slice(0, 500)
-
-        ([message] + error.backtrace).join("\n")
-      end
-
-      def class_for(string)
-        Que.constantize(string)
       end
     end
+
+    # Set up some defaults.
+    self.retry_interval      = proc { |count| count ** 4 + 3 }
+    self.maximum_retry_count = 15
   end
 end

data/lib/que/job_cache.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+# A sized thread-safe queue that holds ordered job sort_keys. Supports blocking
+# while waiting for a job to become available, only returning jobs over a
+# minimum priority, and stopping gracefully.
+
+module Que
+  class JobCache
+    attr_reader :maximum_size, :minimum_size, :priority_queues
+
+    def initialize(
+      maximum_size:,
+      minimum_size:,
+      priorities:
+    )
+      @maximum_size = Que.assert(Integer, maximum_size)
+      Que.assert(maximum_size >= 0) { "maximum_size for a JobCache must be at least zero!" }
+
+      @minimum_size = Que.assert(Integer, minimum_size)
+      Que.assert(minimum_size >= 0) { "minimum_size for a JobCache must be at least zero!" }
+
+      Que.assert(minimum_size <= maximum_size) do
+        "minimum queue size (#{minimum_size}) is " \
+          "greater than the maximum queue size (#{maximum_size})!"
+      end
+
+      @stop    = false
+      @array   = []
+      @monitor = Monitor.new # TODO: Make this a mutex?
+
+      # Make sure that priority = nil sorts highest.
+      @priority_queues = Hash[
+        priorities.sort_by{|p| p || Float::INFINITY}.map do |p|
+          [p, PriorityQueue.new(priority: p, job_cache: self)]
+        end
+      ].freeze
+    end
+
+    def push(*metajobs)
+      Que.internal_log(:job_cache_push, self) do
+        {
+          maximum_size:  maximum_size,
+          ids:           metajobs.map(&:id),
+          current_queue: @array,
+        }
+      end
+
+      sync do
+        return metajobs if stopping?
+
+        @array.push(*metajobs).sort!
+
+        # Relying on the hash's contents being sorted, here.
+        priority_queues.reverse_each do |_, pq|
+          pq.waiting_count.times do
+            job = shift_job(pq.priority)
+            break if job.nil?
+            pq.push(job)
+          end
+        end
+
+        # If we passed the maximum queue size, drop the lowest sort keys and
+        # return their ids to be unlocked.
+        overage = -cache_space
+        pop(overage) if overage > 0
+      end
+    end
+
+    def shift(priority = nil)
+      queue = priority_queues.fetch(priority) { raise Error, "not a permitted priority! #{priority}" }
+      queue.pop
+    end
+
+    def shift_job(priority = nil)
+      sync do
+        if stopping?
+          false
+        elsif (job = @array.first) && job.priority_sufficient?(priority)
+          @array.shift
+        end
+      end
+    end
+
+    def accept?(metajobs)
+      return [] if stopping?
+
+      metajobs.sort!
+
+      sync do
+        start_index = cache_space
+        final_index = metajobs.length - 1
+
+        return metajobs if start_index > final_index
+        index_to_lose = @array.length - 1
+
+        start_index.upto(final_index) do |index|
+          if index_to_lose >= 0 && (metajobs[index] <=> @array[index_to_lose]) < 0
+            return metajobs if index == final_index
+            index_to_lose -= 1
+          else
+            return metajobs.slice(0...index)
+          end
+        end
+
+        []
+      end
+    end
+
+    def jobs_needed?
+      minimum_size > size
+    end
+
+    def waiting_count
+      count = 0
+      priority_queues.each_value do |pq|
+        count += pq.waiting_count
+      end
+      count
+    end
+
+    def available_priorities
+      hash = {}
+      lowest_priority = true
+
+      priority_queues.reverse_each do |priority, pq|
+        count = pq.waiting_count
+
+        if lowest_priority
+          count += cache_space
+          lowest_priority = false
+        end
+
+        hash[priority || MAXIMUM_PRIORITY] = count if count > 0
+      end
+
+      hash
+    end
+
+    def cache_space
+      sync do
+        maximum_size - size
+      end
+    end
+
+    def size
+      sync { @array.size }
+    end
+
+    def to_a
+      sync { @array.dup }
+    end
+
+    def stop
+      sync { @stop = true }
+      priority_queues.each_value(&:stop)
+    end
+
+    def clear
+      sync { pop(size) }
+    end
+
+    def stopping?
+      sync { !!@stop }
+    end
+
+    private
+
+    def pop(count)
+      @array.pop(count)
+    end
+
+    def sync
+      @monitor.synchronize { yield }
+    end
+
+    # A queue object dedicated to a specific worker priority. It's basically a
+    # Queue object from the standard library, but it's able to reach into the
+    # JobCache's cache in order to satisfy a pop.
+    class PriorityQueue
+      attr_reader :job_cache, :priority
+
+      def initialize(
+        job_cache:,
+        priority:
+      )
+        @job_cache = job_cache
+        @priority  = priority
+        @waiting   = 0
+        @stopping  = false
+        @items     = [] # Items pending distribution to waiting threads.
+        @monitor   = Monitor.new
+        @cv        = Monitor::ConditionVariable.new(@monitor)
+      end
+
+      def pop
+        sync do
+          loop do
+            return false if @stopping
+
+            if item = @items.pop
+              return item
+            end
+
+            job = job_cache.shift_job(priority)
+            return job unless job.nil? # False means we're stopping.
+
+            @waiting += 1
+            @cv.wait
+            @waiting -= 1
+          end
+        end
+      end
+
+      def push(item)
+        sync do
+          Que.assert(waiting_count > 0)
+          @items << item
+          @cv.signal
+        end
+      end
+
+      def stop
+        sync do
+          @stopping = true
+          @cv.broadcast
+        end
+      end
+
+      def waiting_count
+        @waiting
+      end
+
+      private
+
+      def sync
+        @monitor.synchronize { yield }
+      end
+    end
+  end
+end