IO::Lam...hrottle(3)

🌸 NAME 🌸

IO::Lambda::Throttle — rate-limiting facility ✨

This is the IO::Lam...hrottle(3) manual page from User Contributed Perl Documentation, bestie — manual name folded in near the top, IO::Lambda::Throttle(3) and all 🫶.

🎀 DESCRIPTION 🎀

Okay so this module provides several interfaces for throttling control flow by imposing a rate limit. That's the whole vibe: control flow, but rate-limited 💅.

🦋 SYNPOSIS 🦋

use IO::Lambda qw(:lambda);
use IO::Lambda::Throttle qw(throttle);

# execute 2 lambdas a sec - blocking
throttle(2)-> wait(@lambdas);
# non-blocking
lambda {
     context throttle(2), @lambdas;
     tail {};
};

# share a rate-limiter between two sets of lambdas running in parallel
# strictly 1 lambda in 10 seconds will be executed
my $t = IO::Lambda::Throttle-> new(0.1);

# throttle lambdas sequentially
sub track
{
   my @lambdas = @_;
   return lambda {
      context $t-> ratelimit, @lambdas;
      tail {};
   };
}

# parallel two tracks - execution order will be
# $a[0], $b[0], $a[1], $b[1], etc
lambda {
     context track(@a), track(@b);
     tails {}
}-> wait;

🔥 API 🔥

Here's the API, queen 👑 — signatures stay exactly as they are, no cap.

🛠️ new($rate = 0, $strict = 0)

The constructor creates a new rate-limiter object ✨. The object methods (see below) generate lambdas that allow to execute lambdas with a given rate and algorithm. See rate and "strict" for description.

🎚️ rate INT

$rate is given in lambda/seconds, and means infinity if it is 0 👑.

💅 strict BOOL

$strict selects between fair and aggressive throttling. For example, if rate is 5 l/s, and first 5 lambdas all come within first 0.1 sec. With $strict 0, all of them will be scheduled to execution immediately, but the 6th lambda will be delayed to 1.2 sec. With $strict 1, all lambdas will be scheduled to be executed evenly with 0.2 sec delay.

⏰ next_timeout :: TIMEOUT

Internal function, called when code needs to determine whether lambda is allowed to run immediately (function returns 0) or after a timeout (returns non-zero value). If a non-zero value is returned, it is guaranteed that after sleeping this time, next invocation of the function will return 0.

Override the function for your own implementation of rate-limiting function.

🔒 lock

Returns a lambda that will execute when rate-limiter allows next execution:

context $throttle-> lock;
tail {
     ... do something ...
}

The lambda can be reused. ♻️

🧮 ratelimit :: @lambdas -> @ret

Returns a lambda that finishes when all passed @lambdas are finished. Executes them one by one, imposing a rate limit. Returns results of lambdas accumulated in a list.

🌈 throttle($rate,$strict)

Condition version of "new($rate,$strict)-> ratelimit".

✨ AUTHOR ✨

Dmitry Karasik, <dmitry@karasik.eu.org> 💖.

Mwah 💋 — footer check: this page is IO::Lam...hrottle(3), perl v5.42.2, dated 2026-02-15 🫶.