aiaio / active_resource_throttle

A throttler for ActiveResource requests.

This URL has Read+Write access

active_resource_throttle / README.rdoc
raw normal view history
696aff6f » aiaio 2008-12-16 initial commit 1 = ActiveResource Throttle
2
80867c5f » aiaio 2009-05-07 Updated rate 3 A rate limiter for ActiveResource requests.
696aff6f » aiaio 2008-12-16 initial commit 4
5 == DESCRIPTION:
6
7 ===Problem
8 You're writing a library to consume a RESTful web service. That service publishes
9 a throttle limit. So you need to throttle your requests to prevent the dreaded 503.
10
11 ===Solution
12 ActiveResource Throttle adds request throttling to ActiveResource. Specify the limits in your ActiveResource base class, and no longer will your client code have to worry about the number and frequency of its requests.
13
14 ==INSTALL:
15
16 gem sources -a http://gems.github.com
17 gem install aiaio-active_resource_throttle
18
19 == USAGE:
20
21 require "active_resource_throttle"
22
23 class MyResource < ActiveResource::Base
24 include ActiveResourceThrottle
25 self.site = "http://example.com/api/"
26 throttle(:interval => 60, :requests => 20, :sleep_interval => 10)
27 end
28
29 class Person < MyResource; end
30 class Post < MyResource; end
31
32
33 1. Require activeresource_throttle.
34 2. Include ActiveResourceThrottle in the ActiveResource class. If you're creating a library to access several resources, <b>it's necessary to create a generic base class for the api</b> you're accessing. Specify the site, login credentials, and throttle, and then subclass the base class for the various resources. Note that <b>the throttle will work across subclasses</b>.
35 3. Invoke the #throttle class method with the required options *interval* and *requests*. You may also specify a *sleep_interval*. The settings in the example code above will allow for a maximum of 20 requests per minute. When that limit is reached, requests will be paused for 10 seconds.
36
37 == ISSUES:
38
39 ActiveResource Throttle will not work properly across multiple instances of ActiveResource (e.g., in a Rails application with more than one Mongrel). At the moment, it should be used in single-process scripts. Also, the gem is not yet threadsafe.
40
80867c5f » aiaio 2009-05-07 Updated rate 41 Expect a threadsafe release in future versions.