Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A minimalist queueing DSL for Beanstalk.

This branch is 0 commits ahead and 0 commits behind master

Merge pull request #7 from gvc/master

Small typo on README
latest commit 18a725d42c
Han Kessels authored April 18, 2012
Octocat-spinner-32 bin Change 'include Stalker' to 'extend' in bin/stalk March 28, 2012
Octocat-spinner-32 examples tabs to spaces March 11, 2011
Octocat-spinner-32 lib tabs to spaces April 12, 2011
Octocat-spinner-32 test tabs to spaces April 12, 2011
Octocat-spinner-32 .gitignore v0.2.1 May 13, 2010
Octocat-spinner-32 README.md Fixed typo in README April 18, 2012
Octocat-spinner-32 Rakefile v0.9.0 April 12, 2011
Octocat-spinner-32 VERSION v0.9.0 April 12, 2011
Octocat-spinner-32 stalker.gemspec v0.9.0 April 12, 2011
README.md

Stalker - a job queueing DSL for Beanstalk

Beanstalkd is a fast, lightweight queueing backend inspired by mmemcached. The Ruby Beanstalk client is a bit raw, however, so Stalker provides a thin wrapper to make job queueing from your Ruby app easy and fun.

Queueing jobs

From anywhere in your app:

require 'stalker'

Stalker.enqueue('email.send', :to => 'joe@example.com')
Stalker.enqueue('post.cleanup.all')
Stalker.enqueue('post.cleanup', :id => post.id)

Working jobs

In a standalone file, typically jobs.rb or worker.rb:

require 'stalker'
include Stalker

job 'email.send' do |args|
  Pony.send(:to => args['to'], :subject => "Hello there")
end

job 'post.cleanup.all' do |args|
  Post.all.each do |post|
    enqueue('post.cleanup', :id => post.id)
  end
end

job 'post.cleanup' do |args|
  Post.find(args['id']).cleanup
end

Running

First, make sure you have Beanstalkd installed and running:

$ sudo port install beanstalkd
$ beanstalkd

Stalker:

$ sudo gem install stalker

Now run a worker using the stalk binary:

$ stalk jobs.rb
Working 3 jobs: [ email.send post.cleanup.all post.cleanup ]
Working send.email (email=hello@example.com)
Finished send.email in 31ms

Stalker will log to stdout as it starts working each job, and then again when the job finishes including the ellapsed time in milliseconds.

Filter to a list of jobs you wish to run with an argument:

$ stalk jobs.rb post.cleanup.all,post.cleanup
Working 2 jobs: [ post.cleanup.all post.cleanup ]

In a production environment you may run one or more high-priority workers (limited to short/urgent jobs) and any number of regular workers (working all jobs). For example, two workers working just the email.send job, and four running all jobs:

$ for i in 1 2; do stalk jobs.rb email.send > log/urgent-worker.log 2>&1; done
$ for i in 1 2 3 4; do stalk jobs.rb > log/worker.log 2>&1; done

Error Handling

If you include an error block in your jobs definition, that block will be invoked when a worker encounters an error. You might use this to report errors to an external monitoring service:

error do |e, job, args|
  Exceptional.handle(e)
end

Before filter

If you wish to run a block of code prior to any job:

before do |job|
  puts "About to work #{job}"
end

Tidbits

  • Jobs are serialized as JSON, so you should stick to strings, integers, arrays, and hashes as arguments to jobs. e.g. don't pass full Ruby objects - use something like an ActiveRecord/MongoMapper/CouchRest id instead.
  • Because there are no class definitions associated with jobs, you can queue jobs from anywhere without needing to include your full app's environment.
  • If you need to change the location of your Beanstalk from the default (localhost:11300), set BEANSTALK_URL in your environment, e.g. export BEANSTALK_URL=beanstalk://example.com:11300/. You can specify multiple beanstalk servers, separated by whitespace or comma, e.g. export BEANSTALK_URL="beanstalk://b1.example.com:11300/, beanstalk://b2.example.com:11300/"
  • The stalk binary is just for convenience, you can also run a worker with a straight Ruby command: $ ruby -r jobs -e Stalker.work

Running the tests

If you wish to hack on Stalker, install these extra gems:

$ gem install contest mocha

Make sure you have a beanstalkd running, then run the tests:

$ ruby test/stalker_test.rb

Meta

Created by Adam Wiggins

Patches from Jamie Cobbett, Scott Water, Keith Rarick, Mark McGranaghan, Sean Walberg, Adam Pohorecki, Han Kessels

Heavily inspired by Minion by Orion Henry

Released under the MIT License: http://www.opensource.org/licenses/mit-license.php

https://github.com/han/stalker

Something went wrong with that request. Please try again.