Object::RateLimiter - A flood control (rate limiter) object


  use Object::RateLimiter;

  my $ctrl = Object::RateLimiter->new(
    events  => 3,
    seconds => 5

  # Run some subs, as a contrived example;
  # no more than 3 in 5 seconds, per our constructor above:
  my @work = (
    sub { "foo" },  sub { "bar" },
    sub { "baz" },  sub { "cake" },
    # ...

  while (my $some_item = shift @work) {
    if (my $delay = $ctrl->delay) {
      # Delayed $delay (fractional) seconds.
      # (You might want Time::HiRes::sleep, or yield to event loop, etc)
      sleep $delay
    print $some_item->()

  # Clear the event history if it's stale:

  # Clear the event history unconditionally:

  # Same as calling ->delay:
  my $delayed = $ctrl->();


This is a generic rate-limiter object, implementing the math described in via light-weight array-type objects.

The algorithm is fairly simple; the article linked above contains an in-depth discussion by Vladi Belperchinov-Shabanski (CPAN:

  $delay =
      $oldest_timestamp + 
      ( $seen_events * $limit_secs / $event_limit ) 
    - time()

This module uses Time::HiRes to provide support for fractional seconds.

See Algorithm::FloodControl for a similar module with a functional interface & persistent on-disk storage features (for use with CGI applications).


  my $ctrl = Object::RateLimiter->new(
    events  => 3,
    seconds => 5

Constructs a new rate-limiter with a clean event history.

Accepts params as a list or a single HASH.



Clear the event history.


  my $new_ctrl = $ctrl->clone( events => 4 );

Clones an existing rate-limiter; new options can be provided, overriding previous settings.

The new limiter contains a clone of the event history; the old rate-limiter is left untouched.


  if (my $delay = $ctrl->delay) {
    sleep $delay;  # ... or do something else
  } else {
    # Not delayed.

  # Same as calling ->delay:
  my $delay = $ctrl->();

The delay() method determines if some work can be done now, or should wait.

When called, event timestamps are considered; if we have exceeded our limit, the delay in (possibly fractional) seconds until the event would be allowed is returned.

A return value of 0 indicates that the event does not need to wait.


Returns the events limit the object was constructed with.



Clears the event history if "is_expired" is true.

Returns true if "clear" was called.

(You're not required to call expire(), but it can be useful to save a little memory.)


  my $opts = $ctrl->export;
  # ... later, perhaps after storing/retrieving ...
  my $recreated = Object::RateLimiter->new($opts);

Exports the current state of the rate-limiter as a reference to a hash; the exported hash can be fed to "new" to recreate the rate-limiter.

This is useful if the rate-limiter's state must be stored persistently.


Returns true if the last seen event is outside of our time window (in other words, the event history is stale) or there is no event history.

Also see "expire"


Returns the seconds limit the object was constructed with.


Jon Portnoy <>

Based on the math from Algorithm::FloodControl as described in an article written by the author:

Licensed under the same terms as Perl.