Skip to content

Cleanup README.rdoc #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Cleanup README.rdoc #87

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 41 additions & 41 deletions README.rdoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,23 @@ resque-status is an extension to the resque queue system that provides simple tr

== About

resque-status provides a set of simple classes that extend resque's default
resque-status provides a set of simple classes that extend resque's default
functionality (with 0% monkey patching) to give apps a way to track specific
job instances and their status. It achieves this by giving job instances UUID's
and allowing the job instances to report their status from within their iterations.

== Installation

resque-status *requires Redis >= 1.1* (though I recommend getting the latest stable version).
You can download Redis here: http://code.google.com/p/redis/ or install it
resque-status *requires Redis >= 1.1* (though I recommend getting the latest stable version).
You can download Redis here: http://code.google.com/p/redis/ or install it
using homebrew (brew install redis).

Install the resque-status gem (which will pull in the dependencies).

gem install resque-status

To use with Rails 2.x, you can install as a plugin or add the gem to you're config:

# environment.rb
config.gem 'resque-status'

Expand All @@ -30,29 +30,29 @@ With newer Rails add this to your Gemfile:
gem 'resque-status'

Then in an initializer:

# config/initializers/resque.rb
Resque.redis = "your/redis/socket" # default localhost:6379
Resque.redis = "your/redis/socket" # default localhost:6379
Resque::Plugins::Status::Hash.expire_in = (24 * 60 * 60) # 24hrs in seconds

== NOTES ABOUT UPGRADING TO >= v0.3
== NOTES ABOUT UPGRADING TO >= v0.3

Even though this was one of the first resque plugins, later versions of resque added stricter plugin conventions
Even though this was one of the first resque plugins, later versions of resque added stricter plugin conventions
that resque-status did not completely conform to (See: https://github.com/defunkt/resque/blob/master/docs/PLUGINS.md)

Thanks to some work from @EugZol and @bukowskis v0.3 moved around some code to conform:

`Resque::Status` is now `Resque::Plugins::Status` and is now an `include`able module.
`Resque::Status.get/etc` have been moved to `Resque::Plugins::Status::Hash`

== Usage

The most direct way to use resque-status is to create your jobs using the
The most direct way to use resque-status is to create your jobs using the
Resque::Plugins::Status module. An example job would look something like:

class SleepJob
include Resque::Plugins::Status

def perform
total = (options['length'] || 1000).to_i
num = 0
Expand All @@ -62,49 +62,49 @@ Resque::Plugins::Status module. An example job would look something like:
num += 1
end
end

end

One major difference is that instead of implementing <tt>perform</tt> as a
One major difference is that instead of implementing <tt>perform</tt> as a
class method, we do our job implementation within instances of the job class.

In order to queue a SleepJob up, we also won't use <tt>Resque.enqueue</tt>, instead
we'll use the <tt>create</tt> class method which will wrap <tt>enqueue</tt> and
we'll use the <tt>create</tt> class method which will wrap <tt>enqueue</tt> and
creating a unique id (UUID) for us to track the job with.

job_id = SleepJob.create(:length => 100)

This will create a UUID enqueue the job and pass the :length option on the SleepJob
instance as options['length'] (as you can see above).

Now that we have a UUID its really easy to get the status:

status = Resque::Plugins::Status::Hash.get(job_id)

This returns a Resque::Plugins::Status::Hash object, which is a Hash (with benefits).

status.pct_complete #=> 0
status.status #=> 'queued'
status.queued? #=> true
status.working? #=> false
status.time #=> Time object
status.message #=> "Created at ..."
status.pct_complete # => 0
status.status # => 'queued'
status.queued? # => true
status.working? # => false
status.time # => Time object
status.message # => "Created at ..."

Once the worker reserves the job, the instance of SleepJob updates the status at
each iteration using <tt>at()</tt>

status = Resque::Plugins::Status::Hash.get(job_id)
status.working? #=> true
status.num #=> 5
status.total => 100
status.pct_complete => 5
status.working? # => true
status.num # => 5
status.total # => 100
status.pct_complete # => 5

If an error occurs within the job instance, the status is set to 'failed' and then
the error is re-raised so that Resque can capture it.

Its also possible to get a list of current/recent job statuses:

Resque::Plugins::Status::Hash.statuses #=> [#<Resque::Plugins::Status::Hash>, ...]
Resque::Plugins::Status::Hash.statuses # => [#<Resque::Plugins::Status::Hash>, ...]

=== Passing back data from the job

Expand All @@ -129,23 +129,23 @@ by UUID.

Resque::Plugins::Status::Hash.kill(job_id)

The next time the job at job_id calls <tt>at</tt> or tick, it will raise a Killed
The next time the job at job_id calls <tt>at</tt> or tick, it will raise a Killed
error and set the status to killed.

=== Expiration

Since Redis is RAM based, we probably don't want to keep these statuses around forever
Since Redis is RAM based, we probably don't want to keep these statuses around forever
(at least until @antirez releases the VM feature). By setting expire_in, all statuses
and thier related keys will expire in expire_in seconds from the last time theyre updated:
and their related keys will expire in expire_in seconds from the last time they're updated:

Resque::Plugins::Status::Hash.expire_in = (60 * 60) # 1 hour
=== Testing

Recent versions of Resque introduced `Resque.inline` which changes the behavior to
Recent versions of Resque introduced `Resque.inline` which changes the behavior to
instead of enqueueing and performing jobs to just executing them inline. In Resque
itself this removes the dependency on a Redis, however, `Resque::Status` uses Redis
to store information about jobs, so though `inline` "works", you will still need
to use or mock a redis connection. You should be able to use a library like
to use or mock a redis connection. You should be able to use a library like
https://github.com/causes/mock_redis alongside `inline` if you really want to
avoid Redis connections in your test.

Expand All @@ -157,30 +157,30 @@ as a plugin to resque-web.

To use, you need to setup a resque-web config file:

# ~/resque_conf.rb
# ~/resque_conf.rb
require 'resque/status_server'

Then start resque-web with your config:

resque-web ~/resque_conf.rb

This should launch resque-web in your browser and you should see a 'Statuses' tab.

http://img.skitch.com/20100119-k166xyijcjpkk6xtwnw3854a8g.jpg

== More

Source: http://github.com/quirkey/resque-status
API Docs: http://rdoc.info/projects/quirkey/resque-status
Examples: http://github.com/quirkey/resque-status/tree/master/examples
Resque: http://github.com/defunkt/resque

== Thanks

Resque is awesome, @defunkt needs a shout-out.
Resque is awesome, @defunkt needs a shout-out.

== Note on Patches/Pull Requests

* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a
Expand Down