.\" 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::Exponential 3pm" .TH Algorithm::Backoff::Exponential 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::Exponential \- Backoff exponentially .SH "VERSION" .IX Header "VERSION" This document describes version 0.009 of Algorithm::Backoff::Exponential (from Perl distribution Algorithm-Backoff), released on 2019\-06\-20. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Algorithm::Backoff::Exponential; \& \& # 1. instantiate \& \& my $ab = Algorithm::Backoff::Exponential\->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 \& 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 = $ab\->failure(); # => 5 (= initial_delay) \& $secs = $ab\->failure(); # => 10 (5 * 2^1) \& $secs = $ab\->failure(); # => 20 (5 * 2^2) \& $secs = $ab\->failure(); # => 33 (5 * 2^3 \- 7) \& $secs = $ab\->failure(); # => 80 (5 * 2^4) \& $secs = $ab\->failure(); # => 100 ( min(5 * 2^5, 100) ) \& $secs = $ab\->success(); # => 0 (= delay_on_success) .Ve .PP Illustration using \s-1CLI\s0 show-backoff-delays (10 failures followed by 3 successes): .PP .Vb 10 \& % show\-backoff\-delays \-a Exponential \-\-initial\-delay 1 \-\-max\-delay 200 \e \& 0 0 0 0 0 0 0 0 0 0 1 1 1 \& 1 \& 2 \& 4 \& 8 \& 16 \& 32 \& 64 \& 128 \& 200 \& 200 \& 0 \& 0 \& 0 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This backoff algorithm calculates the next delay as: .PP .Vb 1 \& initial_delay * exponent_base ** (attempts\-1) .Ve .PP Only the \f(CW\*(C`initial_delay\*(C'\fR is required. \f(CW\*(C`exponent_base\*(C'\fR is 2 by default (binary exponential). For the first failure attempt (\f(CW\*(C`attempts\*(C'\fR = 1) the delay equals the initial delay. Then it is doubled, quadrupled, and so on (using the default exponent base of 2). .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_on_success\fR => \fIufloat\fR (default: 0) .Sp Number of seconds to wait after a success. .IP "\(bu" 4 \&\fBexponent_base\fR => \fIufloat\fR (default: 2) .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" .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.