resque-access_worker_from_job 0.1.2 → 0.2.0

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009 Kali Donovan
+Copyright (c) 2010 Kali Donovan
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,32 +1,61 @@
 = Resque-AccessWorkerFromJob
 
-Small plugin appending the calling worker to the argument list received by the +perform+ method of Resque jobs.  Developed against Resque 1.8.0.
+Small plugin allowing the +perform+ method of Resque jobs to access the worker running them via the cleverly-named +worker+ instance variable.
 
 Purpose: this allows jobs to access shared sockets in the parent worker.
 
-=== Warning
-Be careful to note that each job forks before running, so ivars will be a COPY and, if changed,
-their changes won't persist into the next job's perform method.  However, since sockets ARE persisted, this
-allows multiple jobs to share a single persistent socket kept alive in the worker.
-
-=== Only running in certain workers
-As additional functionality, this plugin can also abort a job gracefully if it's picked up by the wrong worker 
+As additional functionality, it can also abort a job gracefully if it's picked up by the wrong worker 
 class, which is useful if you've subclassed Resque::Worker to add your own functionality and need to ensure
 your jobs aren't accidentally run against the original superclass.
 
+Developed against Resque 1.8.0.
+
+
 == Usage
 To use, add 
 
  extend Resque::Plugins::AccessWorkerFromJob
 
-to the class with the perform method.
+to the _bottom_ of the class with the perform method (the extend line must come _after_ the perform method has 
+already been defined, or else the alias method will fail). Now your perform method can reference a +worker+
+attribute.
+
+Example:
+
+  class MessageJob
+    @queue = :messages
+    
+    # Example using shared socket from worker (via @worker or self.worker)
+    def self.perform( msg )
+      worker.socket.write( msg )
+    end
+   
+    extend Resque::Plugins::AccessWorkerFromJob
+    self.required_worker_class = 'CustomApplication::MessageSender'
+  end
 
-To implement the additional requiring-certain-worker-class feature, add 
+
+To implement the additional abort-if-picked-up-by-wrong-worker-class feature, add 
 
  self.required_worker_class = 'ClassName'
 
 as well.
 
+
+== Warnings
+=== Argument errors in mixed environments
+Internally, this overrides Resque::Job to append the worker to the argument list passed to any <code>JobClass#perform</code>
+method. For a class that extends Resque::Plugins::AccessWorkerFromJob, this is handled transparently (worker is 
+removed from the argument list and is available via the <code>@worker</code> instance variable, instead).  For mixed environments
+where not all jobs to be run extend AccessWorkerFromJob, and where some of these expect a set number of arguments,
+this may cause problems ("wrong number of arguments" exceptions).
+
+=== Ephemeral nature of worker changes
+Be careful to note that each job forks before running, so instance variables will be a _copy_ and, if changed,
+their changes won't persist into the next job's perform method.  However, since sockets ARE persisted, this
+allows multiple jobs to share a single persistent socket kept alive in the worker.
+
+
 == Copyright
 
 Copyright (c) 2010 Kali Donovan. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.2.0

data/lib/resque-access_worker_from_job.rb

@@ -1 +1 @@
-require 'lib/resque/plugins/access_worker_from_job'
+require File.expane_path(File.dirname(__FILE__)) + "/resque/plugins/access_worker_from_job.rb"

data/lib/resque/job.rb

@@ -0,0 +1,9 @@
+module Resque # :nodoc:
+  # Resque-AccessWorkerFromJob plugin overrides the Resque::Job#args method to pass the worker along as the last argument.
+  class Job
+    # Overridden args appends the worker when returning the list of args represented in this job's payload.
+    def args
+      @payload['args'] + [worker]
+    end
+  end
+end

data/lib/resque/plugins/access_worker_from_job.rb

@@ -1,46 +1,70 @@
-module Resque
-  module Plugins
-    # Adds a Resque plugin to allow jobs to access the worker running them as the last argument in the call
-    # to +perform+.  Purpose: this allows jobs to access shared sockets in the parent worker.
-    #
-    # Be careful to note that each job forks before running, however, so ivars will be a COPY and, if changed,
-    # their changes won't persist into the next job's perform method.  However, since sockets ARE persisted, this
-    # allows multiple jobs to share a single persistent socket kept alive in the worker.
+require File.expand_path(File.dirname(__FILE__)) + '/../job'
+
+module Resque  
+  module Plugins # :nodoc:
+    # Adds a Resque plugin to allow jobs to access the worker running them via a cleverly-named +worker+ 
+    # instance variable.  Purpose: this allows jobs to access shared sockets in the parent worker.
     #
-    # As additional functionality, this plugin can also abort a job gracefully if it's picked up by the wrong worker 
-    # class, which is useful if you've subclassed Resque::Worker to add your own functionality and need to ensure
-    # your jobs aren't accidentally run against the original superclass.
+    # Be careful to note that each job forks before running, however, so instance variables will be a COPY and, if 
+    # changed, their changes won't persist into the next job's perform method.  However, since sockets ARE persisted,
+    # this allows multiple jobs to share a single persistent socket kept alive in the worker.
     #
     # To use, add 
     #
     #   extend Resque::Plugins::AccessWorkerFromJob
     #
-    # to the class with the perform method.
+    # to the BOTTOM of the class with the perform method (the extend line must come AFTER the perform method has 
+    # already been defined, or else the alias method will fail). Now your perform method can reference a +worker+
+    # attribute.
     # 
-    # To implement the additional requiring-certain-worker-class feature, add 
+    # As additional functionality, this plugin can also abort a job gracefully if it's picked up by the wrong worker 
+    # class, which is useful if you've subclassed Resque::Worker to add your own functionality and need to ensure
+    # your jobs aren't accidentally run against the original superclass.  Note that if your job is picked up by the
+    # wrong class it'll be removed from the queue, though -- this provides a way to avoid messy exceptions, but it's
+    # still your responsibility to make sure you keep your queues + worker classes straight.
+    #
+    # To implement this additional requiring-certain-worker-class feature, add 
     #
     #   self.required_worker_class = 'ClassName'
     #
     # as well.
     module AccessWorkerFromJob
-      attr_accessor :required_worker_class
+      attr_accessor :required_worker_class, :worker
       
-      # Overrides args to append the worker when returning the list of args represented in this job's payload.
-      def args
-        @payload['args'] + [worker]
+      def self.extended(base)
+        
+        unless base.methods.include?('perform')
+          raise %Q{You must call "extend Resque::Plugins::AccessWorkerFromJob" AFTER (below) defining the perform method}
+        end
+        
+        class << base
+          
+          # Remove worker from last argument, so can write their perform method assuming just the arguments
+          # they sent it, without worrying about the appended worker.
+          def perform_with_worker_in_arguments(*args)
+            args.pop if args.last.is_a?(::Resque::Worker)
+            perform_without_modified_arguments( *args )
+          end
+
+          alias_method :perform_without_modified_arguments, :perform unless method_defined?(:perform_without_modified_arguments)
+          alias_method :perform, :perform_with_worker_in_arguments
+        end 
       end
       
-      # Abort gracefully if picked up by the wrong worker, so message remains in queue to be sent
+      
+      # Abort gracefully if picked up by the wrong worker (job will be removed from queue)
       def before_perform_ensure_proper_worker(*args)
-        worker = args.last
+        if args.last.is_a?(::Resque::Worker)
+          self.worker = args.last
+        else
+          raise "You must override Resque::Job#args to pass worker as last argument. See README."
+        end
+        
         if required_worker_class && worker.class.name != required_worker_class
           raise ::Resque::Job::DontPerform
         end
-
-        # TODO: Make sure this keeps the job in the queue! seems to just skip it and remove from queue, so it'll never be performed
-        # raise ::Resque::Job::DontPerform
       end
       
     end
   end
-end
+end

data/resque-access_worker_from_job.gemspec

@@ -0,0 +1,52 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{resque-access_worker_from_job}
+  s.version = "0.2.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Kali Donovan"]
+  s.date = %q{2010-04-25}
+  s.description = %q{By allowing multiple jobs to share a single socket, which is persisted over the life of the worker, this plugin is an important building block for implementing a Resque-based service send background iPhone messages via the Apple Push Notification servers.}
+  s.email = %q{kali.donovan@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "init.rb",
+     "lib/resque-access_worker_from_job.rb",
+     "lib/resque/job.rb",
+     "lib/resque/plugins/access_worker_from_job.rb",
+     "rails/init.rb",
+     "resque-access_worker_from_job.gemspec"
+  ]
+  s.homepage = %q{http://github.com/kdonovan/resque-access_worker_from_job}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Resque plugin to allow jobs access to their calling worker at runtime.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<resque>, [">= 0"])
+    else
+      s.add_dependency(%q<resque>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<resque>, [">= 0"])
+  end
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: resque-access_worker_from_job
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors: 
 - Kali Donovan
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-13 00:00:00 -07:00
+date: 2010-04-25 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -40,8 +40,10 @@ files:
 - VERSION
 - init.rb
 - lib/resque-access_worker_from_job.rb
+- lib/resque/job.rb
 - lib/resque/plugins/access_worker_from_job.rb
 - rails/init.rb
+- resque-access_worker_from_job.gemspec
 has_rdoc: true
 homepage: http://github.com/kdonovan/resque-access_worker_from_job
 licenses: []