Algorithm-Retry
view release on metacpan or search on metacpan
SYNOPSIS
# 1. pick a strategy and instantiate
use Algorithm::Retry::Constant;
my $ar = Algorithm::Retry::Constant->new(
delay => 2, # required
#delay_on_success => 0, # optional, default 0
);
# 2. log success/failure and get a new number of seconds to delay, timestamp is
# optional but must be monotonically increasing.
my $secs = $ar->failure(); # => 2
my $secs = $ar->success(); # => 0
my $secs = $ar->failure(); # => 2
DESCRIPTION
This distribution provides several classes that implement various
retry/backoff strategies.
This class ("Algorithm::Retry") is a base class only.
METHODS
new
Usage:
How much to add randomness.
If you set this to a value larger than 0, the actual delay will be
between a random number between original_delay * (1-jitter_factor)
and original_delay * (1+jitter_factor). Jitters are usually added to
avoid so-called "thundering herd" problem.
* max_attempts => *uint* (default: 0)
Maximum number consecutive failures before giving up.
0 means to retry endlessly without ever giving up. 1 means to give
up after a single failure (i.e. no retry attempts). 2 means to retry
once after a failure. Note that after a success, the number of
attempts is reset (as expected). So if max_attempts is 3, and if you
fail twice then succeed, then on the next failure the algorithm will
retry again for a maximum of 3 times.
Return value: (obj)
success
Usage:
my $secs = $obj->success([ $timestamp ]);
Log a successful attempt. If not specified, $timestamp defaults to
current time. Will return the suggested number of seconds to wait before
doing another attempt.
failure
Usage:
my $secs = $obj->failure([ $timestamp ]);
Log a failed attempt. If not specified, $timestamp defaults to current
time. Will return the suggested number of seconds to wait before doing
another attempt, or -1 if it suggests that one gives up (e.g. if
"max_attempts" parameter has been exceeded).
HOMEPAGE
Please visit the project's homepage at
<https://metacpan.org/release/Algorithm-Retry>.
SOURCE
Source repository is at
<https://github.com/perlancar/perl-Algorithm-Retry>.
lib/Algorithm/Retry.pm view on Meta::CPAN
our %attr_consider_actual_delay = (
consider_actual_delay => {
summary => 'Whether to consider actual delay',
schema => ['bool*'],
default => 0,
description => <<'_',
If set to true, will take into account the actual delay (timestamp difference).
For example, when using the Constant strategy of delay=2, you log failure()
again right after the previous failure() (i.e. specify the same timestamp).
failure() will then return ~2+2 = 4 seconds. On the other hand, if you waited 2
seconds before calling failure() again (i.e. specify the timestamp that is 2
seconds larger than the previous timestamp), failure() will return 2 seconds.
And if you waited 4 seconds or more, failure() will return 0.
_
},
);
our %attr_max_attempts = (
max_attempts => {
summary => 'Maximum number consecutive failures before giving up',
schema => 'uint*',
default => 0,
description => <<'_',
0 means to retry endlessly without ever giving up. 1 means to give up after a
single failure (i.e. no retry attempts). 2 means to retry once after a failure.
Note that after a success, the number of attempts is reset (as expected). So if
max_attempts is 3, and if you fail twice then succeed, then on the next failure
the algorithm will retry again for a maximum of 3 times.
lib/Algorithm/Retry.pm view on Meta::CPAN
random number between original_delay * (1-jitter_factor) and original_delay *
(1+jitter_factor). Jitters are usually added to avoid so-called "thundering
herd" problem.
_
},
);
our %attr_delay_on_success = (
delay_on_success => {
summary => 'Number of seconds to wait after a success',
schema => 'ufloat*',
default => 0,
},
);
our %attr_max_delay = (
max_delay => {
summary => 'Maximum delay time, in seconds',
schema => 'ufloat*',
},
);
$SPEC{new} = {
v => 1.1,
is_class_meth => 1,
is_func => 0,
args => {
%attr_max_attempts,
lib/Algorithm/Retry.pm view on Meta::CPAN
=head1 SYNOPSIS
# 1. pick a strategy and instantiate
use Algorithm::Retry::Constant;
my $ar = Algorithm::Retry::Constant->new(
delay => 2, # required
#delay_on_success => 0, # optional, default 0
);
# 2. log success/failure and get a new number of seconds to delay, timestamp is
# optional but must be monotonically increasing.
my $secs = $ar->failure(); # => 2
my $secs = $ar->success(); # => 0
my $secs = $ar->failure(); # => 2
=head1 DESCRIPTION
This distribution provides several classes that implement various retry/backoff
strategies.
This class (C<Algorithm::Retry>) is a base class only.
=head1 METHODS
lib/Algorithm/Retry.pm view on Meta::CPAN
How much to add randomness.
If you set this to a value larger than 0, the actual delay will be between a
random number between original_delay * (1-jitter_factor) and original_delay *
(1+jitter_factor). Jitters are usually added to avoid so-called "thundering
herd" problem.
=item * B<max_attempts> => I<uint> (default: 0)
Maximum number consecutive failures before giving up.
0 means to retry endlessly without ever giving up. 1 means to give up after a
single failure (i.e. no retry attempts). 2 means to retry once after a failure.
Note that after a success, the number of attempts is reset (as expected). So if
max_attempts is 3, and if you fail twice then succeed, then on the next failure
the algorithm will retry again for a maximum of 3 times.
=back
Return value: (obj)
=head2 success
Usage:
my $secs = $obj->success([ $timestamp ]);
Log a successful attempt. If not specified, C<$timestamp> defaults to current
time. Will return the suggested number of seconds to wait before doing another
attempt.
=head2 failure
Usage:
my $secs = $obj->failure([ $timestamp ]);
Log a failed attempt. If not specified, C<$timestamp> defaults to current time.
Will return the suggested number of seconds to wait before doing another
attempt, or -1 if it suggests that one gives up (e.g. if C<max_attempts>
parameter has been exceeded).
=head1 HOMEPAGE
Please visit the project's homepage at L<https://metacpan.org/release/Algorithm-Retry>.
=head1 SOURCE
Source repository is at L<https://github.com/perlancar/perl-Algorithm-Retry>.
lib/Algorithm/Retry/Constant.pm view on Meta::CPAN
$SPEC{new} = {
v => 1.1,
is_class_meth => 1,
is_func => 0,
args => {
%Algorithm::Retry::attr_consider_actual_delay,
%Algorithm::Retry::attr_max_attempts,
%Algorithm::Retry::attr_jitter_factor,
%Algorithm::Retry::attr_delay_on_success,
delay => {
summary => 'Number of seconds to wait after a failure',
schema => 'ufloat*',
req => 1,
},
},
result_naked => 1,
result => {
schema => 'obj*',
},
};
lib/Algorithm/Retry/Constant.pm view on Meta::CPAN
# 1. instantiate
my $ar = Algorithm::Retry::Constant->new(
#consider_actual_delay => 1, # optional, default 0
#max_attempts => 0, # optional, default 0 (retry endlessly)
#jitter_factor => 0, # optional, set to positive value to add randomness
delay => 2, # required
#delay_on_success => 0, # optional, default 0
);
# 2. log success/failure and get a new number of seconds to delay, timestamp is
# optional argument (default is current time) but must be monotonically
# increasing.
my $secs = $ar->failure(1554652553); # => 2
my $secs = $ar->success(); # => 0
my $secs = $ar->failure(); # => 2
=head1 DESCRIPTION
This retry strategy is one of the simplest: it waits X second(s) after each
failure, or Y second(s) (default 0) after a success. Some randomness can be
introduced to avoid "thundering herd problem".
=head1 METHODS
=head2 new
Usage:
new(%args) -> obj
lib/Algorithm/Retry/Constant.pm view on Meta::CPAN
=over 4
=item * B<consider_actual_delay> => I<bool> (default: 0)
Whether to consider actual delay.
If set to true, will take into account the actual delay (timestamp difference).
For example, when using the Constant strategy of delay=2, you log failure()
again right after the previous failure() (i.e. specify the same timestamp).
failure() will then return ~2+2 = 4 seconds. On the other hand, if you waited 2
seconds before calling failure() again (i.e. specify the timestamp that is 2
seconds larger than the previous timestamp), failure() will return 2 seconds.
And if you waited 4 seconds or more, failure() will return 0.
=item * B<delay>* => I<ufloat>
Number of seconds to wait after a failure.
=item * B<delay_on_success> => I<ufloat> (default: 0)
Number of seconds to wait after a success.
=item * B<jitter_factor> => I<float>
How much to add randomness.
If you set this to a value larger than 0, the actual delay will be between a
random number between original_delay * (1-jitter_factor) and original_delay *
(1+jitter_factor). Jitters are usually added to avoid so-called "thundering
herd" problem.
=item * B<max_attempts> => I<uint> (default: 0)
Maximum number consecutive failures before giving up.
0 means to retry endlessly without ever giving up. 1 means to give up after a
single failure (i.e. no retry attempts). 2 means to retry once after a failure.
Note that after a success, the number of attempts is reset (as expected). So if
max_attempts is 3, and if you fail twice then succeed, then on the next failure
the algorithm will retry again for a maximum of 3 times.
=back
Return value: (obj)
lib/Algorithm/Retry/ExponentialBackoff.pm view on Meta::CPAN
is_class_meth => 1,
is_func => 0,
args => {
%Algorithm::Retry::attr_consider_actual_delay,
%Algorithm::Retry::attr_max_attempts,
%Algorithm::Retry::attr_jitter_factor,
%Algorithm::Retry::attr_delay_on_success,
%Algorithm::Retry::attr_max_delay,
initial_delay => {
summary => 'Initial delay for the first attempt after failure, '.
'in seconds',
schema => 'ufloat*',
req => 1,
},
exponent_base => {
schema => 'ufloat*',
default => 2,
},
},
result_naked => 1,
result => {
lib/Algorithm/Retry/ExponentialBackoff.pm view on Meta::CPAN
my $ar = Algorithm::Retry::ExponentialBackoff->new(
#consider_actual_delay => 1, # optional, default 0
#max_attempts => 0, # optional, default 0 (retry endlessly)
#jitter_factor => 0.25, # optional, default 0
initial_delay => 5, # required
#max_delay => 100, # optional
#exponent_base => 2, # optional, default 2 (binary exponentiation)
#delay_on_success => 0, # optional, default 0
);
# 2. log success/failure and get a new number of seconds to delay, timestamp is
# optional but must be monotonically increasing.
# for example, using the parameters initial_delay=5, max_delay=100:
my $secs;
$secs = $ar->failure(); # => 5 (= initial_delay)
$secs = $ar->failure(); # => 10 (5 * 2^1)
$secs = $ar->failure(); # => 20 (5 * 2^2)
$secs = $ar->failure(); # => 33 (5 * 2^3 - 7)
$secs = $ar->failure(); # => 80 (5 * 2^4)
$secs = $ar->failure(); # => 100 ( min(5 * 2^5, 100) )
$secs = $ar->success(); # => 0 (= delay_on_success)
=head1 DESCRIPTION
This backoff algorithm calculates the next delay as:
initial_delay * exponent_base ** (attempts-1)
Only the C<initial_delay> is required. C<exponent_base> is 2 by default (binary
expoential). For the first failure attempt (C<attempts> = 1) the delay equals
the initial delay. Then it is doubled, quadrupled, and so on (using the default
lib/Algorithm/Retry/ExponentialBackoff.pm view on Meta::CPAN
=over 4
=item * B<consider_actual_delay> => I<bool> (default: 0)
Whether to consider actual delay.
If set to true, will take into account the actual delay (timestamp difference).
For example, when using the Constant strategy of delay=2, you log failure()
again right after the previous failure() (i.e. specify the same timestamp).
failure() will then return ~2+2 = 4 seconds. On the other hand, if you waited 2
seconds before calling failure() again (i.e. specify the timestamp that is 2
seconds larger than the previous timestamp), failure() will return 2 seconds.
And if you waited 4 seconds or more, failure() will return 0.
=item * B<delay_on_success> => I<ufloat> (default: 0)
Number of seconds to wait after a success.
=item * B<exponent_base> => I<ufloat> (default: 2)
=item * B<initial_delay>* => I<ufloat>
Initial delay for the first attempt after failure, in seconds.
=item * B<jitter_factor> => I<float>
How much to add randomness.
If you set this to a value larger than 0, the actual delay will be between a
random number between original_delay * (1-jitter_factor) and original_delay *
(1+jitter_factor). Jitters are usually added to avoid so-called "thundering
herd" problem.
=item * B<max_attempts> => I<uint> (default: 0)
Maximum number consecutive failures before giving up.
0 means to retry endlessly without ever giving up. 1 means to give up after a
single failure (i.e. no retry attempts). 2 means to retry once after a failure.
Note that after a success, the number of attempts is reset (as expected). So if
max_attempts is 3, and if you fail twice then succeed, then on the next failure
the algorithm will retry again for a maximum of 3 times.
=item * B<max_delay> => I<ufloat>
Maximum delay time, in seconds.
=back
Return value: (obj)
=head1 HOMEPAGE
Please visit the project's homepage at L<https://metacpan.org/release/Algorithm-Retry>.
=head1 SOURCE
lib/Algorithm/Retry/Fibonacci.pm view on Meta::CPAN
is_class_meth => 1,
is_func => 0,
args => {
%Algorithm::Retry::attr_consider_actual_delay,
%Algorithm::Retry::attr_max_attempts,
%Algorithm::Retry::attr_jitter_factor,
%Algorithm::Retry::attr_delay_on_success,
%Algorithm::Retry::attr_max_delay,
initial_delay1 => {
summary => 'Initial delay for the first attempt after failure, '.
'in seconds',
schema => 'ufloat*',
req => 1,
},
initial_delay2 => {
summary => 'Initial delay for the second attempt after failure, '.
'in seconds',
schema => 'ufloat*',
req => 1,
},
},
result_naked => 1,
result => {
schema => 'obj*',
},
};
lib/Algorithm/Retry/Fibonacci.pm view on Meta::CPAN
my $ar = Algorithm::Retry::Fibonacci->new(
#max_attempts => 0, # optional, default 0 (retry endlessly)
#jitter_factor => 0.25, # optional, default 0
initial_delay1 => 2, # required
initial_delay2 => 3, # required
#max_delay => 20, # optional
#delay_on_success => 0, # optional, default 0
);
# 2. log success/failure and get a new number of seconds to delay, timestamp is
# optional but must be monotonically increasing.
my $secs;
$secs = $ar->failure(); # => 2 (= initial_delay1)
$secs = $ar->failure(); # => 3 (= initial_delay2)
$secs = $ar->failure(); # => 5 (= 2+3)
$secs = $ar->failure(); # => 8 (= 3+5)
sleep 1;
$secs = $ar->failure(); # => 12 (= 5+8 -1)
$secs = $ar->failure(); # => 20 (= min(13+8, 20) = max_delay)
$secs = $ar->success(); # => 0 (= delay_on_success)
=head1 DESCRIPTION
This backoff algorithm calculates the next delay using Fibonacci sequence. For
example, if the two initial numbers are 2 and 3:
2, 3, 5, 8, 13, 21, ...
C<initial_delay1> and C<initial_delay2> are required. The other attributes are
optional. It is recommended to add a jitter factor, e.g. 0.25 to add some
lib/Algorithm/Retry/Fibonacci.pm view on Meta::CPAN
=over 4
=item * B<consider_actual_delay> => I<bool> (default: 0)
Whether to consider actual delay.
If set to true, will take into account the actual delay (timestamp difference).
For example, when using the Constant strategy of delay=2, you log failure()
again right after the previous failure() (i.e. specify the same timestamp).
failure() will then return ~2+2 = 4 seconds. On the other hand, if you waited 2
seconds before calling failure() again (i.e. specify the timestamp that is 2
seconds larger than the previous timestamp), failure() will return 2 seconds.
And if you waited 4 seconds or more, failure() will return 0.
=item * B<delay_on_success> => I<ufloat> (default: 0)
Number of seconds to wait after a success.
=item * B<initial_delay1>* => I<ufloat>
Initial delay for the first attempt after failure, in seconds.
=item * B<initial_delay2>* => I<ufloat>
Initial delay for the second attempt after failure, in seconds.
=item * B<jitter_factor> => I<float>
How much to add randomness.
If you set this to a value larger than 0, the actual delay will be between a
random number between original_delay * (1-jitter_factor) and original_delay *
(1+jitter_factor). Jitters are usually added to avoid so-called "thundering
herd" problem.
=item * B<max_attempts> => I<uint> (default: 0)
Maximum number consecutive failures before giving up.
0 means to retry endlessly without ever giving up. 1 means to give up after a
single failure (i.e. no retry attempts). 2 means to retry once after a failure.
Note that after a success, the number of attempts is reset (as expected). So if
max_attempts is 3, and if you fail twice then succeed, then on the next failure
the algorithm will retry again for a maximum of 3 times.
=item * B<max_delay> => I<ufloat>
Maximum delay time, in seconds.
=back
Return value: (obj)
=head1 HOMEPAGE
Please visit the project's homepage at L<https://metacpan.org/release/Algorithm-Retry>.
=head1 SOURCE
t/01-base.t view on Meta::CPAN
consider_actual_delay => 1,
delay => 2,
max_attempts => 0,
);
is($ar->failure(1), 2);
# we didn't wait, so the delay is now 2+2 = 4
is($ar->failure(1), 4);
# we now waited for 5 seconds, so delay is now 2-1 = 1
is($ar->failure(6), 1);
# we now waited for 2 seconds, so delay is now 2-1 = 1
is($ar->failure(8), 1);
# we now waited for 3 seconds, so delay is now 2-2 = 0
is($ar->failure(11), 0);
};
# XXX test each strategy
subtest "attr: jitter_factor" => sub {
my $ar = Algorithm::Retry::Constant->new(
delay => 2,
delay_on_success => 3,
jitter_factor => 0.1,
);
( run in 0.534 second using v1.01-cache-2.11-cpan-39bf76dae61 )