glutton_ratelimit 0.1.0 → 0.2.0

data/.document

@@ -1,5 +1,5 @@
-README.rdoc
-lib/**/*.rb
-bin/*
-features/**/*.feature
-LICENSE
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/LICENSE

@@ -1,24 +1,24 @@
-This is free and unencumbered software released into the public domain.
-
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
-
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
 For more information, please refer to <http://unlicense.org/>

data/README.rdoc

@@ -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.

data/Rakefile

@@ -1,52 +1,52 @@
-require 'rubygems'
-require 'rake'
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "glutton_ratelimit"
-    gem.summary = %Q{Simple Ruby library for self-imposed rater-limiting.}
-    gem.description = %Q{A Ruby library for limiting the number of times a method can be invoked within a specified time period.}
-    gem.email = "stungeye@gmail.com"
-    gem.homepage = "http://github.com/stungeye/glutton_ratelimit"
-    gem.authors = ["Wally Glutton"]
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
-end
-
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
-end
-
-begin
-  require 'rcov/rcovtask'
-  Rcov::RcovTask.new do |test|
-    test.libs << 'test'
-    test.pattern = 'test/**/test_*.rb'
-    test.verbose = true
-  end
-rescue LoadError
-  task :rcov do
-    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
-  end
-end
-
-task :test => :check_dependencies
-
-task :default => :test
-
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "glutton_ratelimit #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "glutton_ratelimit"
+    gem.summary = %Q{Simple Ruby library for self-imposed rater-limiting.}
+    gem.description = %Q{A Ruby library for limiting the number of times a method can be invoked within a specified time period.}
+    gem.email = "stungeye@gmail.com"
+    gem.homepage = "http://github.com/stungeye/glutton_ratelimit"
+    gem.authors = ["Wally Glutton"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "glutton_ratelimit #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/examples/limit_instance_methods.rb

@@ -1,34 +1,34 @@
-require 'rubygems'
-require 'glutton_ratelimit'
-
-class LimitInstanceMethods
-  extend GluttonRatelimit
-    
-  def initialize
-    @start = Time.now
-  end
-  
-  def limit_me
-    puts "#{Time.now - @start}"
-    sleep 0.001
-  end
-  
-  def cap_me
-    puts "#{Time.now - @start}"
-    sleep 0.001
-  end
-  
-  rate_limit :limit_me, 6, 6
-  rate_limit :cap_me, 6, 6, GluttonRatelimit::BurstyTokenBucket
-end
-
-t = LimitInstanceMethods.new
-
-puts "Six requests every 6 seconds (Averaged): "
-13.times { t.limit_me }
-puts "Six requests every 6 seconds (Bursty): "
-13.times { t.cap_me }
-
-# In both cases:
-# The 7th execution should occur after 6 seconds after the first.
+require 'rubygems'
+require 'glutton_ratelimit'
+
+class LimitInstanceMethods
+  extend GluttonRatelimit
+    
+  def initialize
+    @start = Time.now
+  end
+  
+  def limit_me
+    puts "#{Time.now - @start}"
+    sleep 0.001
+  end
+  
+  def cap_me
+    puts "#{Time.now - @start}"
+    sleep 0.001
+  end
+  
+  rate_limit :limit_me, 6, 6
+  rate_limit :cap_me, 6, 6, GluttonRatelimit::BurstyTokenBucket
+end
+
+t = LimitInstanceMethods.new
+
+puts "Six requests every 6 seconds (Averaged): "
+13.times { t.limit_me }
+puts "Six requests every 6 seconds (Bursty): "
+13.times { t.cap_me }
+
+# In both cases:
+# The 7th execution should occur after 6 seconds after the first.
 # The 13th execution should occur after 12 seconds after the first.