Merge branch 'master' into 2.0

Conflicts:
	HISTORY.md
	test/worker_test.rb

Author: defunkt

HISTORY.md

@@ -2,6 +2,19 @@
 
 * Resque now uses Unix Epoch Timestamps exclusively.
 
+## 1.7.1 (2010-04-02)
+
+* Bugfix: Make job hook execution order consistent
+* Bugfix: stdout buffering in child process
+
+## 1.7.0 (2010-03-31)
+
+* Job hooks API. See docs/HOOKS.md.
+* web: Hovering over dates shows a timestamp
+* web: AJAXify retry action for failed jobs
+* web bugfix: Fix pagination bug
+>>>>>>> master
+
 ## 1.6.1 (2010-03-25)
 
 * Bugfix: Workers may not be clearing their state correctly on

README.markdown

@@ -653,39 +653,16 @@ this way we can tell our Sinatra app about the config file:
 
 Now everyone is on the same page.
 
-Worker Hooks
-------------
-
-If you wish to have a Proc called before the worker forks for the
-first time, you can add it in the initializer like so:
-
-    Resque.before_first_fork do
-      puts "Call me once before the worker forks the first time"
-    end
-
-You can also run a hook before _every_ fork:
-
-    Resque.before_fork do |job|
-      puts "Call me before the worker forks"
-    end
-
-The `before_fork` hook will be run in the **parent** process. So, be
-careful - any changes you make will be permanent for the lifespan of
-the worker.
-
-And after forking:
 
-    Resque.after_fork do |job|
-      puts "Call me after the worker forks"
-    end
-
-The `after_fork` hook will be run in the child process and is passed
-the current job. Any changes you make, therefor, will only live as
-long as the job currently being processes.
+Plugins and Hooks
+-----------------
 
-All hooks can also be set using a setter, e.g.
+For a list of available plugins see
+<http://wiki.github.com/defunkt/resque/plugins>.
 
-    Resque.after_fork = proc { puts "called" }
+If you'd like to write your own plugin, or want to customize Resque
+using hooks (such as `Resque.after_fork`), see
+[docs/HOOKS.md](http://github.com/defunkt/resque/blob/master/HOOKS.md).
 
 To clear all hooks, set nil or false:
 
@@ -788,7 +765,7 @@ Mailing List
 
 To join the list simply send an email to <[email protected]>. This
 will subscribe you and send you information about your subscription,
-include unsubscribe information.
+including unsubscribe information.
 
 The archive can be found at <http://librelist.com/browser/>.
 

Rakefile

@@ -1,25 +1,45 @@
+#
+# Setup
+#
+
 load 'tasks/redis.rake'
+require 'rake/testtask'
 
 $LOAD_PATH.unshift 'lib'
 require 'resque/tasks'
 
+def command?(command)
+  system("type #{command} > /dev/null")
+end
+
+
+#
+# Tests
+#
+
 task :default => :test
 
-desc "Run tests"
+desc "Run the test suite"
 task :test do
-  # Don't use the rake/testtask because it loads a new
-  # Ruby interpreter - we want to run tests with the current
-  # `rake` so our library manager still works
-  Dir['test/*_test.rb'].each do |f|
-    require f
+  rg = command?(:rg)
+  Dir['test/**/*_test.rb'].each do |f|
+    rg ? sh("rg #{f}") : ruby(f)
   end
 end
 
-desc "Activate kicker - gem install kicker"
-task :kick do
-  exec "kicker -e rake lib test"
+if command? :kicker
+  desc "Launch Kicker (like autotest)"
+  task :kicker do
+    puts "Kicking... (ctrl+c to cancel)"
+    exec "kicker -e rake test lib examples"
+  end
 end
 
+
+#
+# Gem
+#
+
 task :install => [ 'redis:install', 'dtach:install' ]
 
 desc "Build a gem"
@@ -31,8 +51,7 @@ begin
 
   Jeweler::Tasks.new do |gemspec|
     gemspec.name = "resque"
-    gemspec.summary = ""
-    gemspec.description = ""
+    gemspec.summary = "Resque is a Redis-backed queueing system."
     gemspec.email = "[email protected]"
     gemspec.homepage = "http://github.com/defunkt/resque"
     gemspec.authors = ["Chris Wanstrath"]
@@ -43,18 +62,45 @@ begin
     gemspec.add_dependency "vegas", ">=0.1.2"
     gemspec.add_dependency "sinatra", ">=0.9.2"
     gemspec.add_development_dependency "jeweler"
+
+    gemspec.description = <<description
+    Resque is a Redis-backed Ruby library for creating background jobs,
+    placing those jobs on multiple queues, and processing them later.
+
+    Background jobs can be any Ruby class or module that responds to
+    perform. Your existing classes can easily be converted to background
+    jobs or you can create new classes specifically to do work. Or, you
+    can do both.
+
+    Resque is heavily inspired by DelayedJob (which rocks) and is
+    comprised of three parts:
+
+    * A Ruby library for creating, querying, and processing jobs
+    * A Rake task for starting a worker which processes jobs
+    * A Sinatra app for monitoring queues, jobs, and workers.
+description
   end
 rescue LoadError
   puts "Jeweler not available. Install it with: "
   puts "gem install jeweler"
 end
 
+
+#
+# Documentation
+#
+
 begin
   require 'sdoc_helpers'
 rescue LoadError
   puts "sdoc support not enabled. Please gem install sdoc-helpers."
 end
 
+
+#
+# Publishing
+#
+
 desc "Push a new version to Gemcutter"
 task :publish => [ :test, :gemspec, :build ] do
   system "git tag v#{Resque::Version}"

docs/HOOKS.md

@@ -0,0 +1,121 @@
+Resque Hooks
+============
+
+You can customize Resque or write plugins using its hook API. In many
+cases you can use a hook rather than mess with Resque's internals.
+
+For a list of available plugins see
+<http://wiki.github.com/defunkt/resque/plugins>.
+
+
+Worker Hooks
+------------
+
+If you wish to have a Proc called before the worker forks for the
+first time, you can add it in the initializer like so:
+
+    Resque.before_first_fork do
+      puts "Call me once before the worker forks the first time"
+    end
+
+You can also run a hook before _every_ fork:
+
+    Resque.before_fork do |job|
+      puts "Call me before the worker forks"
+    end
+
+The `before_fork` hook will be run in the **parent** process. So, be
+careful - any changes you make will be permanent for the lifespan of
+the worker.
+
+And after forking:
+
+    Resque.after_fork do |job|
+      puts "Call me after the worker forks"
+    end
+
+The `after_fork` hook will be run in the child process and is passed
+the current job. Any changes you make, therefor, will only live as
+long as the job currently being processes.
+
+All worker hooks can also be set using a setter, e.g.
+
+    Resque.after_fork = proc { puts "called" }
+
+
+Job Hooks
+---------
+
+Plugins can utilize job hooks to provide additional behavior. A job
+hook is a method name in the following format:
+
+    HOOKNAME_IDENTIFIER
+
+For example, a `before_perform` hook which adds locking may be defined
+like this:
+
+    def before_perform_with_lock(*args)
+      set_lock!
+    end
+
+Once this hook is made available to your job (either by way of
+inheritence or `extend`), it will be run before the job's `perform`
+method is called. Hooks of each type are executed in alphabetical order,
+so `before_perform_a` will always be executed before `before_perform_b`.
+An unnamed hook (`before_perform`) will be executed first.
+
+The available hooks are:
+
+* `before_perform`: Called with the job args before perform. If it raises
+  `Resque::Job::DontPerform`, the job is aborted. If other exceptions
+  are raised, they will be propagated up the the `Resque::Failure`
+  backend.
+
+* `after_perform`: Called with the job args after it performs. Uncaught
+  exceptions will propagate up to the `Resque::Failure` backend.
+
+* `around_perform`: Called with the job args. It is expected to yield in order
+  to perform the job (but is not required to do so). It may handle exceptions
+  thrown by `perform`, but any that are not caught will propagate up to the
+  `Resque::Failure` backend.
+
+* `on_failure`: Called with the exception and job args if any exception occurs
+  while performing the job (or hooks).
+
+Hooks are easily implemented with superclasses or modules. A superclass could
+look something like this.
+
+    class LoggedJob
+      def self.before_perform_log_job(*args)
+        Logger.info "About to perform #{self} with #{args.inspect}"
+      end
+    end
+
+    class MyJob < LoggedJob
+      def self.perform(*args)
+        ...
+      end
+    end
+
+Modules are even better because jobs can use many of them.
+
+    module LoggedJob
+      def before_perform_log_job(*args)
+        Logger.info "About to perform #{self} with #{args.inspect}"
+      end
+    end
+
+    module RetriedJob
+      def on_failure_retry(e, *args)
+        Logger.info "Performing #{self} caused an exception (#{e}). Retrying..."
+        Resque.enqueue self, *args
+      end
+    end
+
+    class MyJob
+      extend LoggedJob
+      extend RetriedJob
+      def self.perform(*args)
+        ...
+      end
+    end