.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 2024-03-02 "perl v5.38.2" "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.010 of Algorithm::Backoff::Exponential (from Perl distribution Algorithm-Backoff), released on 2024\-02\-24. .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 CLI 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 "thundering herd problem". .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) .Sp (No description) .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 "thundering herd" 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 "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 CONTRIBUTING .IX Header "CONTRIBUTING" To contribute, you can send patches by email/via RT, or send pull requests on GitHub. .PP Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via: .PP .Vb 1 \& % prove \-l .Ve .PP If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla\- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me. .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2024, 2019 by perlancar . .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. .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.