NAME

Algorithm::RateLimiter::TokenBucket - Loop-agnostic Token Bucket Rate Limiter

SYNOPSIS

use Algorithm::RateLimiter::TokenBucket;

# Limit to 500 KB/s
my $limiter = Algorithm::RateLimiter::TokenBucket->new( limit => 512_000 );

# In your main loop
while ( 1 ) {
    my $delta = 0.1; # Time elapsed since last tick
    $limiter->tick( $delta );

    my $can_send = $limiter->consume( 16384 );
    if ($can_send > 0) {
        # Send $can_send bytes
    }
}

DESCRIPTION

Algorithm::RateLimiter::TokenBucket implements the token bucket algorithm for rate limiting. It is specifically designed to be loop-agnostic, meaning it does not manage its own timers or background threads. Instead, you "drive" it by calling tick( ) with the amount of time that has passed.

This makes it ideal for integration into event loops (like IO::Async or Mojo::IOLoop) or high-performance network applications.

METHODS

new( limit = $bytes_per_second )>

Creates a new limiter. limit is optional and defaults to 0 (unlimited).

set_limit( $limit )

Dynamically updates the rate limit.

tick( $delta_seconds )

Adds new tokens to the bucket based on the time elapsed.

consume( $amount )

Attempts to consume $amount units (tokens) from the bucket. Returns the number of units actually consumed.

available( )

Returns the current number of tokens in the bucket.

AUTHOR

Sanko Robinson <sanko@cpan.org>

COPYRIGHT

Copyright (C) 2026 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.