Algorithm-TokenBucket

 view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

- count($)

    This method removes _N_ (or all if there are fewer than _N_ available)
    tokens from the bucket. It does not return a meaningful value.

- until($)

    This method returns the number of seconds until _N_ tokens can be removed
    from the bucket. It is especially useful in multitasking environments like
    [POE](https://metacpan.org/pod/POE) where you cannot busy-wait. One can safely schedule the next
    `conform($N)` check in `until($N)` seconds instead of checking
    repeatedly.

    Note that `until()` does not take into account `burst size`. This means
    that a bucket will not conform to _N_ even after sleeping for `until($N)`
    seconds if _N_ is greater than `burst size`.

- get\_token\_count()

    Returns the current number of tokens in the bucket. This method may be

README.md  view on Meta::CPAN

Imagine a rate limiter for a mail sending application. We would like to
allow 2 mails per minute but no more than 20 mails per hour.

    my $rl1 = Algorithm::TokenBucket->new(2/60, 1);
    my $rl2 = Algorithm::TokenBucket->new(20/3600, 10);
        # "bursts" of 10 to ease the lag but $rl1 enforces
        # 2 per minute, so it won't flood

    while (my $mail = get_next_mail) {
        until ($rl1->conform(1) && $rl2->conform(1)) {
            busy_wait;
        }

        $mail->take_off;
        $rl1->count(1); $rl2->count(1);
    }

Now, let's fix the CPU-hogging example from ["SYNOPSIS"](#synopsis) using
the ["until($)"](#until) method.

    my $bucket = Algorithm::TokenBucket->new(100 / 3600, 5);

lib/Algorithm/TokenBucket.pm  view on Meta::CPAN

    $self->_token_flow;

    ($self->{_tokens} -= $size) < 0 and $self->{_tokens} = 0;
}

=item until($)

This method returns the number of seconds until I<N> tokens can be removed
from the bucket. It is especially useful in multitasking environments like
L<POE> where you cannot busy-wait. One can safely schedule the next
C<< conform($N) >> check in C<< until($N) >> seconds instead of checking
repeatedly.

Note that C<until()> does not take into account C<burst size>. This means
that a bucket will not conform to I<N> even after sleeping for C<< until($N) >>
seconds if I<N> is greater than C<burst size>.

=cut

sub until {

lib/Algorithm/TokenBucket.pm  view on Meta::CPAN

Imagine a rate limiter for a mail sending application. We would like to
allow 2 mails per minute but no more than 20 mails per hour.

    my $rl1 = Algorithm::TokenBucket->new(2/60, 1);
    my $rl2 = Algorithm::TokenBucket->new(20/3600, 10);
        # "bursts" of 10 to ease the lag but $rl1 enforces
        # 2 per minute, so it won't flood

    while (my $mail = get_next_mail) {
        until ($rl1->conform(1) && $rl2->conform(1)) {
            busy_wait;
        }

        $mail->take_off;
        $rl1->count(1); $rl2->count(1);
    }

Now, let's fix the CPU-hogging example from L</SYNOPSIS> using
the L</until($)> method.

    my $bucket = Algorithm::TokenBucket->new(100 / 3600, 5);