Acme-Parataxis
view release on metacpan or search on metacpan
lib/Acme/Parataxis/RateLimiter.pod view on Meta::CPAN
=pod
=encoding utf8
=head1 NAME
Acme::Parataxis::RateLimiter - Token-Bucket Rate Limiter for Fibers
=head1 SYNOPSIS
use v5.40;
use Acme::Parataxis qw[async fiber];
use Acme::Parataxis::RateLimiter;
async {
my $limiter = Acme::Parataxis::RateLimiter->new( rate => 5, burst => 10 );
my @workers = map {
my $url = $_;
fiber {
$limiter->acquire; # parks when tokens are exhausted
fetch_url($url);
};
} @urls;
$_->await for @workers;
$limiter->stop; # required, or the run will never finish
};
=head1 DESCRIPTION
C<Acme::Parataxis::RateLimiter> provides an application-wide speed limit for operations interacting with external,
rate-limited services. Built on the classic token-bucket algorithm, the limiter starts holding C<burst> tokens. Each
request consumes tokens (one by default), while a background loop continuously refills the bucket at C<rate> tokens per
second up to the configured ceiling. When the bucket is depleted, calling C<acquire> parks the calling fiber until the
next token is credited.
The bucket itself is an L<Acme::Parataxis::Semaphore>, meaning C<acquire> is a standard C<down> operation. This
architecture guarantees zero polling overhead: parked fibers suspend cleanly in the scheduler, inherit
L<with_timeout|Acme::Parataxis/with_timeout> and cancellation token support, and automatically unregister if
interrupted.
Refills are driven by an internal L<Acme::Parataxis::Ticker> waking C<rate> times per second. Each tick calculates the
wall-clock duration elapsed since the last wake and credits all accrued whole tokens (carrying fractional remainders
over). Tokens only accumulate while the bucket is below C<burst>; an idle limiter stops topping up once full and will
never burst beyond its ceiling.
B<Crucial Lifecycle Rule>: Because a running limiter maintains background refill fibers, an unstopped limiter keeps the
scheduler run open indefinitely. Always call C<stop()> when the limiter is no longer needed.
=head1 BURST VS. SUSTAINED RATE
The C<burst> parameter governs how much traffic can be dispatched instantaneously:
=over
=item *
The bucket starts full. With C<< burst => 10 >>, the first 10 requests pass through instantly without waiting. Only the
11th request will park for a refill.
=item *
( run in 0.606 second using v1.01-cache-2.11-cpan-234fa220139 )