Algori...ackoff(3pm)

💖 Algorithm::Backoff — the 3pm manual, but make it cute 💖

okay bestie, pull up a chair 🪑 because we're talking about Algorithm::Backoff — the module that gives you Various backoff strategies for retry. it's giving "I don't do the retrying, I just tell you how long to wait" and honestly? iconic. ✨

This page is the 3pm one, iykyk 🫶

---

✨ VERSION ✨

so this doc describes version 0.010 of Algorithm::Backoff (from the Perl distribution Algorithm-Backoff), and it was released on 2024-02-24. slay. 💅

---

🌈 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

literally that's the whole vibe: pick a strategy, log stuff, get seconds back. no cap. 🍓

---

🌸 DESCRIPTION 🌸

this distribution ships a whole lil friend group of classes that implement various backoff strategies for setting the delay between retry attempts. so when something fails, you don't just keep hammering it — you wait a polite lil amount first. 🧚

and Algorithm::Backoff itself? it's a base class only. it's the main character that doesn't do much on its own, respectfully. 👑

here's the tea: Algorithm::Backoff does not actually provide a function/method to retry a piece of code. it only contains the backoff strategies, and it splits the actual delaying off to another module (e.g. Retry::Backoff). and that split is the whole point — it lets you do things like printing/returning all the retries and their delay amounts without actually doing the delay (e.g. in the show-backoff-delays script). obsessed. 💜

---

🎀 METHODS 🎀

new

Usage:

new(%args) -> obj

this function is not exported. it just lives in the module, doing its thing.

Arguments ('*' denotes required arguments) — here's the menu, bestie:

• 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 the so-called "thundering herd" problem — which is exactly as chaotic as it sounds, a whole crowd of processes stampeding at once. 😭

and heads up: the jitter will be applied to delay on failure as well as on success. equal opportunity randomness fr fr.

• 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. and 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. the counter really said "fresh start, new me" 🌈

Return value: (obj) — yes, you get an object back. a lil guy. 🫶

---

success

Usage:

my $secs = $obj->success([ $timestamp ]);

Log a successful attempt. 🎉 if you don't specify it, $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 you don't specify it, $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 the max_attempts parameter has been exceeded). so if you see a -1, that's the module telling you to let it go. it's not you, it's the attempt limit. 💅

---

🦋 HOMEPAGE 🦋

please visit the project's homepage at <https://metacpan.org/release/Algorithm-Backoff>. go give it a lil visit, it's cute. ✨

---

⭐ SOURCE ⭐

source repository is at <https://github.com/perlancar/perl-Algorithm-Backoff>. the code lives there, go peek. 👀

---

🌈 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.

ngl that last one is giving "we were both doing the same thing but I didn't know you existed" and the author handled it with so much grace. 💖

---

💜 AUTHOR 💜

perlancar <perlancar@cpan.org>

---

🎀 CONTRIBUTORS 🎀

• Brendan Byrd <brendan.byrd@grantstreet.com>
• SineSwiper <GitHub@ResonatorSoft.org>

the whole squad came through. 👑

---

💅 CONTRIBUTING 💅

to contribute, you can send patches by email/via RT, or send pull requests on GitHub. come thru bestie 🫶

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. so if the build is doing the most, tell them. 🐛

---

💖 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. free as in freedom, bestie. 🌸

---

🔥 BUGS 🔥

please report any bugs or feature requests on the bugtracker website <https://rt.cpan.org/Public/Dist/Display.html?Name=Algorithm-Backoff>. don't be shy, the bugtracker is literally right there. 🙈

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. receipts help so much, periodt. 📝

---

and that's the whole page, bestie!! 💜 this was perl v5.40.1, dated 2025-05-04 — yeah that's the footer tea, now you have the full picture. go forth and back off (affectionately) 🌈✨🎀