.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Algorithm::Backoff::LIMD 3pm" .TH Algorithm::Backoff::LIMD 3pm "2022-10-22" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Algorithm::Backoff::LIMD \- Linear Increment, Multiplicative Decrement (LIMD) backoff .SH "VERSION" .IX Header "VERSION" This document describes version 0.009 of Algorithm::Backoff::LIMD (from Perl distribution Algorithm-Backoff), released on 2019\-06\-20. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Algorithm::Backoff::LIMD; \& \& # 1. instantiate \& \& my $ab = Algorithm::Backoff::LIMD\->new( \& #consider_actual_delay => 1, # optional, default 0 \& #max_actual_duration => 0, # optional, default 0 (retry endlessly) \& #max_attempts => 0, # optional, default 0 (retry endlessly) \& #jitter_factor => 0.25, # optional, default 0 \& min_delay => 1, # optional, default 0 \& #max_delay => 100, # optional \& initial_delay => 2, # required \& delay_increment_on_failure => 4, # required \& delay_multiple_on_success => 0.2, # required \& ); \& \& # 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=2, \& # delay_increment_on_failure=4, delay_multiple_on_success=0.2, min_delay=1: \& \& my $secs; \& $secs = $ab\->failure(); # => 2 (= initial_delay) \& $secs = $ab\->failure(); # => 6 (2 + 4) \& $secs = $ab\->failure(); # => 10 (2 + 4) \& $secs = $ab\->success(); # => 2 (10 * 0.2) \& $secs = $ab\->success(); # => 1 (max(2 * 0.2, 1)) \& $secs = $ab\->failure(); # => 5 (1 + 4) .Ve .PP Illustration using \s-1CLI\s0 show-backoff-delays (3 failures followed by 3 successes, followed by 3 failures): .PP .Vb 12 \& % show\-backoff\-delays \-a LILD \-\-initial\-delay 2 \-\-min\-delay 1 \e \& \-\-delay\-increment\-on\-failure 4 \-\-delay\-multiple\-on\-success 0.2 \e \& 0 0 0 1 1 1 0 0 0 \& 2 \& 6 \& 10 \& 2 \& 1 \& 1 \& 5 \& 9 \& 13 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Upon failure, this backoff algorithm calculates the next delay as: .PP .Vb 3 \& D1 = initial_delay \& D2 = min(D1 + delay_increment_on_failure, max_delay) \& ... .Ve .PP Upon success, the next delay is calculated as: .PP .Vb 3 \& D1 = initial_delay \& D2 = max(D1 * delay_multiple_on_success, min_delay) \& ... .Ve .PP \&\f(CW\*(C`initial_delay\*(C'\fR, \f(CW\*(C`delay_increment_on_failure\*(C'\fR, and \&\f(CW\*(C`delay_multiple_on_success\*(C'\fR are required. .PP There are limits on the number of attempts (`max_attempts`) and total duration (`max_actual_duration`). .PP It is recommended to add a jitter factor, e.g. 0.25 to add some randomness to avoid \*(L"thundering herd problem\*(R". .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" Usage: .PP .Vb 1 \& new(%args) \-> obj .Ve .PP This function is not exported. .PP Arguments ('*' denotes required arguments): .IP "\(bu" 4 \&\fBconsider_actual_delay\fR => \fIbool\fR (default: 0) .Sp Whether to consider actual delay. .Sp 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 \fBfailure()\fR again right after the previous \fBfailure()\fR (i.e. specify the same timestamp). \&\fBfailure()\fR will then return ~2+2 = 4 seconds. On the other hand, if you waited 2 seconds before calling \fBfailure()\fR again (i.e. specify the timestamp that is 2 seconds larger than the previous timestamp), \fBfailure()\fR will return 2 seconds. And if you waited 4 seconds or more, \fBfailure()\fR will return 0. .IP "\(bu" 4 \&\fBdelay_increment_on_failure\fR* => \fIfloat\fR .Sp How much to add to previous delay, in seconds, upon failure (e.g. 5). .IP "\(bu" 4 \&\fBdelay_multiple_on_success\fR* => \fIufloat\fR .Sp How much to multiple previous delay, upon success (e.g. 0.5). .IP "\(bu" 4 \&\fBinitial_delay\fR* => \fIufloat\fR .Sp Initial delay for the first attempt after failure, in seconds. .IP "\(bu" 4 \&\fBjitter_factor\fR => \fIfloat\fR .Sp How much to add randomness. .Sp 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 \*(L"thundering herd\*(R" problem. .Sp The jitter will be applied to delay on failure as well as on success. .IP "\(bu" 4 \&\fBmax_actual_duration\fR => \fIufloat\fR (default: 0) .Sp Maximum number of seconds for all of the attempts (0 means unlimited). .Sp If set to a positive number, will limit the number of seconds for all of the attempts. This setting is used to limit the amount of time you are willing to spend on a task. For example, when using the Exponential strategy of initial_delay=3 and max_attempts=10, the delays will be 3, 6, 12, 24, ... If failures are logged according to the suggested delays, and max_actual_duration is set to 21 seconds, then the third \fBfailure()\fR will return \-1 instead of 24 because 3+6+12 >= 21, even though max_attempts has not been exceeded. .IP "\(bu" 4 \&\fBmax_attempts\fR => \fIuint\fR (default: 0) .Sp Maximum number consecutive failures before giving up. .Sp 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. .IP "\(bu" 4 \&\fBmax_delay\fR => \fIufloat\fR .Sp Maximum delay time, in seconds. .IP "\(bu" 4 \&\fBmin_delay\fR => \fIufloat\fR (default: 0) .Sp Maximum delay time, in seconds. .PP Return value: (obj) .SH "HOMEPAGE" .IX Header "HOMEPAGE" Please visit the project's homepage at . .SH "SOURCE" .IX Header "SOURCE" Source repository is at . .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests on the bugtracker website .PP When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. .SH "SEE ALSO" .IX Header "SEE ALSO" Algorithm::Backoff::LILD .PP Algorithm::Backoff::MILD .PP Algorithm::Backoff::MIMD .PP Algorithm::Backoff .PP Other \f(CW\*(C`Algorithm::Backoff::*\*(C'\fR classes. .SH "AUTHOR" .IX Header "AUTHOR" perlancar .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2019 by perlancar@cpan.org. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.