que 0.3.0 → 0.4.0

data/spec/unit/queue_spec.rb

@@ -3,9 +3,13 @@ require 'spec_helper'
 describe Que::Job, '.queue' do
   it "should be able to queue a job" do
     DB[:que_jobs].count.should be 0
-    Que::Job.queue
+    result = Que::Job.queue
     DB[:que_jobs].count.should be 1
 
+    result.should be_an_instance_of Que::Job
+    result.attrs[:priority].should == '1'
+    result.attrs[:args].should == []
+
     job = DB[:que_jobs].first
     job[:priority].should be 1
     job[:run_at].should be_within(3).of Time.now

data/spec/unit/states_spec.rb

@@ -0,0 +1,52 @@
+require 'spec_helper'
+
+describe Que, '.worker_states' do
+  it "should return a list of the job types in the queue, their counts and the number of each currently running" do
+    Que.adapter = QUE_ADAPTERS[:connection_pool]
+
+    class WorkerStateJob < BlockJob
+      def run
+        $pid = Que.execute("select pg_backend_pid()").first['pg_backend_pid']
+        super
+      end
+    end
+
+    WorkerStateJob.queue :priority => 2
+
+    # Ensure that the portion of the SQL query that accounts for bigint
+    # job_ids functions correctly.
+    DB[:que_jobs].update(:job_id => 2**33)
+
+    begin
+      t = Thread.new { Que::Job.work }
+      $q1.pop
+
+      states = Que.worker_states
+      states.length.should be 1
+
+      state = states.first
+      state.keys.should == %w(priority run_at job_id job_class args error_count last_error pg_backend_pid pg_state pg_state_changed_at pg_last_query pg_last_query_started_at pg_transaction_started_at pg_waiting_on_lock)
+
+      state[:priority].should == '2'
+      Time.parse(state[:run_at]).should be_within(3).of Time.now
+      state[:job_id].should == (2**33).to_s
+      state[:job_class].should == 'WorkerStateJob'
+      state[:args].should == '[]'
+      state[:error_count].should == '0'
+      state[:last_error].should be nil
+
+      state[:pg_backend_pid].should == $pid.to_s
+      state[:pg_state].should == 'idle'
+      Time.parse(state[:pg_state_changed_at]).should be_within(3).of Time.now
+      state[:pg_last_query].should == 'select pg_backend_pid()'
+      Time.parse(state[:pg_last_query_started_at]).should be_within(3).of Time.now
+      state[:pg_transaction_started_at].should == nil
+      state[:pg_waiting_on_lock].should == 'f'
+    ensure
+      if t
+        t.kill
+        t.join
+      end
+    end
+  end if QUE_ADAPTERS[:connection_pool]
+end

data/spec/unit/stats_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+
+describe Que, '.job_stats' do
+  it "should return a list of the job types in the queue, their counts and the number of each currently running" do
+    BlockJob.queue
+    Que::Job.queue
+
+    # Have to tweak the job_id to ensure that the portion of the SQL query
+    # that accounts for bigint job_ids functions correctly.
+    old = Time.now - 3600
+    DB[:que_jobs].where(:job_class => "Que::Job").update(:job_id => 2**33, :error_count => 5, :run_at => old)
+
+    Que::Job.queue
+
+    begin
+      DB.get{pg_advisory_lock(2**33)}
+
+      stats = Que.job_stats
+      stats.length.should == 2
+
+      qj, bj = stats
+
+      qj.keys.should == %w(job_class count count_working count_errored highest_error_count oldest_run_at)
+
+      qj[:job_class].should == 'Que::Job'
+      qj[:count].should == '2'
+      qj[:count_working].should == '1'
+      qj[:count_errored].should == '1'
+      qj[:highest_error_count].should == '5'
+      Time.parse(qj[:oldest_run_at]).should be_within(3).of old
+
+      bj[:job_class].should == 'BlockJob'
+      bj[:count].should == '1'
+      bj[:count_working].should == '0'
+      bj[:count_errored].should == '0'
+      bj[:highest_error_count].should == '0'
+      Time.parse(bj[:oldest_run_at]).should be_within(3).of Time.now
+    ensure
+      DB.get{pg_advisory_unlock_all{}}
+    end
+  end
+end

data/spec/unit/work_spec.rb

@@ -7,9 +7,6 @@ describe Que::Job, '.work' do
     Que::Job.work.should be_an_instance_of ArgsJob
     DB[:que_jobs].count.should be 0
     $passed_args.should == [1, 'two', {'three' => 3}]
-
-    # Should clear advisory lock.
-    DB[:pg_locks].where(:locktype => 'advisory').should be_empty
   end
 
   it "should make a job's argument hashes indifferently accessible" do
@@ -20,14 +17,10 @@ describe Que::Job, '.work' do
     DB[:que_jobs].count.should be 0
 
     $passed_args.last[:array].first[:number].should == 3
-
-    # Should clear advisory lock.
-    DB[:pg_locks].where(:locktype => 'advisory').should be_empty
   end
 
   it "should not fail if there are no jobs to work" do
     Que::Job.work.should be nil
-    DB[:pg_locks].where(:locktype => 'advisory').should be_empty
   end
 
   it "should write messages to the logger" do
@@ -50,16 +43,15 @@ describe Que::Job, '.work' do
   end
 
   it "should prefer a job with a higher priority" do
-    Que::Job.queue :priority => 5
-    Que::Job.queue :priority => 1
-    Que::Job.queue :priority => 5
-    DB[:que_jobs].order(:job_id).select_map(:priority).should == [5, 1, 5]
+    # 1 is highest priority.
+    [5, 4, 3, 2, 1, 2, 3, 4, 5].map{|p| Que::Job.queue :priority => p}
+    DB[:que_jobs].order(:job_id).select_map(:priority).should == [5, 4, 3, 2, 1, 2, 3, 4, 5]
 
     Que::Job.work.should be_an_instance_of Que::Job
-    DB[:que_jobs].select_map(:priority).should == [5, 5]
+    DB[:que_jobs].select_map(:priority).should == [5, 4, 3, 2, 2, 3, 4, 5]
   end
 
-  it "should prefer a job that was scheduled to run longer ago" do
+  it "should prefer a job that was scheduled to run longer ago when priorities are equal" do
     Que::Job.queue :run_at => Time.now - 30
     Que::Job.queue :run_at => Time.now - 60
     Que::Job.queue :run_at => Time.now - 30
@@ -70,7 +62,7 @@ describe Que::Job, '.work' do
     DB[:que_jobs].order_by(:job_id).select_map(:run_at).should == [recent1, recent2]
   end
 
-  it "should prefer a job that was queued earlier, judging by the job_id" do
+  it "should prefer a job that was queued earlier when priorities and run_ats are equal" do
     run_at = Time.now - 30
     Que::Job.queue :run_at => run_at
     Que::Job.queue :run_at => run_at
@@ -100,19 +92,22 @@ describe Que::Job, '.work' do
     thread = Thread.new { Que::Job.work }
 
     $q1.pop
-    DB[:pg_locks].where(:locktype => 'advisory', :objid => id).count.should be 1
+    DB[:pg_locks].where(:locktype => 'advisory').select_map(:objid).should == [id]
     $q2.push nil
 
     thread.join
   end
 
-  it "should not work jobs that are advisory-locked" do
-    Que::Job.queue
-    id = DB[:que_jobs].get(:job_id)
+  it "should skip jobs that are advisory-locked" do
+    Que::Job.queue :priority => 2
+    Que::Job.queue :priority => 1
+    Que::Job.queue :priority => 3
+    id = DB[:que_jobs].where(:priority => 1).get(:job_id)
 
     begin
       DB.select{pg_advisory_lock(id)}.single_value
-      Que::Job.work.should be nil
+      Que::Job.work.should be_an_instance_of Que::Job
+      DB[:que_jobs].order_by(:job_id).select_map(:priority).should == [1, 3]
     ensure
       DB.select{pg_advisory_unlock(id)}.single_value
     end
@@ -234,7 +229,7 @@ describe Que::Job, '.work' do
       Que::Job.work.should be false
     end
 
-    it "should behave sensibly if there's no corresponding job class" do
+    it "should throw an error properly if there's no corresponding job class" do
       DB[:que_jobs].insert :job_class => "NonexistentClass"
       Que::Job.work.should be true
       DB[:que_jobs].count.should be 1

data/spec/unit/worker_spec.rb

@@ -75,7 +75,7 @@ describe Que::Worker do
     end
   end
 
-  it "should receive and respect a notification to shut down when it is working, after its current job completes" do
+  it "should receive and respect a notification to stop down when it is working, after its current job completes" do
     begin
       BlockJob.queue :priority => 1
       Que::Job.queue :priority => 5
@@ -100,7 +100,7 @@ describe Que::Worker do
     end
   end
 
-  it "should receive and respect a notification to shut down when it is asleep" do
+  it "should receive and respect a notification to stop when it is currently asleep" do
     begin
       @worker = Que::Worker.new
       sleep_until { @worker.sleeping? }
@@ -115,7 +115,7 @@ describe Que::Worker do
     end
   end
 
-  it "should receive and respect a notification to kill its job and stop running immediately" do
+  it "should receive and respect a notification to stop immediately when it is working, and kill the job" do
     begin
       # Worker#stop! can leave the database connection in an unpredictable
       # state, which would impact the rest of the tests, so we need a special
@@ -133,4 +133,19 @@ describe Que::Worker do
       pg.close if pg
     end
   end
+
+  it "should receive and respect a notification to stop immediately when it is currently asleep" do
+    begin
+      @worker = Que::Worker.new
+      sleep_until { @worker.sleeping? }
+
+      @worker.stop!
+      @worker.wait_until_stopped
+    ensure
+      if @worker
+        @worker.thread.kill
+        @worker.thread.join
+      end
+    end
+  end
 end

data/tasks/safe_shutdown.rb

@@ -3,13 +3,15 @@
 # The situation we're trying to avoid occurs when the process dies while a job
 # is in the middle of a transaction - ideally, the transaction would be rolled
 # back and the job could just be reattempted later, but if we're not careful,
-# the transaction could be committed too early. For specifics, see this post:
+# the transaction could be committed prematurely. For specifics, see here:
 
 # http://coderrr.wordpress.com/2011/05/03/beware-of-threadkill-or-your-activerecord-transactions-are-in-danger-of-being-partially-committed/
 
 # So, this task opens a transaction within a job, makes a write, then prompts
-# you to kill it with one of a few signals. It also checks to see whether the
-# previous shutdown was clean or not.
+# you to kill it with one of a few signals. You can then run it again to make
+# sure that the write was rolled back (if it wasn't, Que isn't functioning
+# like it should). This task only explicitly tests Sequel, but the behavior
+# for ActiveRecord is very similar.
 
 task :safe_shutdown do
   require 'sequel'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: que
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Chris Hanks
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-22 00:00:00.000000000 Z
+date: 2014-01-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,13 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/advanced_setup.md
+- docs/error_handling.md
+- docs/inspecting_the_queue.md
+- docs/managing_workers.md
+- docs/using_plain_connections.md
+- docs/using_sequel.md
+- docs/writing_reliable_jobs.md
 - lib/generators/que/install_generator.rb
 - lib/generators/que/templates/add_que.rb
 - lib/que.rb
@@ -75,11 +82,13 @@ files:
 - spec/support/helpers.rb
 - spec/support/jobs.rb
 - spec/support/shared_examples/adapter.rb
-- spec/support/shared_examples/multithreaded_adapter.rb
+- spec/support/shared_examples/multi_threaded_adapter.rb
 - spec/unit/connection_spec.rb
 - spec/unit/helper_spec.rb
 - spec/unit/pool_spec.rb
 - spec/unit/queue_spec.rb
+- spec/unit/states_spec.rb
+- spec/unit/stats_spec.rb
 - spec/unit/work_spec.rb
 - spec/unit/worker_spec.rb
 - tasks/benchmark.rb
@@ -105,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.5
+rubygems_version: 2.2.0.rc.1
 signing_key: 
 specification_version: 4
 summary: A PostgreSQL-based Job Queue
@@ -118,10 +127,12 @@ test_files:
 - spec/support/helpers.rb
 - spec/support/jobs.rb
 - spec/support/shared_examples/adapter.rb
-- spec/support/shared_examples/multithreaded_adapter.rb
+- spec/support/shared_examples/multi_threaded_adapter.rb
 - spec/unit/connection_spec.rb
 - spec/unit/helper_spec.rb
 - spec/unit/pool_spec.rb
 - spec/unit/queue_spec.rb
+- spec/unit/states_spec.rb
+- spec/unit/stats_spec.rb
 - spec/unit/work_spec.rb
 - spec/unit/worker_spec.rb