1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
NAME
Algorithm::Backoff - Various backoff strategies for retry
VERSION
This document describes version 0.010 of Algorithm::Backoff (from Perl
distribution Algorithm-Backoff), released on 2024-02-24.
SYNOPSIS
# 1. pick a strategy and instantiate
use Algorithm::Backoff::Constant;
my $ab = Algorithm::Backoff::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. if you don't
# want to log for the current time, you can pass a timestamp (number of seconds
# passed since some reference value, like a Unix epoch) as the argument, which
# should be monotonically increasing.
my $secs = $ab->failure(); # => 2
my $secs = $ab->success(); # => 0
my $secs = $ab->failure(); # => 2
DESCRIPTION
This distribution provides several classes that implement various
backoff strategies for setting delay between retry attempts.
This class ("Algorithm::Backoff") is a base class only.
Algorithm::Backoff does not actually provide a function/method to retry
a piece of code. It only contains the backoff strategies and splits the
actual delaying to another module (e.g. Retry::Backoff). This allows for
things like printing/returning all the retries and their delay amounts
without actually doing the delay (e.g. in show-backoff-delays script).
METHODS
new
Usage:
new(%args) -> obj
This function is not exported.
Arguments ('*' denotes required arguments):
* jitter_factor => *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.
The jitter will be applied to delay on failure as well as on
success.
* 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 Unix timestamp. 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
Unix timestamp. 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-Backoff>.
SOURCE
Source repository is at
<https://github.com/perlancar/perl-Algorithm-Backoff>.
SEE ALSO
Retry::Backoff - an application of Algorithm::Backoff to retry a piece
of code using various backoff strategies.
App::AlgorithmBackoffUtils - various CLI's related to
Algorithm::Backoff.
Action::Retry - A prior art for Algorithm::Backoff. Somehow I didn't
find this module before writing Algorithm::Backoff. But
Algorithm::Backoff offers an alternative interface (a split of actual
sleep/retry vs the algorithm), and some additional parameters (like
delay on success and jitter factor), a lighter footprint (no Moo), and a
couple more strategies.
AUTHOR
perlancar <perlancar@cpan.org>
CONTRIBUTORS
* Brendan Byrd <brendan.byrd@grantstreet.com>
* SineSwiper <GitHub@ResonatorSoft.org>
CONTRIBUTING
To contribute, you can send patches by email/via RT, or send pull
requests on GitHub.
Most of the time, you don't need to build the distribution yourself. You
can simply modify the code, then test via:
% prove -l
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.
COPYRIGHT AND LICENSE
This software is copyright (c) 2024, 2019 by perlancar
<perlancar@cpan.org>.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
BUGS
Please report any bugs or feature requests on the bugtracker website
<https://rt.cpan.org/Public/Dist/Display.html?Name=Algorithm-Backoff>
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.
|
