glutton_ratelimit 0.2.0 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b8a1b9b8b47cbcc4573a67ec3af28dad39ed240e61e85729d2773645cb109eef
+  data.tar.gz: c56bf652f9348c46aa2d45f94d1159316a94a8d37fad53aea15eae4fa00e41bd
+SHA512:
+  metadata.gz: 61ff459ec83219910e727aaa837347bdb39604f23aa0bf49be2c19ad9b6ab15dbae60d2ea6e3268ec4a272fb411f24c29957ce95cc299e210662d7246ce9b691
+  data.tar.gz: e56a2767ff91f37b28990f6e54ff977481cf0eccbca5da99c345151fd254046e635dd52ab201d2a18a39b828b18f047b0e5f1ee944d4585b2cbaddcd3312f1c7

data/.document

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

data/.github/workflows/ruby.yml

@@ -0,0 +1,20 @@
+name: Ruby
+
+on: [push]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Set up Ruby 2.6
+      uses: actions/setup-ruby@v1
+      with:
+        ruby-version: 2.6.x
+    - name: Build and test with Rake
+      run: |
+        gem install bundler
+        bundle install --jobs 4 --retry 3
+        bundle exec rake

data/.ruby-version

@@ -0,0 +1 @@
+2.5.7

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 1.9
+  - 2.0
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4
+  - 2.5

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem 'jeweler'
+gem 'test-unit'

data/Gemfile.lock

@@ -0,0 +1,63 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.4.0)
+    builder (3.2.4)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    faraday (0.9.2)
+      multipart-post (>= 1.2, < 3)
+    git (1.5.0)
+    github_api (0.16.0)
+      addressable (~> 2.4.0)
+      descendants_tracker (~> 0.0.4)
+      faraday (~> 0.8, < 0.10)
+      hashie (>= 3.4)
+      mime-types (>= 1.16, < 3.0)
+      oauth2 (~> 1.0)
+    hashie (4.0.0)
+    highline (2.0.3)
+    jeweler (2.3.9)
+      builder
+      bundler
+      git (>= 1.2.5)
+      github_api (~> 0.16.0)
+      highline (>= 1.6.15)
+      nokogiri (>= 1.5.10)
+      psych
+      rake
+      rdoc
+      semver2
+    jwt (2.2.1)
+    mime-types (2.99.3)
+    mini_portile2 (2.4.0)
+    multi_json (1.14.1)
+    multi_xml (0.6.0)
+    multipart-post (2.1.1)
+    nokogiri (1.10.7)
+      mini_portile2 (~> 2.4.0)
+    oauth2 (1.4.2)
+      faraday (>= 0.8, < 2.0)
+      jwt (>= 1.0, < 3.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (>= 1.2, < 3)
+    power_assert (1.1.5)
+    psych (3.1.0)
+    rack (2.0.8)
+    rake (13.0.1)
+    rdoc (6.2.0)
+    semver2 (3.4.2)
+    test-unit (3.3.4)
+      power_assert
+    thread_safe (0.3.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  jeweler
+  test-unit
+
+BUNDLED WITH
+   2.1.1

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,130 +1,156 @@
-= 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.
+*NOTE:* This library is no longer under active development. Pull requests are, however, still being accepted.
+
+Shopify maintains a gem with similar functionality called {ruby-limiter}[https://github.com/Shopify/limiter].
+
+== 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.
+
+The 1.x.x version of the library is designed to work with Ruby 2.4+. Please use version 0.2.0 if you need to support an ealier version of Ruby.
+
+== 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
+
+    gem install glutton_ratelimit
+
+Or add the gem to your project Gemfile:
+
+    gem 'glutton_ratelimit'
+
+If you need to use this gem with Ruby version 2.3 or ealier, use version 0.2.0 of the gem.
+
+== Types of Limiting
+
+There are two types of rate limiting provided by this library:
+
+* Average Throttle Limiting (GluttonRatelimit::AveragedThrottle) DEFAULT
+* Bursty Token Bucket Limiting (GluttonRatelimit::BurstyTokenBucket)
+
+=== Average Throttle (Default Mode)
+
+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.
+
+=== 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.
+
+== Instance Method Limiting Example
+
+The rate_limit method can be used at the end of a class definition to limit specific instance methods.
+
+    rate_limit :name_of_instance_method, number_of_executions, timeframe_in_seconds
+
+The specified instance method will be throlled to maintain an execution rate of:
+
+    timeframe_in_seconds / number_of_executions
+
+==== An example where the limit_me instance method of the RateLimitTest class is throttled:
+
+    class RateLimitTest
+      # 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 five executions every sixty seconds.
+      rate_limit :limit_me, 5, 60
+    end
+
+    t = RateLimitTest.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, 5, 60, GluttonRatelimit::BurstyTokenBucket
+
+== Simple Manual Limiting Example
+
+Chunks of code can also be manually throttled using the times 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.
+
+== Tests
+
+The tests integration/timing tests with a tolerance of 0.5 of a percent outside the expected timings.
+
+The tests can be run using:
+
+    bundle exec rake test
+
+== 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.