NAME

Algorithm::LeakyBucket - Perl implementation of leaky bucket rate limiting

SYNOPSIS

 use Algorithm::LeakyBucket;
 my $bucket = Algorithm::LeakyBucket->new( ticks => 1, seconds => 1 ); # one per second

 while($something_happening)
 {
     if ($bucket->tick)
     {
         # allowed
         do_something();
	 # maybe decide to change limits?
	 $bucket->ticks(2);
	 $bucket->seconds(5);
     }
 }

CONSTRUCTOR

There are two required options to get the module to do anything useful. ticks and seconds set the number of ticks allowed per that time period. If ticks is 3 and seconds is 14, you will be able to run 3 ticks every 14 seconds. Optionally you can pass memcached_servers and memcached_key to distribute the limiting across multiple processes.

my $bucket = Algorithm::LeakyBucket->new( ticks => $ticks, seconds => $every_x_seconds,
                                 memcached_key => 'some_key',
                                 memcached_servers => [ { address => 'localhost:11211' } ] );

Implements leaky bucket as a rate limiter. While the code will do rate limiting for a single process, it was intended as a limiter for multiple processes. (But see the BUGS section)

The syntax of the memcached_servers argument should be the syntax expected by the local memcache module. If Cache::Memcached::Fast is installed, use its syntax, otherwise you can use the syntax for Cache::Memcached. If neither module is found it will use a locally defined set of vars internally to track rate limiting. Obviously this keeps the code from being used across processes.

This is an alpha version of the code. Some early bugs have been ironed out and its in produciton in places, so we would probably transition it to beta once we have seen it work for a bit.

BUGS

Probably some. There is a known bug where if you are in an infinite loop you could move faster than memcached could be updated remotely, so you'll likely at that point only bbe limted by the local counters. I'm not sure how im going to fix this yet as this is in early development.

TODO

Will need to look at including some actual tests im thinking. Maybe once we get more real usage out of this in our produciton environment some test cases will make themselves obvious.

SEE ALSO

http://en.wikipedia.org/wiki/Leaky_bucket

AUTHOR

Marcus Slagle, <marc.slagle@online-rewards.com>

COPYRIGHT AND LICENSE

Copyright (C) 2012 by Marcus Slagle

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.9 or, at your option, any later version of Perl 5 you may have available.