.\" -*- 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::MIMD 3pm" .TH Algorithm::Backoff::MIMD 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::MIMD \- Multiplicative Increment, Multiplicative Decrement (MIMD) backoff .SH VERSION .IX Header "VERSION" This document describes version 0.010 of Algorithm::Backoff::MIMD (from Perl distribution Algorithm-Backoff), released on 2024\-02\-24. .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& use Algorithm::Backoff::MIMD; \& \& # 1. instantiate \& \& my $ab = Algorithm::Backoff::MIMD\->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 => 2, # optional, default 0 \& #max_delay => 100, # optional \& initial_delay => 3, # required \& delay_multiple_on_failure => 2, # required \& delay_multiple_on_success => 0.5, # 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=3, \& # delay_multiple_on_failure=2, delay_multiple_on_success=0.5, min_delay=2: \& \& my $secs; \& $secs = $ab\->failure(); # => 3 (= initial_delay) \& $secs = $ab\->failure(); # => 6 (3 * 2) \& $secs = $ab\->failure(); # => 12 (6 * 2) \& $secs = $ab\->success(); # => 6 (12 * 0.5) \& $secs = $ab\->success(); # => 3 (6 * 0.5) \& $secs = $ab\->success(); # => 2 (max(3*0.5, min_delay=2)) \& $secs = $ab\->failure(); # => 4 (2 * 2) .Ve .PP Illustration using CLI show-backoff-delays (4 failures followed by 5 successes, followed by 3 failures): .PP .Vb 10 \& % show\-backoff\-delays \-a MIMD \-\-initial\-delay 3 \-\-min\-delay 2 \e \& \-\-delay\-multiple\-on\-failure 2 \-\-delay\-multiple\-on\-success 0.5 \e \& 0 0 0 0 1 1 1 1 1 0 0 0 \& 3 \& 6 \& 12 \& 24 \& 12 \& 6 \& 3 \& 2 \& 2 \& 4 \& 8 \& 16 .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" Upon failure, this backoff algorithm calculates the next delay as: .PP .Vb 3 \& D1 = initial_delay \& D2 = max(min(D1 * delay_multiple_on_failure, max_delay), min_delay) \& ... .Ve .PP Upon success, the next delay is calculated as: .PP .Vb 3 \& D1 = initial_delay \& D2 = max(min(D1 * delay_multiple_on_success, max_delay), min_delay) \& ... .Ve .PP \&\f(CW\*(C`initial_delay\*(C'\fR, \f(CW\*(C`delay_multiple_on_failure\*(C'\fR, and \f(CW\*(C`delay_multiple_on_success\*(C'\fR are required. \f(CW\*(C`initial_delay\*(C'\fR and \f(CW\*(C`min_delay\*(C'\fR should be larger than zero; otherwise the next delays will all be zero. .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_multiple_on_failure\fR* => \fIufloat\fR .Sp How much to multiple previous delay, upon failure (e.g. 1.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 "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" Algorithm::Backoff::LILD .PP Algorithm::Backoff::LIMD .PP Algorithm::Backoff::MILD .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.