Skip to content
Newer
Older
100644 67 lines (38 sloc) 3.13 KB
95d09a0 @mperham Initial commit
authored Apr 10, 2011
1 girl_friday
2 ====================
3
2db509a @mperham Add completion callback support, doc update
authored Apr 12, 2011
4 Have a task you want to get done sometime soon but don't want to do it yourself? Give it to girl_friday! From wikipedia:
5
6 > The term Man Friday has become an idiom, still in mainstream usage, to describe an especially faithful servant or
7 > one's best servant or right-hand man. The female equivalent is Girl Friday. The title of the movie His Girl Friday
8 > alludes to it and may have popularized it.
95d09a0 @mperham Initial commit
authored Apr 10, 2011
9
10 girl_friday is a Ruby library for performing asynchronous tasks. Often times you don't want to block a web response by performing some task, like sending an email, so you can just use this gem to perform it in the background. It works with any Ruby application, including Rails 3 applications.
11
12
13 Installation
14 ------------------
15
2db509a @mperham Add completion callback support, doc update
authored Apr 13, 2011
16 We recommend using [JRuby 1.6+](http://jruby.org) or [Rubinius 2.0+](http://rubini.us) with girl_friday. Both are excellent options for executing Ruby these days.
95d09a0 @mperham Initial commit
authored Apr 10, 2011
17
18 gem install girl_friday
19
3d32a27 @mperham Update docs
authored Apr 16, 2011
20 girl_friday does not support Ruby 1.8 (MRI) because of its poor threading support. Ruby 1.9 will work reasonably well if you use gems that release the GIL for network I/O (mysql2 is a good example of this, do **not** use the original mysql gem).
95d09a0 @mperham Initial commit
authored Apr 10, 2011
21
22
23 Usage
24 --------------------
25
26 Put girl_friday in your Gemfile:
27
28 gem 'girl_friday'
29
2db509a @mperham Add completion callback support, doc update
authored Apr 13, 2011
30 In your Rails app, create a `config/initializers/girl_friday.rb` which defines your queues:
95d09a0 @mperham Initial commit
authored Apr 10, 2011
31
d805fdd @mperham Implement clean shutdown, currently synchronous. Should I implement
authored Apr 17, 2011
32 EMAIL_QUEUE = GirlFriday::WorkQueue.new(:user_email, :size => 3) do |msg|
95d09a0 @mperham Initial commit
authored Apr 10, 2011
33 UserMailer.registration_email(msg).deliver
34 end
d805fdd @mperham Implement clean shutdown, currently synchronous. Should I implement
authored Apr 18, 2011
35 IMAGE_QUEUE = GirlFriday::WorkQueue.new(:image_crawler, :size => 7) do |msg|
2db509a @mperham Add completion callback support, doc update
authored Apr 13, 2011
36 ImageCrawler.process(msg)
37 end
38
d805fdd @mperham Implement clean shutdown, currently synchronous. Should I implement
authored Apr 18, 2011
39 :size is the number of workers to spin up and defaults to 5. Keep in mind, ActiveRecord defaults to a connection pool size of 5 so if your workers are accessing the database you'll want to ensure that the connection pool is large enough by modifying `config/database.yml`.
95d09a0 @mperham Initial commit
authored Apr 10, 2011
40
41 In your controller action or model, you can call `#push(msg)`
42
2db509a @mperham Add completion callback support, doc update
authored Apr 13, 2011
43 EMAIL_QUEUE.push(:email => @user.email, :name => @user.name)
95d09a0 @mperham Initial commit
authored Apr 10, 2011
44
45 The msg parameter to push is just a Hash whose contents are completely up to you.
46
3d32a27 @mperham Update docs
authored Apr 17, 2011
47 Your message processing block should **not** access any instance data or variables outside of the block. That's shared mutable state and dangerous to touch! I also strongly recommend your queue processor block be **VERY** short, ideally just a method call or two. You can unit test those methods easily but not the processor block itself.
95d09a0 @mperham Initial commit
authored Apr 10, 2011
48
49
50 More Detail
51 --------------------
52
d805fdd @mperham Implement clean shutdown, currently synchronous. Should I implement
authored Apr 18, 2011
53 Please see the [girl_friday wiki](https://github.com/mperham/girl_friday/wiki) for more detail and advanced options and tuning. You'll find details on queue persistence with Redis, implementing clean shutdown, querying runtime metrics and SO MUCH MORE!
95d09a0 @mperham Initial commit
authored Apr 10, 2011
54
55
56 Thanks
57 --------------------
58
59 [Carbon Five](http://carbonfive.com), I write and maintain girl_friday on their clock.
60
61 This gem contains a copy of the Rubinius Actor API, modified to work on any Ruby VM. Thanks to Evan Phoenix, MenTaLguY and the Rubinius project for permission to use and distribute this code.
62
63
64 Author
65 --------------------
66
67 Mike Perham, [@mperham](https://twitter.com/mperham), [mikeperham.com](http://mikeperham.com)
Something went wrong with that request. Please try again.