Skip to content
Newer
Older
100644 103 lines (75 sloc) 6 KB
ea707f4 @danielsdeleo Getting started
authored
1 = Qusion
559f975 @danielsdeleo nitpicking
authored
2 Qusion makes AMQP[http://github.com/tmm1/amqp] work with your webserver with no fuss. It's a simple library/plugin with three features:
3 * A set of monkey patches that sets up the required callbacks and/or worker threads so that AMQP will work with Passenger, Thin, or Mongrel. WEBrick, SCGI, and Evented Mongrel are experimentally supported, but not heavily tested.
23a8096 @danielsdeleo How to use the channel pools, a note on fixes that could be helpful.
authored
4 * A Channel Pool. You can cause problems for yourself if you create new channels (with MQ.new) for every request. The pool sets up a few of these when your app starts and reuses them.
ab9a0f4 @danielsdeleo Explain config/amqp.yml and other options, show usage of Qusion.start
authored
5 * YAML configuration files. If you're using Rails or Merb, create config/amqp.yml, then fill in the details for development, test, and production. Use Qusion.start() in your environment.rb file and you're good to go.
ea707f4 @danielsdeleo Getting started
authored
6
5912732 @danielsdeleo Discuss other options for queueing/background jobs in README
authored
7 = Before You Start
8 Qusion makes it easy to just install the plugin and start using AMQP in your application. But there are many ways to use background jobs within a Rails app, so it's worth taking some time to consider the tradeoffs of each approach.
9
10 * If your background job needs are simple and you're using a relational database, Delayed::Job[http://github.com/tobi/delayed_job/] lets you schedule background tasks through the database. You won't need to run another application (the AMQP Broker) to keep your app running.
11 * The 0.6.x version of the ruby amqp library may drop messages when the AMQP broker goes down. Pivotal Labs has discussed this problem on their blog[http://pivots.pivotallabs.com/users/will/blog/articles/966-how-to-not-test-rabbitmq-part-1]. This issue will likely be addressed in the 0.7.0 release of amqp, but can be avoided entirely using a synchronous amqp library such as bunny[http://github.com/celldee/bunny]. For a ready-made background job solution using Bunny to publish jobs to the queue, see Minion[http://github.com/orionz/minion/].
12 * Qusion runs EventMachine in a separate thread on Phusion Passenger, Mongrel, and other non-evented servers. There are some inefficiencies in Ruby 1.8's threading model that make running EM in a thread quite slow. Joe Damato and Aman Gupta have created a patch[http://github.com/ice799/matzruby/tree/heap_stacks] for the problem which is included in an experimental branch of REE. You can learn more about the patch from Phusion's Blog[http://blog.phusion.nl/2009/12/15/google-tech-talk-on-ruby-enterprise-edition/].
13
ea707f4 @danielsdeleo Getting started
authored
14 = Getting Started
a7618f7 @danielsdeleo Install as a plugin, use Configuration#after_initialize
authored
15 First you'll need the amqp library and a working RabbitMQ installation. This entails:
16 * Install Erlang for your platform
17 * Install RabbitMQ for your platform
18 * (sudo) gem install amqp
19 Ezmobius has a good walk-through on the readme for nanite[http://github.com/ezmobius/nanite/] if you haven't done this yet.
20 == Install Qusion
21 Start by installing Qusion as a plugin:
23a8096 @danielsdeleo How to use the channel pools, a note on fixes that could be helpful.
authored
22
a7618f7 @danielsdeleo Install as a plugin, use Configuration#after_initialize
authored
23 script/plugin install git://github.com/danielsdeleo/qusion.git
24
25 Next, in your config/environment.rb, add something like:
ab9a0f4 @danielsdeleo Explain config/amqp.yml and other options, show usage of Qusion.start
authored
26
a7618f7 @danielsdeleo Install as a plugin, use Configuration#after_initialize
authored
27 # Add eventmachine and amqp gems to config.gem to get config.gem goodies:
28 config.gem "eventmachine"
29 config.gem "amqp"
30
31 # Start AMQP after rails loads:
32 config.after_initialize do
33 Qusion.start # no options needed if you're using config/amqp.yml or the default settings.
34 end
ea707f4 @danielsdeleo Getting started
authored
35
36 And that's it! This will set up AMQP for any ruby app server (tested on mongrel, thin, and passenger). Now, you can use all of AMQP's functionality as normal. In your controllers or models, you might have:
37
38 MQ.new.queue("my-work-queue").publish("do work, son!")
39
40 and it should just work.
41
23a8096 @danielsdeleo How to use the channel pools, a note on fixes that could be helpful.
authored
42 = Channel Pools
43 It's considered bad practice to use MQ.new over and over, as it creates a new AMQP channel, and that creates a new Erlang process in RabbitMQ. Erlang processes are super light weight, but you'll be wasting them and causing the Erlang VM GC headaches if you create them wantonly. So don't do that. Instead, use the channel pool provided by Qusion. It's simple: wherever you'd normally put MQ.new, just replace it with Qusion.channel. Examples:
44
45 # Create a queue:
46 Qusion.channel.queue("my-worker-queue")
47 # Topics:
48 Qusion.channel.topic("my-topic-exchange")
49 # etc.
50
51 This feature is a bit experimental, so the optimal pool size isn't known yet. The default is 5. You can change it by adding something like the following to your environment.rb:
52
53 Qusion.channel_pool_size(3)
54
ab9a0f4 @danielsdeleo Explain config/amqp.yml and other options, show usage of Qusion.start
authored
55 = Configuration
449e1bd @danielsdeleo tweak the readme
authored
56 If you're using rails or merb, you can put your AMQP server details in config/amqp.yml and Qusion will load it when you call Qusion.start(). Example:
57
58 # Put this in config/amqp.yml
ab9a0f4 @danielsdeleo Explain config/amqp.yml and other options, show usage of Qusion.start
authored
59 development:
60 host: localhost
61 port: 5672
62 user: guest
63 pass: guest
64 vhost: /
65 timeout: 3600
66 logging: false
67 ssl: false
68
69 test:
70 host: localhost
71 port: 5672
72 ...
73
74 production:
75 host: localhost
76 port: 5672
77 ...
78
79 If you're too hardcore for rails or merb (maybe you're using Sinatra or Ramaze), you can still use a YAML config file, but there's no support for different environments. So do something like this:
658f19e @danielsdeleo Configuration in config/amqp.yml coming soon.
authored
80
ab9a0f4 @danielsdeleo Explain config/amqp.yml and other options, show usage of Qusion.start
authored
81 # Tell Qusion where your config file is:
82 Qusion.start("/path/to/amqp.yml")
83
84 # Your configuration looks like this:
85 application:
86 host: localhost
87 port: 5672
88 ...
89
90 If you just want to get started without configuring anything, Qusion.start() will use the default options if it can't find a config file. And, finally, you can give options directly to Qusion.start() like this:
91
92 Qusion.start(:host => "my-amqp-broker.mydomain.com", :user => "me", :pass => "am_I_really_putting_this_in_VCS?")
93
94
559f975 @danielsdeleo nitpicking
authored
95 = Bugs? Hacking?
96 If you find any bugs, or feel the need to add a feature, fork away. You can also contact me directly via the email address in my profile if you have any quesions.
ea707f4 @danielsdeleo Getting started
authored
97
4b117a0 @danielsdeleo A shout out for tmm1
authored
98 = Shouts
559f975 @danielsdeleo nitpicking
authored
99 * Qusion's code for Phusion Passenger's starting_worker_process event was originally posted by Aman Gupta (tmm1[http://github.com/tmm1]) on the AMQP list[http://groups.google.com/group/ruby-amqp]
100 * Brightbox's Warren[http://github.com/brightbox/warren] library provides some similar functionality. It doesn't support webserver-specific EventMachine setup, but it does have built-in encryption and support for the synchronous (non-EventMachine) Bunny[http://github.com/celldee/bunny] AMQP client.
4b117a0 @danielsdeleo A shout out for tmm1
authored
101
ea707f4 @danielsdeleo Getting started
authored
102 dan@kallistec.com
Something went wrong with that request. Please try again.