README.rdoc in glutton_ratelimit-0.1.0 vs README.rdoc in glutton_ratelimit-0.2.0
- old
+ new
@@ -1,125 +1,130 @@
-= glutton_ratelimit
-
-A Ruby library for limiting the number of times a method can be invoked within a specified time period.
-
-The rate-limiting is simple if somewhat naïve. Throttled methods are blocked using sleep.
-
-== Use Cases
-
-You might wish to use this library to throttle code that:
-
-* Accesses a 3rd-party API that imposes a maximum rate-limit.
-* Scrapes data from any website where rapid repeated access is banned.
-
-For example, EchoNest API requests need to be limited to 120 every minute.
-
-== Types of Limiting
-
-There are two types of rate limiting provided by this library:
-
-* Bursty Token Bucket Limiting (GluttonRatelimit::BurstyTokenBucket)
-* Average Throttle Limiting (GluttonRatelimit::AveragedThrottle)
-
-=== Bursty Token Bucket
-
-If executions are limited to n times per m seconds then:
-
-1. n executions will be allowed immediately.
-2. Before the next execution the process will sleep for the remainder of the m second time period.
-3. The process is repeated.
-
-The amount of time slept in step 2 will depend on how long the n executions took in step 1.
-
-=== Average Throttle
-
-If executions are limited to n times per m seconds then:
-
-1. The first execution will occur immediately.
-2. Before each of the remaining n-1 executions the process will attempt to sleep so that the executions are evenly spaced within the m second time period.
-3. The process is repeated.
-
-The amount of time slept before each execution will depend on the time period m and the average elapsed time of each execution.
-
-== Instance Method Limiting Example
-
-The rate_limit method can be used at the end of a class definition to limit specific instance methods.
-
- class LimitInstanceMethod
- # The class must be extended to permit limiting.
- extend GluttonRatelimit
-
- def initialize
- @start = Time.now
- end
-
- def limit_me
- puts "#{Time.now - @start}"
- end
-
- # Throttle the limit_me method to six executions every six seconds.
- rate_limit :limit_me, 6, 6
- end
-
- t = LimitInstanceMethod.new
-
- 10.times { t.limit_me }
-
-When using the rate_limit method the limiting defaults to GluttonRatelimit::AveragedThrottle. Token Bucket limiting can also be specified:
-
- rate_limite :limit_me, 6, 6, GluttonRatelimit::BurstyTokenBucket
-
-== Simple Manual Limiting Example
-
-Chunks of code can also be manually throttled using the wait method of a specific GluttonRatelimit object.
-
- # Maximum of twelve executions every five seconds.
- rl = GluttonRatelimit::BurstyTokenBucket.new 12, 5
-
- 25.times do
- # BurstyTokenBucket will allow for a full burst of executions followed by a pause.
- rl.wait
- # Simulating a constant-time task:
- sleep 0.1
- end
-
- # Maximum of six executions every six seconds.
- rl = GluttonRatelimit::AveragedThrottle.new 6, 6
- 13.times do
- # AverageThrottle will attempt to evenly space executions within the allowed period.
- rl.wait
- # Simulating a 0 to 1 second random-time task:
- sleep rand
- end
-
-== More Examples
-
-More examples can be found within the examples folder.
-
-== Warnings
-
-Before using the library you should be aware of the following warnings.
-
-=== Short Tasks and AveragedThrottle
-
-The inaccuracy of Ruby's sleep method may cause timing issues with the AveragedThrottle limiting. Specifically, the limiting accuracy may be slightly-off when trying to rate-limit quick methods (sub-millisecond tasks).
-
-See: http://codeidol.com/other/rubyckbk/Date-and-Time/Waiting-a-Certain-Amount-of-Time
-
-It is recommend that you use the BurstyTokenBucket limiting when throttling very short tasks.
-
-=== Naive Throttling
-
-As mentioned above, throttling is accomplish by blocking script execution using sleep. There is no support for dropping or queuing throttled method invocations.
-
-This library is not thread safe.
-
-== Thanks
-
-Some of the algorithms were inspired by these discussions:
-
-* http://stackoverflow.com/questions/667508/whats-a-good-rate-limiting-algorithm
-* http://stackoverflow.com/questions/1407113/throttling-method-calls-to-m-requests-in-n-seconds
-
-== License
-
+= glutton_ratelimit
+
+A Ruby library for limiting the number of times a method can be invoked within a specified time period.
+
+The rate-limiting is simple if somewhat naïve. Throttled methods are blocked using sleep.
+
+== Use Cases
+
+You might wish to use this library to throttle code that:
+
+* Accesses a 3rd-party API that imposes a maximum rate-limit.
+* Scrapes data from any website where rapid repeated access is banned.
+
+For example, EchoNest API requests need to be limited to 120 every minute.
+
+== Installation
+
+ sudo gem install glutton_ratelimit
+
+The gem is hosted at: http://rubygems.org/gems/glutton_ratelimit
+
+== Types of Limiting
+
+There are two types of rate limiting provided by this library:
+
+* Bursty Token Bucket Limiting (GluttonRatelimit::BurstyTokenBucket)
+* Average Throttle Limiting (GluttonRatelimit::AveragedThrottle)
+
+=== Bursty Token Bucket
+
+If executions are limited to n times per m seconds then:
+
+1. n executions will be allowed immediately.
+2. Before the next execution the process will sleep for the remainder of the m second time period.
+3. The process is repeated.
+
+The amount of time slept in step 2 will depend on how long the n executions took in step 1.
+
+=== Average Throttle
+
+If executions are limited to n times per m seconds then:
+
+1. The first execution will occur immediately.
+2. Before each of the remaining n-1 executions the process will attempt to sleep so that the executions are evenly spaced within the m second time period.
+3. The process is repeated.
+
+The amount of time slept before each execution will depend on the time period m and the average elapsed time of each execution.
+
+== Instance Method Limiting Example
+
+The rate_limit method can be used at the end of a class definition to limit specific instance methods.
+
+ class LimitInstanceMethod
+ # The class must be extended to permit limiting.
+ extend GluttonRatelimit
+
+ def initialize
+ @start = Time.now
+ end
+
+ def limit_me
+ puts "#{Time.now - @start}"
+ end
+
+ # Throttle the limit_me method to six executions every six seconds.
+ rate_limit :limit_me, 6, 6
+ end
+
+ t = LimitInstanceMethod.new
+
+ 10.times { t.limit_me }
+
+When using the rate_limit method the limiting defaults to GluttonRatelimit::AveragedThrottle. Token Bucket limiting can also be specified:
+
+ rate_limite :limit_me, 6, 6, GluttonRatelimit::BurstyTokenBucket
+
+== Simple Manual Limiting Example
+
+Chunks of code can also be manually throttled using the wait method of a specific GluttonRatelimit object.
+
+ # Maximum of twelve executions every five seconds.
+ rl = GluttonRatelimit::BurstyTokenBucket.new 12, 5
+ # BurstyTokenBucket will allow for a full burst of executions followed by a pause.
+
+ rl.times(25) do
+ # Simulating a constant-time task:
+ sleep 0.1
+ end
+
+ # Maximum of six executions every six seconds.
+ rl = GluttonRatelimit::AveragedThrottle.new 6, 6
+ # AverageThrottle will attempt to evenly space executions within the allowed period.
+
+ rl.times(13) do
+ # Simulating a 0 to 1 second random-time task:
+ sleep rand
+ end
+
+== More Examples
+
+More examples can be found within the examples folder.
+
+== Warnings
+
+Before using the library you should be aware of the following warnings.
+
+=== Short Tasks and AveragedThrottle
+
+The inaccuracy of Ruby's sleep method may cause timing issues with the AveragedThrottle limiting. Specifically, the limiting accuracy may be slightly-off when trying to rate-limit quick methods (sub-millisecond tasks).
+
+See: http://codeidol.com/other/rubyckbk/Date-and-Time/Waiting-a-Certain-Amount-of-Time
+
+It is recommend that you use the BurstyTokenBucket limiting when throttling very short tasks.
+
+=== Naive Throttling
+
+As mentioned above, throttling is accomplish by blocking script execution using sleep. There is no support for dropping or queuing throttled method invocations.
+
+This library is not thread safe.
+
+== Thanks
+
+Some of the algorithms were inspired by these discussions:
+
+* http://stackoverflow.com/questions/667508/whats-a-good-rate-limiting-algorithm
+* http://stackoverflow.com/questions/1407113/throttling-method-calls-to-m-requests-in-n-seconds
+
+== License
+
This is free and unencumbered software released into the public domain. See LICENSE for details.
\ No newline at end of file