disc 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7e4f52b8bcd6d2c7b0648a5943c23f41c2fc71b0
-  data.tar.gz: 45fded657cbdd9122369e9cee62a0f451fb65309
+  metadata.gz: 233a653ff0bf84c468fda3cbeb939259209eae64
+  data.tar.gz: c9f14c60f0d2dfa165eb56421d3e1f2ed0eb3c6c
 SHA512:
-  metadata.gz: 29e37f6f7c7b706345a66699beca6513f3adb1351b61d4a6d99513a207f0798af25a59542514f1728e56254c772e0df5cbfda5cab24a10efe8071abf75b8ec79
-  data.tar.gz: d8917b863ef3073e27ed2804174e8719d71d1021adc5c45eca79873a13988eadf9293b2f668936da140f311a204f8a94c57d216bb2a1f69d9ec2089694cfb94a
+  metadata.gz: 49b4e538464fddd391724150b4403bb4be4f00adddfe4a374e3e0a30c664e759615cc10ef8385f5d26592e5e0323f0d77e0e9a29f1aa8bddccddd6a321d874a8
+  data.tar.gz: 8e6caa1a5e2532ee85f40d97e849415cc402127e6258c83e999148c5edc673da1bb6565fa5bb5a7582f8283084dbd11d73d135e76aac14469c7b722d4df4d136

data/README.md

@@ -23,7 +23,7 @@ Disc fills the gap between your Ruby service objects and [antirez](http://antire
     include Disc::Job
     disc queue: 'urgent'
 
-    def self.perform(type)
+    def perform(type)
       # perform rather lengthy operations here.
     end
   end
@@ -94,7 +94,7 @@ Signature documentation follows:
 ## Parameters:
 #
 ## `arguments`  - an optional array of arguments with which to execute
-#                 the job's `self.perform` method.
+#                 the job's `perform` method.
 #
 # `at`          - an optional named parameter specifying a moment in the
 #                 future in which to run the job, must respond to
@@ -142,7 +142,7 @@ Signature documentation follows:
 
 You can see [Disque's ADDJOB documentation](https://github.com/antirez/disque#addjob-queue_name-job-ms-timeout-replicate-count-delay-sec-retry-sec-ttl-sec-maxlen-count-async) for more details
 
-When a Disc worker process is assigned a job, it will create a new intance of the job's class and execute the `self.perform` method with whatever arguments were previously passed to `#enqueue`.
+When a Disc worker process is assigned a job, it will create a new intance of the job's class and execute the `perform` method with whatever arguments were previously passed to `#enqueue`.
 
 Example:
 
@@ -151,7 +151,7 @@ class ComplexJob
   include Disc::Job
   disc queue: 'urgent'
 
-  def self.perform(first_parameter, second_parameter)
+  def perform(first_parameter, second_parameter)
     # do things...
   end
 end
@@ -160,7 +160,32 @@ end
 ComplexJob.enqueue(['first argument', { second: 'argument' }])
 ```
 
-### Job Status
+### Managing Jobs
+
+Disc jobs can be managed by knowing their disque ID, this id is returned by the `#enqueue` method so you can control the job or query it's state from your application code.
+
+```ruby
+Echoer.enqueue('test')
+#=> "DIa18101491133639148a574eb30cd2e12f25dcf8805a0SQ"
+```
+
+The disque ID is also available from within the context of an executing job, you can access it via `self.disque_id` if you wish to do things like notify Disque that a long-running job is still being executed.
+
+```ruby
+class LongJob
+  include Disc::Job
+
+  def perform(first_parameter, second_parameter)
+    # Do things that take a while.
+
+    Disc.disque.call('WORKING', self.disque_id)
+
+    # Do more things that take a while.
+  end
+end
+```
+
+#### Job Status
 
 After a job is enqueued, you can check it's current status like so:
 
@@ -192,12 +217,16 @@ Disc["DIa18101491133639148a574eb30cd2e12f25dcf8805a0SQ"]
 
 This information might vary, as it's retreived from Disque via the [`SHOW`](https://github.com/antirez/disque#show-job-id) command, only `arguments` and `class` are filled in by Disc, which are added by using `Disc.deserialize` on the `body` value.
 
+#### Do everything Disque can
+
+Access to the disque ID allows us to leverage the Disque API to manage the job, you can execute Disque commands via the `Disc.disque.call()` method, see [the Disque API](https://github.com/antirez/disque#main-api) to see all the commands available.
+
 ### Job Serialization
 
 Job information (their arguments, and class) need to be serialized in order to be stored
 in Disque, to this end Disc uses the `Disc.serialize` and `Disc.deserialize` methods.
 
-By default, these methods use by default the Ruby standard library json implementation in order to serialize and deserialize job data, this has a few implications:
+By default, these methods use the Ruby standard library json implementation in order to serialize and deserialize job data, this has a few implications:
 
 1. Arguments passed to a job's `#enqueue` method need to be serializable by `Disc.serialize` and parsed back by `Disc.deserialize`, so by default you can't pass complex Ruby objects like a `user` model, instead, pass `user.id`, and use that from your job code.
 
@@ -317,7 +346,7 @@ end
 class CluJob < ActiveJob::Base
   queue_as :urgent
 
-  def self.perform(*args)
+  def perform(*args)
     # Try to take over The Grid here...
   end
 end

data/examples/echoer.rb

@@ -4,7 +4,7 @@ class Echoer
   include Disc::Job
   disc queue: 'test'
 
-  def self.perform(first, second, third)
+  def perform(first, second, third)
     puts "First: #{ first }, Second: #{ second }, Third: #{ third }"
   end
 end

data/examples/failer.rb

@@ -10,7 +10,7 @@ class Failer
   include Disc::Job
   disc queue: 'test'
 
-  def self.perform(string)
+  def perform(string)
     raise string
   end
 end

data/examples/greeter.rb

@@ -4,7 +4,7 @@ class Greeter
   include Disc::Job
   disc queue: 'test_medium'
 
-  def self.perform(string)
+  def perform(string)
     $stdout.puts(string)
   end
 end

data/examples/identifier.rb

@@ -0,0 +1,10 @@
+require 'disc'
+
+class Identifier
+  include Disc::Job
+  disc queue: 'test'
+
+  def perform
+    $stdout.puts("Working with Disque ID: #{ self.disque_id }")
+  end
+end

data/examples/returner.rb

@@ -1,7 +1,7 @@
 class Returner
   include Disc::Job
 
-  def self.perform(argument)
+  def perform(argument)
     return argument
   end
 end

data/lib/disc.rb

@@ -73,7 +73,7 @@ class Disc
   #     * An instance of the given job class
   #     * An array of arguments to pass to the job's `#perorm` class.
   #
-  def self.load_job(serialized_job)
+  def self.load_job(serialized_job, disque_id = nil)
     begin
       job_data = Disc.deserialize(serialized_job)
     rescue => err
@@ -86,7 +86,14 @@ class Disc
       raise Disc::UnknownJobClassError.new(err)
     end
 
-    return [job_class, job_data['arguments']]
+    begin
+      job_instance = job_class.new
+      job_instance.disque_id = disque_id
+    rescue => err
+      raise Disc::NonJobClassError.new(err)
+    end
+
+    return [job_instance, job_data['arguments']]
   end
 end
 

data/lib/disc/errors.rb

@@ -1,6 +1,7 @@
 class Disc
   class Error < StandardError; end
 
-  class UnknownJobClassError < Error; end
-  class NonParsableJobError  < Error; end
+  class UnknownJobClassError  < Error; end
+  class NonParsableJobError   < Error; end
+  class NonJobClassError      < Error; end
 end

data/lib/disc/job.rb

@@ -1,4 +1,5 @@
 module Disc::Job
+  attr_accessor :disque_id
 
   def self.included(base)
     base.extend(ClassMethods)
@@ -26,6 +27,10 @@ module Disc::Job
       @queue || Disc.default_queue
     end
 
+    def perform(arguments)
+      self.new.perform(*arguments)
+    end
+
     ## Disc's `#enqueue` is the main user-facing method of a Disc job, it
     #  enqueues a job with a given set of arguments in Disque, so it can be
     #  picked up by a Disc worker process.

data/lib/disc/version.rb

@@ -1,3 +1,3 @@
 class Disc
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/disc/worker.rb

@@ -52,15 +52,15 @@ class Disc::Worker
       jobs = disque.fetch(from: queues, timeout: timeout, count: count)
       Array(jobs).each do |queue, msgid, serialized_job|
         begin
-          job_class, arguments = Disc.load_job(serialized_job)
-          job_class.perform(*arguments)
+          job_instance, arguments = Disc.load_job(serialized_job, msgid)
+          job_instance.perform(*arguments)
           disque.call('ACKJOB', msgid)
-          $stdout.puts("Completed #{ job_class.name } id #{ msgid }")
+          $stdout.puts("Completed #{ job_instance.class.name } id #{ msgid }")
         rescue => err
           Disc.on_error(err, {
             disque_id: msgid,
             queue: queue,
-            class: defined?(job_class) ? job_class.name : '',
+            class: defined?(job_instance) ? job_instance.class.name : '',
             arguments: defined?(arguments) ? arguments : []
           })
         end

data/test/disc_test.rb

@@ -44,9 +44,9 @@ scope do
       { class: 'Echoer', arguments: ['one argument', { random: 'data' }, 3] }
     )
 
-    job_class, arguments = Disc.load_job(serialized_job)
+    job_instance, arguments = Disc.load_job(serialized_job)
 
-    assert_equal Echoer, job_class
+    assert_equal Echoer, job_instance.class
     assert arguments.is_a?(Array)
     assert_equal 3, arguments.count
     assert_equal 'one argument', arguments.first

data/test/process_test.rb

@@ -5,6 +5,7 @@ require 'timeout'
 
 require_relative '../examples/echoer'
 require_relative '../examples/failer'
+require_relative '../examples/identifier'
 
 prepare do
   Disc.disque_timeout = 1 # 1ms so we don't wait at all.
@@ -35,14 +36,12 @@ scope do
 
     run('QUEUES=test ruby -Ilib bin/disc -r ./examples/failer') do |cout, pid|
       output = Timeout.timeout(1) { cout.take(5) }
-      jobs = Disc.disque.fetch(from: ['test'], timeout: Disc.disque_timeout, count: 1)
-      assert jobs.nil?
-
       assert output.grep(/<insert error reporting here>/).any?
       assert output.grep(/this can only end positively/).any?
       assert output.grep(/Failer/).any?
 
       assert is_running?(pid)
+      assert_equal 0, Disc.qlen(Failer.queue)
     end
   end
 
@@ -51,9 +50,19 @@ scope do
 
     run('QUEUES=test ruby -Ilib bin/disc -r ./examples/echoer') do |cout, pid|
       output = Timeout.timeout(1) { cout.take(3) }
-      jobs = Disc.disque.fetch(from: ['test'], timeout: Disc.disque_timeout, count: 1)
-      assert jobs.nil?
       assert output.grep(/First: one argument, Second: {"random"=>"data"}, Third: 3/).any?
+      assert_equal 0, Disc.qlen(Echoer.queue)
+    end
+  end
+
+  test 'running jobs have access to their Disque job ID' do
+    disque_id = Identifier.enqueue
+
+    run('QUEUES=test ruby -Ilib bin/disc -r ./examples/identifier') do |cout, pid|
+      output = Timeout.timeout(1) { cout.take(3) }
+      assert output.grep(/Working with Disque ID: #{ disque_id }/).any?
+
+      assert_equal 0, Disc.qlen(Identifier.queue)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: disc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - pote
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-10 00:00:00.000000000 Z
+date: 2016-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: disque
@@ -61,6 +61,7 @@ files:
 - examples/echoer.rb
 - examples/failer.rb
 - examples/greeter.rb
+- examples/identifier.rb
 - examples/returner.rb
 - lib/active_job/queue_adapters/disc_adapter.rb
 - lib/disc.rb