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

SYNOPSIS
      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" },
        # ...
      );

      while (my $some_item = shift @work) {
        if (my $delay = $ctrl->delay) {
          # Delayed $delay seconds.
          sleep $delay;
        } else {
          # No delay.
          $some_item->()
        }
      }

      # Clear the event history if it's stale:
      $ctrl->expire;

      # Clear the event history unconditionally:
      $ctrl->clear;

DESCRIPTION
    This is a generic rate-limiter object, implementing the math described
    in <http://www.perl.com/pub/2004/11/11/floodcontrol.html> in lightweight
    objects.

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

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

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

  clear
      $ctrl->clear;

    Clears the event history.

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

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

    When called, a new event timestamp is recorded; if we've exceeded our
    limit, the current delay (in possibly-fractional seconds) until the
    event is allowed is returned.

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

  events
    Returns the events limit the object was constructed with.

  expire
      $ctrl->expire;

    Clears the event history if the last seen event is outside of our time
    window.

    (You're not required to call "expire()", but it can be useful to force a
    cleanup.)

  seconds
    Returns the seconds limit the object was constructed with.

AUTHOR
    Jon Portnoy <avenj@cobaltirc.org>

    Based on the math from Algorithm::FloodControl as described in an
    article written by the author:
    <http://www.perl.com/pub/2004/11/11/floodcontrol.html>

    Licensed under the same terms as Perl.