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 )