README.markdown in resque_admin-0.2.0 vs README.markdown in resque_admin-1.0.2
- old
+ new
@@ -1,59 +1,59 @@
-ResqueAdmin
+Resque
======
[](https://rubygems.org/gems/resque)
[](https://travis-ci.org/resque/resque)
[](https://coveralls.io/r/resque/resque?branch=1-x-stable)
-ResqueAdmin (pronounced like "rescue") is a Redis-backed library for creating
+Resque (pronounced like "rescue") is a Redis-backed 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.
-ResqueAdmin is heavily inspired by DelayedJob (which rocks) and comprises
+Resque is heavily inspired by DelayedJob (which rocks) and comprises
three parts:
1. A Ruby library for creating, querying, and processing jobs
2. A Rake task for starting a worker which processes jobs
3. A Sinatra app for monitoring queues, jobs, and workers.
-ResqueAdmin workers can be distributed between multiple machines,
+Resque workers can be distributed between multiple machines,
support priorities, are resilient to memory bloat / "leaks," are
optimized for REE (but work on MRI and JRuby), tell you what they're
doing, and expect failure.
-ResqueAdmin queues are persistent; support constant time, atomic push and
+Resque queues are persistent; support constant time, atomic push and
pop (thanks to Redis); provide visibility into their contents; and
store jobs as simple JSON packages.
-The ResqueAdmin frontend tells you what workers are doing, what workers are
+The Resque frontend tells you what workers are doing, what workers are
not doing, what queues you're using, what's in those queues, provides
general usage stats, and helps you track failures.
-ResqueAdmin now supports Ruby 2.0.0 and above. Any future updates will not be
+Resque now supports Ruby 2.0.0 and above. Any future updates will not be
guaranteed to work without defects on any Rubies older than 2.0.0. We will also only be supporting Redis 3.0 and above going forward.
The Blog Post
-------------
-For the backstory, philosophy, and history of ResqueAdmin's beginnings,
+For the backstory, philosophy, and history of Resque's beginnings,
please see [the blog post][0].
Overview
--------
-ResqueAdmin allows you to create jobs and place them on a queue, then,
+Resque allows you to create jobs and place them on a queue, then,
later, pull those jobs off the queue and process them.
-ResqueAdmin jobs are Ruby classes (or modules) which respond to the
+Resque jobs are Ruby classes (or modules) which respond to the
`perform` method. Here's an example:
``` ruby
class Archive
@@ -74,11 +74,11 @@
to our application's pre-existing `Repository` class:
``` ruby
class Repository
def async_create_archive(branch)
- ResqueAdmin.enqueue(Archive, self.id, branch)
+ Resque.enqueue(Archive, self.id, branch)
end
end
```
Now when we call `repo.async_create_archive('masterbrew')` in our
@@ -86,11 +86,11 @@
queue.
Later, a worker will run something like this code to process the job:
``` ruby
-klass, args = ResqueAdmin.reserve(:file_serve)
+klass, args = Resque.reserve(:file_serve)
klass.perform(*args) if klass.respond_to? :perform
```
Which translates to:
@@ -101,13 +101,13 @@
Let's start a worker to run `file_serve` jobs:
$ cd app_root
$ QUEUE=file_serve rake resque:work
-This starts one ResqueAdmin worker and tells it to work off the
+This starts one Resque worker and tells it to work off the
`file_serve` queue. As soon as it's ready it'll try to run the
-`ResqueAdmin.reserve` code snippet above and process jobs until it can't
+`Resque.reserve` code snippet above and process jobs until it can't
find any more, at which point it will sleep for a small period and
repeatedly poll the queue for more jobs.
Workers can be given multiple queues (a "queue list") and run on
multiple machines. In fact they can be run anywhere with network
@@ -118,11 +118,11 @@
----
What should you run in the background? Anything that takes any time at
all. Slow INSERT statements, disk manipulating, data processing, etc.
-At GitHub we use ResqueAdmin to process the following types of jobs:
+At GitHub we use Resque to process the following types of jobs:
* Warming caches
* Counting disk usage
* Building tarballs
* Building Rubygems
@@ -132,11 +132,11 @@
* Deleting users
* Updating our search index
As of writing we have about 35 different types of background jobs.
-Keep in mind that you don't need a web app to use ResqueAdmin - we just
+Keep in mind that you don't need a web app to use Resque - we just
mention "foreground" and "background" because they make conceptual
sense. You could easily be spidering sites and sticking data which
needs to be crunched later into a queue.
@@ -162,17 +162,17 @@
Because of this your jobs must only accept arguments that can be JSON encoded.
So instead of doing this:
``` ruby
-ResqueAdmin.enqueue(Archive, self, branch)
+Resque.enqueue(Archive, self, branch)
```
do this:
``` ruby
-ResqueAdmin.enqueue(Archive, self.id, branch)
+Resque.enqueue(Archive, self.id, branch)
```
This is why our above example (and all the examples in `examples/`)
uses object IDs instead of passing around the objects.
@@ -195,35 +195,35 @@
### Failure
If a job raises an exception, it is logged and handed off to the
-`ResqueAdmin::Failure` module. Failures are logged either locally in Redis
+`Resque::Failure` module. Failures are logged either locally in Redis
or using some different backend. To see exceptions while developing,
use VERBOSE env variable, see details below under Logging.
-For example, ResqueAdmin ships with Airbrake support. To configure it, put
+For example, Resque ships with Airbrake support. To configure it, put
the following into an initialisation file or into your rake job:
``` ruby
# send errors which occur in background jobs to redis and airbrake
require 'resque/failure/multiple'
require 'resque/failure/redis'
require 'resque/failure/airbrake'
-ResqueAdmin::Failure::Multiple.classes = [ResqueAdmin::Failure::Redis, ResqueAdmin::Failure::Airbrake]
-ResqueAdmin::Failure.backend = ResqueAdmin::Failure::Multiple
+Resque::Failure::Multiple.classes = [Resque::Failure::Redis, Resque::Failure::Airbrake]
+Resque::Failure.backend = Resque::Failure::Multiple
```
Keep this in mind when writing your jobs: you may want to throw
exceptions you would not normally throw in order to assist debugging.
Workers
-------
-ResqueAdmin workers are rake tasks that run forever. They basically do this:
+Resque workers are rake tasks that run forever. They basically do this:
``` ruby
start
loop do
if job = reserve
@@ -237,15 +237,15 @@
Starting a worker is simple. Here's our example from earlier:
$ QUEUE=file_serve rake resque:work
-By default ResqueAdmin won't know about your application's
+By default Resque won't know about your application's
environment. That is, it won't be able to find and run your jobs - it
needs to load your application into memory.
-If we've installed ResqueAdmin as a Rails plugin, we might run this command
+If we've installed Resque as a Rails plugin, we might run this command
from our RAILS_ROOT:
$ QUEUE=file_serve rake environment resque:work
This will load the environment before starting a worker. Alternately
@@ -263,11 +263,11 @@
Grit::Git.git_timeout = 10.minutes
end
```
We don't want the `git_timeout` as high as 10 minutes in our web app,
-but in the ResqueAdmin workers it's fine.
+but in the Resque workers it's fine.
### Logging
Workers support basic logging to STDOUT. If you start them with the
@@ -275,15 +275,15 @@
information. You can also set the `VVERBOSE` (very verbose) env
variable.
$ VVERBOSE=1 QUEUE=file_serve rake environment resque:work
-If you want ResqueAdmin to log to a file, in Rails do:
+If you want Resque to log to a file, in Rails do:
```ruby
# config/initializers/resque.rb
-ResqueAdmin.logger = Logger.new(Rails.root.join('log', "#{Rails.env}_resque.log"))
+Resque.logger = Logger.new(Rails.root.join('log', "#{Rails.env}_resque.log"))
```
### Process IDs (PIDs)
There are scenarios where it's helpful to record the PID of a resque
@@ -308,11 +308,11 @@
$ INTERVAL=0.1 QUEUE=file_serve rake environment resque:work
### Priorities and Queue Lists
-ResqueAdmin doesn't support numeric priorities but instead uses the order
+Resque doesn't support numeric priorities but instead uses the order
of queues you give it. We call this list of queues the "queue list."
Let's say we add a `warm_cache` queue in addition to our `file_serve`
queue. We'd now start a worker like so:
@@ -362,43 +362,43 @@
If you'd like to run multiple workers in development mode, you can do
so using the `resque:workers` rake task:
$ COUNT=5 QUEUE=* rake resque:workers
-This will spawn five ResqueAdmin workers, each in its own process. Hitting
+This will spawn five Resque workers, each in its own process. Hitting
ctrl-c should be sufficient to stop them all.
### Forking
-On certain platforms, when a ResqueAdmin worker reserves a job it
+On certain platforms, when a Resque worker reserves a job it
immediately forks a child process. The child processes the job then
exits. When the child has exited successfully, the worker reserves
another job and repeats the process.
Why?
-Because ResqueAdmin assumes chaos.
+Because Resque assumes chaos.
-ResqueAdmin assumes your background workers will lock up, run too long, or
+Resque assumes your background workers will lock up, run too long, or
have unwanted memory growth.
-If ResqueAdmin workers processed jobs themselves, it'd be hard to whip them
+If Resque workers processed jobs themselves, it'd be hard to whip them
into shape. Let's say one is using too much memory: you send it a
signal that says "shutdown after you finish processing the current
job," and it does so. It then starts up again - loading your entire
application environment. This adds useless CPU cycles and causes a
delay in queue processing.
Plus, what if it's using too much memory and has stopped responding to
signals?
-Thanks to ResqueAdmin's parent / child architecture, jobs that use too much memory
+Thanks to Resque's parent / child architecture, jobs that use too much memory
release that memory upon completion. No unwanted growth.
And what if a job is running too long? You'd need to `kill -9` it then
-start the worker again. With ResqueAdmin's parent / child architecture you
+start the worker again. With Resque's parent / child architecture you
can tell the parent to forcefully kill the child then immediately
start processing more jobs. No startup delay or wasted cycles.
The parent / child architecture helps us keep tabs on what workers are
doing, too. By eliminating the need to `kill -9` workers we can have
@@ -431,23 +431,23 @@
92099 resque: Waiting for file_serve,warm_cache
### Signals
-ResqueAdmin workers respond to a few different signals:
+Resque workers respond to a few different signals:
* `QUIT` - Wait for child to finish processing then exit
* `TERM` / `INT` - Immediately kill child then exit
* `USR1` - Immediately kill child but don't exit
* `USR2` - Don't start to process any new jobs
* `CONT` - Start to process new jobs again after a USR2
-If you want to gracefully shutdown a ResqueAdmin worker, use `QUIT`.
+If you want to gracefully shutdown a Resque worker, use `QUIT`.
If you want to kill a stale or stuck child, use `USR1`. Processing
will continue as normal unless the child was not found. In that case
-ResqueAdmin assumes the parent process is in a bad state and shuts down.
+Resque assumes the parent process is in a bad state and shuts down.
If you want to kill a stale or stuck child and shutdown, use `TERM`
If you want to stop processing jobs, but want to leave the worker running
(for example, to temporarily alleviate load), use `USR2` to stop processing,
@@ -455,27 +455,27 @@
#### Signals on Heroku
When shutting down processes, Heroku sends every process a TERM signal at the
same time. By default this causes an immediate shutdown of any running job
-leading to frequent `ResqueAdmin::TermException` errors. For short running jobs, a simple
+leading to frequent `Resque::TermException` errors. For short running jobs, a simple
solution is to give a small amount of time for the job to finish
before killing it.
-ResqueAdmin doesn't handle this out of the box (for both cedar-14 and heroku-16), you need to
+Resque doesn't handle this out of the box (for both cedar-14 and heroku-16), you need to
install the [`resque-heroku-signals`](https://github.com/iloveitaly/resque-heroku-signals)
addon which adds the required signal handling to make the behavior described above work.
Related issue: https://github.com/resque/resque/issues/1559
To accomplish this set the following environment variables:
* `RESQUE_PRE_SHUTDOWN_TIMEOUT` - The time between the parent receiving a shutdown signal (TERM by default) and it sending that signal on to the child process. Designed to give the child process
time to complete before being forced to die.
-* `TERM_CHILD` - Must be set for `RESQUE_PRE_SHUTDOWN_TIMEOUT` to be used. After the timeout, if the child is still running it will raise a `ResqueAdmin::TermException` and exit.
+* `TERM_CHILD` - Must be set for `RESQUE_PRE_SHUTDOWN_TIMEOUT` to be used. After the timeout, if the child is still running it will raise a `Resque::TermException` and exit.
-* `RESQUE_TERM_TIMEOUT` - By default you have a few seconds to handle `ResqueAdmin::TermException` in your job. `RESQUE_TERM_TIMEOUT` and `RESQUE_PRE_SHUTDOWN_TIMEOUT` must be lower than the [heroku dyno timeout](https://devcenter.heroku.com/articles/limits#exit-timeout).
+* `RESQUE_TERM_TIMEOUT` - By default you have a few seconds to handle `Resque::TermException` in your job. `RESQUE_TERM_TIMEOUT` and `RESQUE_PRE_SHUTDOWN_TIMEOUT` must be lower than the [heroku dyno timeout](https://devcenter.heroku.com/articles/limits#exit-timeout).
### Mysql::Error: MySQL server has gone away
If your workers remain idle for too long they may lose their MySQL connection. Depending on your version of Rails, we recommend the following:
@@ -527,26 +527,26 @@
The Front End
-------------
-ResqueAdmin comes with a Sinatra-based front end for seeing what's up with
+Resque comes with a Sinatra-based front end for seeing what's up with
your queue.
### Standalone
-If you've installed ResqueAdmin as a gem running the front end standalone is easy:
+If you've installed Resque as a gem running the front end standalone is easy:
$ resque-web
It's a thin layer around `rackup` so it's configurable as well:
$ resque-web -p 8282
-If you have a ResqueAdmin config file you want evaluated just pass it to
+If you have a Resque config file you want evaluated just pass it to
the script as the final argument:
$ resque-web -p 8282 rails_root/config/initializers/resque.rb
You can also set the namespace directly using `resque-web`:
@@ -557,64 +557,64 @@
$ resque-web -p 8282 -r localhost:6379:2
### Passenger
-Using Passenger? ResqueAdmin ships with a `config.ru` you can use. See
+Using Passenger? Resque ships with a `config.ru` you can use. See
Phusion's guide:
Apache: <https://www.phusionpassenger.com/library/deploy/apache/deploy/ruby/>
Nginx: <https://www.phusionpassenger.com/library/deploy/nginx/deploy/ruby/>
### Rack::URLMap
-If you want to load ResqueAdmin on a subpath, possibly alongside other
+If you want to load Resque on a subpath, possibly alongside other
apps, it's easy to do with Rack's `URLMap`:
``` ruby
require 'resque/server'
run Rack::URLMap.new \
"/" => Your::App.new,
- "/resque" => ResqueAdmin::Server.new
+ "/resque" => Resque::Server.new
```
Check `examples/demo/config.ru` for a functional example (including
HTTP basic auth).
### Rails 3
-You can also mount ResqueAdmin on a subpath in your existing Rails 3 app by adding `require 'resque/server'` to the top of your routes file or in an initializer then adding this to `routes.rb`:
+You can also mount Resque on a subpath in your existing Rails 3 app by adding `require 'resque/server'` to the top of your routes file or in an initializer then adding this to `routes.rb`:
``` ruby
-mount ResqueAdmin::Server.new, :at => "/resque"
+mount Resque::Server.new, :at => "/resque"
```
-ResqueAdmin vs DelayedJob
+Resque vs DelayedJob
--------------------
-How does ResqueAdmin compare to DelayedJob, and why would you choose one
+How does Resque compare to DelayedJob, and why would you choose one
over the other?
-* ResqueAdmin supports multiple queues
+* Resque supports multiple queues
* DelayedJob supports finer grained priorities
-* ResqueAdmin workers are resilient to memory leaks / bloat
+* Resque workers are resilient to memory leaks / bloat
* DelayedJob workers are extremely simple and easy to modify
-* ResqueAdmin requires Redis
+* Resque requires Redis
* DelayedJob requires ActiveRecord
-* ResqueAdmin can only place JSONable Ruby objects on a queue as arguments
+* Resque can only place JSONable Ruby objects on a queue as arguments
* DelayedJob can place _any_ Ruby object on its queue as arguments
-* ResqueAdmin includes a Sinatra app for monitoring what's going on
+* Resque includes a Sinatra app for monitoring what's going on
* DelayedJob can be queried from within your Rails app if you want to
add an interface
If you're doing Rails development, you already have a database and
ActiveRecord. DelayedJob is super easy to setup and works great.
GitHub used it for many months to process almost 200 million jobs.
-Choose ResqueAdmin if:
+Choose Resque if:
* You need multiple queues
* You don't care / dislike numeric priorities
* You don't need to persist every Ruby object ever
* You have potentially huge queues
@@ -630,21 +630,21 @@
* Your queue stays small and nimble
* There is not a lot failure / chaos
* You want to easily throw anything on the queue
* You don't want to setup Redis
-In no way is ResqueAdmin a "better" DelayedJob, so make sure you pick the
+In no way is Resque a "better" DelayedJob, so make sure you pick the
tool that's best for your app.
-ResqueAdmin Dependencies
+Resque Dependencies
-------------------
$ gem install bundler
$ bundle install
-Installing ResqueAdmin
+Installing Resque
-----------------
### In a Rack app, as a gem
First install the gem.
@@ -659,11 +659,11 @@
Now start your application:
rackup config.ru
-That's it! You can now create ResqueAdmin jobs from within your app.
+That's it! You can now create Resque jobs from within your app.
To start a worker, create a Rakefile in your app's root (or add this
to an existing Rakefile):
``` ruby
@@ -699,11 +699,11 @@
Now start your application:
$ ./script/server
-That's it! You can now create ResqueAdmin jobs from within your app.
+That's it! You can now create Resque jobs from within your app.
To start a worker, add this to your Rakefile in `RAILS_ROOT`:
``` ruby
require 'resque/tasks'
@@ -719,11 +719,11 @@
### In a Rails 2.x app, as a plugin
$ ./script/plugin install git://github.com/resque/resque
-That's it! ResqueAdmin will automatically be available when your Rails app
+That's it! Resque will automatically be available when your Rails app
loads.
To start a worker:
$ QUEUE=* rake environment resque:work
@@ -747,11 +747,11 @@
Now start your application:
$ rails server
-That's it! You can now create ResqueAdmin jobs from within your app.
+That's it! You can now create Resque jobs from within your app.
To start a worker, add this to a file in `lib/tasks` (ex:
`lib/tasks/resque.rake`):
``` ruby
@@ -767,20 +767,20 @@
Configuration
-------------
-You may want to change the Redis host and port ResqueAdmin connects to, or
+You may want to change the Redis host and port Resque connects to, or
set various other options at startup.
-ResqueAdmin has a `redis` setter which can be given a string or a Redis
-object. This means if you're already using Redis in your app, ResqueAdmin
+Resque has a `redis` setter which can be given a string or a Redis
+object. This means if you're already using Redis in your app, Resque
can re-use the existing connection.
-String: `ResqueAdmin.redis = 'localhost:6379'`
+String: `Resque.redis = 'localhost:6379'`
-Redis: `ResqueAdmin.redis = $redis`
+Redis: `Resque.redis = $redis`
For our rails app we have a `config/initializers/resque.rb` file where
we load `config/resque.yml` by hand and set the Redis information
appropriately.
@@ -797,11 +797,11 @@
``` ruby
rails_root = ENV['RAILS_ROOT'] || File.dirname(__FILE__) + '/../..'
rails_env = ENV['RAILS_ENV'] || 'development'
resque_config = YAML.load_file(rails_root + '/config/resque.yml')
-ResqueAdmin.redis = resque_config[rails_env]
+Resque.redis = resque_config[rails_env]
```
Easy peasy! Why not just use `RAILS_ROOT` and `RAILS_ENV`? Because
this way we can tell our Sinatra app about the config file:
@@ -811,61 +811,61 @@
Also, you could disable jobs queueing by setting 'inline' attribute.
For example, if you want to run all jobs in the same process for cucumber, try:
``` ruby
-ResqueAdmin.inline = ENV['RAILS_ENV'] == "cucumber"
+Resque.inline = ENV['RAILS_ENV'] == "cucumber"
```
Plugins and Hooks
-----------------
For a list of available plugins see
<http://wiki.github.com/resque/resque/plugins>.
-If you'd like to write your own plugin, or want to customize ResqueAdmin
-using hooks (such as `ResqueAdmin.after_fork`), see
+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/resque/resque/blob/master/docs/HOOKS.md).
Namespaces
----------
-If you're running multiple, separate instances of ResqueAdmin you may want
+If you're running multiple, separate instances of Resque you may want
to namespace the keyspaces so they do not overlap. This is not unlike
the approach taken by many memcached clients.
This feature is provided by the [redis-namespace][rs] library, which
-ResqueAdmin uses by default to separate the keys it manages from other keys
+Resque uses by default to separate the keys it manages from other keys
in your Redis server.
-Simply use the `ResqueAdmin.redis.namespace` accessor:
+Simply use the `Resque.redis.namespace` accessor:
``` ruby
-ResqueAdmin.redis.namespace = "resque:GitHub"
+Resque.redis.namespace = "resque:GitHub"
```
We recommend sticking this in your initializer somewhere after Redis
is configured.
Demo
----
-ResqueAdmin ships with a demo Sinatra app for creating jobs that are later
+Resque ships with a demo Sinatra app for creating jobs that are later
processed in the background.
Try it out by looking at the README, found at `examples/demo/README.markdown`.
Monitoring
----------
### god
-If you're using god to monitor ResqueAdmin, we have provided example
+If you're using god to monitor Resque, we have provided example
configs in `examples/god/`. One is for starting / stopping workers,
the other is for killing workers that have been running too long.
### monit
@@ -881,11 +881,11 @@
Development
-----------
-Want to hack on ResqueAdmin?
+Want to hack on Resque?
First clone the repo and run the tests:
git clone git://github.com/resque/resque.git
cd resque
@@ -915,10 +915,10 @@
Read [CONTRIBUTING.md](CONTRIBUTING.md) first.
Once you've made your great commits:
-1. [Fork][1] ResqueAdmin
+1. [Fork][1] Resque
2. Create a topic branch - `git checkout -b my_branch`
3. Push to your branch - `git push origin my_branch`
4. Create a [Pull Request](http://help.github.com/pull-requests/) from your branch
5. That's it!