= 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

This is free and unencumbered software released into the public domain. See LICENSE for details.