que 0.2.0 → 0.3.0

data/lib/que/version.rb

@@ -1,3 +1,3 @@
 module Que
-  Version = '0.2.0'
+  Version = '0.3.0'
 end

data/lib/que/worker.rb

@@ -4,74 +4,39 @@ module Que
   class Worker
     # Each worker has a thread that does the actual work of running jobs.
     # Since both the worker's thread and whatever thread is managing the
-    # worker are capable of affecting the state of the worker's thread, we
-    # need to synchronize access to it.
-
+    # worker are capable of affecting the worker's state, we need to
+    # synchronize access to it.
     include MonitorMixin
 
-    attr_reader :thread
+    # A custom exception to immediately kill a worker and its current job.
+    class Stop < Interrupt; end
+
+    attr_reader :thread, :state
 
     def initialize
       super # For MonitorMixin.
+      @state  = :working
+      @thread = Thread.new { work_loop }
+    end
 
-      # We have to make sure the thread doesn't actually start the work loop
-      # until it has a state and directive already set up, so use a queue to
-      # temporarily block it.
-      q = Queue.new
-
-      @thread = Thread.new do
-        q.pop
-
-        loop do
-          job = Job.work
-
-          # Grab the lock and figure out what we should do next.
-          synchronize do
-            if @thread[:directive] == :stop
-              @thread[:state] = :stopping
-            elsif not job
-              # No work, go to sleep.
-              @thread[:state] = :sleeping
-            end
-          end
-
-          if @thread[:state] == :sleeping
-            sleep
-
-            # Now that we're woken up, grab the lock figure out if we're stopping.
-            synchronize do
-              @thread[:state] = :stopping if @thread[:directive] == :stop
-            end
-          end
-
-          break if @thread[:state] == :stopping
-        end
-      end
-
-      synchronize do
-        @thread[:directive] = :work
-        @thread[:state]     = :working
-      end
-
-      q.push :go!
+    def alive?
+      !!@thread.status
     end
 
     def sleeping?
       synchronize do
-        if @thread[:state] == :sleeping
+        if @state == :sleeping
           # There's a very small period of time between when the Worker marks
           # itself as sleeping and when it actually goes to sleep. Only report
           # true when we're certain the thread is sleeping.
-          sleep 0.0001 until @thread.status == 'sleep'
+          wait until @thread.status == 'sleep'
           true
         end
       end
     end
 
     def working?
-      synchronize do
-        @thread[:state] == :working
-      end
+      synchronize { @state == :working }
     end
 
     def wake!
@@ -79,30 +44,56 @@ module Que
         if sleeping?
           # Have to set the state here so that another thread checking
           # immediately after this won't see the worker as asleep.
-          @thread[:state] = :working
+          @state = :working
           @thread.wakeup
           true
         end
       end
     end
 
-    # This has to be called when trapping a SIGTERM, so it can't lock the monitor.
+    # #stop informs the worker that it should shut down after its next job,
+    # while #stop! kills the job and worker immediately. #stop! is bad news
+    # because its results are unpredictable (it can leave the DB connection
+    # in an unusable state), so it should only be used when we're shutting
+    # down the whole process anyway and side effects aren't a big deal.
+    def stop
+      synchronize do
+        @stop = true
+        @thread.wakeup if sleeping?
+      end
+    end
+
     def stop!
-      @thread[:directive] = :stop
+      @thread.raise Stop
     end
 
     def wait_until_stopped
-      loop do
-        case @thread.status
-          when false then break
-          when 'sleep' then @thread.wakeup
-        end
-        sleep 0.0001
-      end
+      wait while alive?
     end
 
     private
 
+    # Sleep very briefly while waiting for a thread to get somewhere.
+    def wait
+      sleep 0.0001
+    end
+
+    def work_loop
+      loop do
+        job = Job.work
+
+        # Grab the lock and figure out what we should do next.
+        synchronize { @state = :sleeping unless @stop || job }
+
+        sleep if @state == :sleeping
+        break if @stop
+      end
+    rescue Stop
+      # This process is shutting down; let it.
+    ensure
+      @state = :stopped
+    end
+
     # Defaults for the Worker pool.
     @worker_count = 0
     @sleep_period = 5
@@ -131,7 +122,7 @@ module Que
         if count > workers.count
           (count - workers.count).times { workers << new }
         elsif count < workers.count
-          workers.pop(workers.count - count).each(&:stop!).each(&:wait_until_stopped)
+          workers.pop(workers.count - count).each(&:stop).each(&:wait_until_stopped)
         end
       end
 
@@ -140,6 +131,19 @@ module Que
         wrangler.wakeup if period
       end
 
+      def stop!
+        # The behavior of Worker#stop! is unpredictable - what it does is
+        # dependent on what the Worker is currently doing. Sometimes it won't
+        # work the first time, so we need to try again, but sometimes it'll
+        # never do anything, so we can't repeat indefinitely. So, compromise.
+        5.times do
+          break if workers.select(&:alive?).each(&:stop!).none?
+          sleep 0.001
+        end
+
+        workers.clear
+      end
+
       def wake!
         workers.find &:wake!
       end

data/spec/adapters/active_record_spec.rb

@@ -1,39 +1,67 @@
-require 'spec_helper'
-require 'active_record'
+# Don't run these specs in JRuby until jruby-pg is compatible with ActiveRecord.
+unless defined?(RUBY_ENGINE) && RUBY_ENGINE == 'jruby'
 
-ActiveRecord::Base.establish_connection(QUE_URL)
-Que.connection = ActiveRecord
-QUE_ADAPTERS[:active_record] = Que.adapter
+  require 'spec_helper'
+  require 'active_record'
 
-describe "Que using the ActiveRecord adapter" do
-  before { Que.adapter = QUE_ADAPTERS[:active_record] }
+  ActiveRecord::Base.establish_connection(QUE_URL)
+  Que.connection = ActiveRecord
+  QUE_ADAPTERS[:active_record] = Que.adapter
 
-  it_behaves_like "a Que adapter"
-  it_behaves_like "a multithreaded Que adapter"
+  describe "Que using the ActiveRecord adapter" do
+    before { Que.adapter = QUE_ADAPTERS[:active_record] }
 
-  it "should use the same connection that ActiveRecord does" do
-    class ActiveRecordJob < Que::Job
-      def run
-        $pid1 = Que.execute("SELECT pg_backend_pid()").first['pg_backend_pid'].to_i
-        $pid2 = ActiveRecord::Base.connection.select_all("select pg_backend_pid()").rows.first.first.to_i
+    it_behaves_like "a Que adapter"
+    it_behaves_like "a multithreaded Que adapter"
+
+    it "should use the same connection that ActiveRecord does" do
+      class ActiveRecordJob < Que::Job
+        def run
+          $pid1 = Que.execute("SELECT pg_backend_pid()").first['pg_backend_pid'].to_i
+          $pid2 = ActiveRecord::Base.connection.select_all("select pg_backend_pid()").rows.first.first.to_i
+        end
       end
+
+      ActiveRecordJob.queue
+      Que::Job.work
+
+      $pid1.should == $pid2
     end
 
-    ActiveRecordJob.queue
-    Que::Job.work
+    it "should instantiate args as ActiveSupport::HashWithIndifferentAccess" do
+      ArgsJob.queue :param => 2
+      Que::Job.work
+      $passed_args.first[:param].should == 2
+      $passed_args.first.should be_an_instance_of ActiveSupport::HashWithIndifferentAccess
+    end
 
-    $pid1.should == $pid2
-  end
+    it "should support Rails' special extensions for times" do
+      Que::Job.queue :run_at => 1.minute.from_now
+      DB[:que_jobs].get(:run_at).should be_within(3).of Time.now + 60
+    end
 
-  it "should instantiate args as ActiveSupport::HashWithIndifferentAccess" do
-    ArgsJob.queue :param => 2
-    Que::Job.work
-    $passed_args.first[:param].should == 2
-    $passed_args.first.should be_an_instance_of ActiveSupport::HashWithIndifferentAccess
-  end
+    it "should safely roll back in-process transactions when using Que.stop!" do
+      begin
+        class ARInterruptJob < BlockJob
+          def run
+            ActiveRecord::Base.transaction do
+              Que.execute "INSERT INTO que_jobs (job_id, job_class) VALUES (0, 'Que::Job')"
+              super
+            end
+          end
+        end
+
+        ARInterruptJob.queue
+        Que.mode = :async
+        $q1.pop
+        Que.stop!
 
-  it "should support Rails' special extensions for times" do
-    Que::Job.queue :run_at => 1.minute.from_now
-    DB[:que_jobs].get(:run_at).should be_within(3).of Time.now + 60
+        DB[:que_jobs].where(:job_id => 0).should be_empty
+      ensure
+        # Que.stop! can affect DB connections in an unpredictable fashion, so
+        # force a reconnection for the sake of the other specs.
+        ActiveRecord::Base.establish_connection(QUE_URL)
+      end
+    end
   end
 end

data/spec/adapters/sequel_spec.rb

@@ -22,4 +22,34 @@ describe "Que using the Sequel adapter" do
 
     $pid1.should == $pid2
   end
+
+  it "should safely roll back in-process transactions when using Que.stop!" do
+    begin
+      class SequelInterruptJob < BlockJob
+        def run
+          SEQUEL_ADAPTER_DB.transaction do
+            Que.execute "INSERT INTO que_jobs (job_id, job_class) VALUES (0, 'Que::Job')"
+            super
+          end
+        end
+      end
+
+      SequelInterruptJob.queue
+      Que.mode = :async
+      $q1.pop
+      Que.stop!
+
+      DB[:que_jobs].where(:job_id => 0).should be_empty
+    ensure
+      # Que.stop! can affect DB connections in an unpredictable fashion, and
+      # Sequel's built-in reconnection logic may not be able to recover them.
+      # So, force a reconnection for the sake of the other specs...
+      SEQUEL_ADAPTER_DB.disconnect
+
+      # ...and that's not even foolproof, because threads may have died with
+      # connections checked out.
+      SEQUEL_ADAPTER_DB.pool.allocated.each_value(&:close)
+      SEQUEL_ADAPTER_DB.pool.allocated.clear
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -1,15 +1,14 @@
 require 'que'
+require 'uri'
+require 'pg'
 require 'json'
 
-Dir["./spec/support/**/*.rb"].sort.each &method(:require)
-
-QUE_URL = ENV["DATABASE_URL"] || "postgres://postgres:@localhost/que-test"
+Dir['./spec/support/**/*.rb'].sort.each &method(:require)
 
 
+# Handy constants for initializing PG connections:
+QUE_URL = ENV['DATABASE_URL'] || 'postgres://postgres:@localhost/que-test'
 
-# Handy proc to instantiate new PG connections:
-require 'uri'
-require 'pg'
 NEW_PG_CONNECTION = proc do
   uri = URI.parse(QUE_URL)
   PG::Connection.open :host     => uri.host,
@@ -20,12 +19,11 @@ NEW_PG_CONNECTION = proc do
 end
 
 
-
-# Adapters track information about their connections like which statements
-# have been prepared, and if Que.connection= is called before each spec, we're
-# constantly creating new adapters and losing that information, which is bad.
-# So instead, we hang onto a few adapters and assign them using Que.adapter=
-# as needed. The plain pg adapter is the default.
+# Adapters track which statements have been prepared for their connections,
+# and if Que.connection= is called before each spec, we're constantly creating
+# new adapters and losing that information, which is bad. So instead, we hang
+# onto a few adapters and assign them using Que.adapter= as needed. The plain
+# pg adapter is the default.
 
 # Also, let Que initialize the adapter itself, to make sure that the
 # recognition logic works. Similar code can be found in the adapter specs.
@@ -33,13 +31,26 @@ Que.connection = NEW_PG_CONNECTION.call
 QUE_ADAPTERS = {:pg => Que.adapter}
 
 
-
 # We use Sequel to introspect the database in specs.
 require 'sequel'
 DB = Sequel.connect(QUE_URL)
 DB.drop_table? :que_jobs
 DB.run Que::SQL[:create_table]
 
+
+# Set up a dummy logger.
+Que.logger = $logger = Object.new
+
+def $logger.messages
+  @messages ||= []
+end
+
+def $logger.method_missing(m, message)
+  messages << message
+end
+
+
+# Clean up between specs.
 RSpec.configure do |config|
   config.before do
     DB[:que_jobs].delete
@@ -51,8 +62,28 @@ RSpec.configure do |config|
 end
 
 
+# Optionally log to STDOUT which spec is running at the moment. This is loud,
+# but helpful in tracking down what spec is hanging, if any.
+if ENV['LOG_SPEC']
+  require 'logger'
+  logger = Logger.new(STDOUT)
 
-# Set up a dummy logger.
-Que.logger = $logger = Object.new
-def $logger.messages;                   @messages ||= [];    end
-def $logger.method_missing(m, message); messages << message; end
+  description_builder = -> hash do
+    if g = hash[:example_group]
+      "#{description_builder.call(g)} #{hash[:description_args].first}"
+    else
+      hash[:description_args].first
+    end
+  end
+
+  RSpec.configure do |config|
+    config.around do |example|
+      data = example.metadata
+      desc = description_builder.call(data)
+      line = "rspec #{data[:file_path]}:#{data[:line_number]}"
+      logger.info "Running spec: #{desc} @ #{line}"
+
+      example.run
+    end
+  end
+end

data/spec/unit/pool_spec.rb

@@ -6,6 +6,11 @@ describe "Managing the Worker pool" do
     $logger.messages.should == ["[Que] Set mode to :off"]
   end
 
+  it "Que.stop! should do nothing if there are no workers running" do
+    Que::Worker.workers.should be_empty
+    Que.stop!
+  end
+
   describe "Que.mode = :sync" do
     it "should make jobs run in the same thread as they are queued" do
       Que.mode = :sync
@@ -25,6 +30,11 @@ describe "Managing the Worker pool" do
       ArgsJob.queue(5, :testing => "synchronous", :run_at => Time.now + 60)
       DB[:que_jobs].select_map(:job_class).should == ["ArgsJob"]
     end
+
+    it "then Que.stop! should do nothing" do
+      Que::Worker.workers.should be_empty
+      Que.stop!
+    end
   end
 
   describe "Que.mode = :async" do
@@ -122,5 +132,21 @@ describe "Managing the Worker pool" do
         Que.sleep_period = nil
       end
     end
+
+    it "then Que.stop! should interrupt all running jobs" do
+      begin
+        # Que.stop! can unpredictably affect connections, which may affect
+        # other tests, so use a new one.
+        pg = NEW_PG_CONNECTION.call
+        Que.connection = pg
+
+        BlockJob.queue
+        Que.mode = :async
+        $q1.pop
+        Que.stop!
+      ensure
+        pg.close if pg
+      end
+    end
   end
 end