Debian Codegraph @

README

raw
1 NAME
2 Algorithm::Backoff - Various backoff strategies for retry
3
4 VERSION
5 This document describes version 0.010 of Algorithm::Backoff (from Perl
6 distribution Algorithm-Backoff), released on 2024-02-24.
7
8 SYNOPSIS
9 # 1. pick a strategy and instantiate
10
11 use Algorithm::Backoff::Constant;
12 my $ab = Algorithm::Backoff::Constant->new(
13 delay => 2, # required
14 #delay_on_success => 0, # optional, default 0
15 );
16
17 # 2. log success/failure and get a new number of seconds to delay. if you don't
18 # want to log for the current time, you can pass a timestamp (number of seconds
19 # passed since some reference value, like a Unix epoch) as the argument, which
20 # should be monotonically increasing.
21
22 my $secs = $ab->failure(); # => 2
23 my $secs = $ab->success(); # => 0
24 my $secs = $ab->failure(); # => 2
25
26 DESCRIPTION
27 This distribution provides several classes that implement various
28 backoff strategies for setting delay between retry attempts.
29
30 This class ("Algorithm::Backoff") is a base class only.
31
32 Algorithm::Backoff does not actually provide a function/method to retry
33 a piece of code. It only contains the backoff strategies and splits the
34 actual delaying to another module (e.g. Retry::Backoff). This allows for
35 things like printing/returning all the retries and their delay amounts
36 without actually doing the delay (e.g. in show-backoff-delays script).
37
38 METHODS
39 new
40 Usage:
41
42 new(%args) -> obj
43
44 This function is not exported.
45
46 Arguments ('*' denotes required arguments):
47
48 * jitter_factor => *float*
49
50 How much to add randomness.
51
52 If you set this to a value larger than 0, the actual delay will be
53 between a random number between original_delay * (1-jitter_factor)
54 and original_delay * (1+jitter_factor). Jitters are usually added to
55 avoid so-called "thundering herd" problem.
56
57 The jitter will be applied to delay on failure as well as on
58 success.
59
60 * max_attempts => *uint* (default: 0)
61
62 Maximum number consecutive failures before giving up.
63
64 0 means to retry endlessly without ever giving up. 1 means to give
65 up after a single failure (i.e. no retry attempts). 2 means to retry
66 once after a failure. Note that after a success, the number of
67 attempts is reset (as expected). So if max_attempts is 3, and if you
68 fail twice then succeed, then on the next failure the algorithm will
69 retry again for a maximum of 3 times.
70
71 Return value: (obj)
72
73 success
74 Usage:
75
76 my $secs = $obj->success([ $timestamp ]);
77
78 Log a successful attempt. If not specified, $timestamp defaults to
79 current Unix timestamp. Will return the suggested number of seconds to
80 wait before doing another attempt.
81
82 failure
83 Usage:
84
85 my $secs = $obj->failure([ $timestamp ]);
86
87 Log a failed attempt. If not specified, $timestamp defaults to current
88 Unix timestamp. Will return the suggested number of seconds to wait
89 before doing another attempt, or -1 if it suggests that one gives up
90 (e.g. if "max_attempts" parameter has been exceeded).
91
92 HOMEPAGE
93 Please visit the project's homepage at
94 <https://metacpan.org/release/Algorithm-Backoff>.
95
96 SOURCE
97 Source repository is at
98 <https://github.com/perlancar/perl-Algorithm-Backoff>.
99
100 SEE ALSO
101 Retry::Backoff - an application of Algorithm::Backoff to retry a piece
102 of code using various backoff strategies.
103
104 App::AlgorithmBackoffUtils - various CLI's related to
105 Algorithm::Backoff.
106
107 Action::Retry - A prior art for Algorithm::Backoff. Somehow I didn't
108 find this module before writing Algorithm::Backoff. But
109 Algorithm::Backoff offers an alternative interface (a split of actual
110 sleep/retry vs the algorithm), and some additional parameters (like
111 delay on success and jitter factor), a lighter footprint (no Moo), and a
112 couple more strategies.
113
114 AUTHOR
115 perlancar <[email protected]>
116
117 CONTRIBUTORS
118 * Brendan Byrd <[email protected]>
119
120 * SineSwiper <[email protected]>
121
122 CONTRIBUTING
123 To contribute, you can send patches by email/via RT, or send pull
124 requests on GitHub.
125
126 Most of the time, you don't need to build the distribution yourself. You
127 can simply modify the code, then test via:
128
129 % prove -l
130
131 If you want to build the distribution (e.g. to try to install it locally
132 on your system), you can install Dist::Zilla,
133 Dist::Zilla::PluginBundle::Author::PERLANCAR,
134 Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two
135 other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps
136 required beyond that are considered a bug and can be reported to me.
137
138 COPYRIGHT AND LICENSE
139 This software is copyright (c) 2024, 2019 by perlancar
140 <[email protected]>.
141
142 This is free software; you can redistribute it and/or modify it under
143 the same terms as the Perl 5 programming language system itself.
144
145 BUGS
146 Please report any bugs or feature requests on the bugtracker website
147 <https://rt.cpan.org/Public/Dist/Display.html?Name=Algorithm-Backoff>
148
149 When submitting a bug or request, please include a test-file or a patch
150 to an existing test-file that illustrates the bug or desired feature.
151