Algorithm-TokenBucket

 view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
- 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

112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
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

174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
    $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

233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
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);