IO::Lambda::Throttle(3p)

NAME
IO::Lambda::Throttle - rate-limiting facility

DESCRIPTION
Provides several interfaces for throttling control flow by imposing rate limit.

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

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 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 af 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>.