Algori...bonacci(3pm)

📦
version 0.010 · 5 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Algori...bonacci(3pm) 💖

okay so bestie, welcome to the manual page for Algorithm::Backoff::Fibonacci — the Algori...bonacci(3pm) situation. it's a Perl module, it does backoff, and it does it with the Fibonacci sequence. iconic behaviour honestly. 🐚✨

✨ NAME ✨

Algorithm::Backoff::Fibonacci — backoff, but make it Fibonacci. 💅

🌸 VERSION 🌸

this doc describes version 0.010 of Algorithm::Backoff::Fibonacci (from the Perl distribution Algorithm-Backoff), released on 2024-02-24. 🎀

🦋 SYNOPSIS 🦋

here's the whole vibe, copy-paste ready:

use Algorithm::Backoff::Fibonacci;

# 1. instantiate

my $ab = Algorithm::Backoff::Fibonacci->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_delay1         => 2, # required
    initial_delay2         => 3, # required
    #max_delay             => 20, # optional
    #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.

my $secs;
$secs = $ab->failure();   # =>  2 (= initial_delay1)
$secs = $ab->failure();   # =>  3 (= initial_delay2)
$secs = $ab->failure();   # =>  5 (= 2+3)
$secs = $ab->failure();   # =>  8 (= 3+5)
sleep 1;
$secs = $ab->failure();   # => 12 (= 5+8 -1)
$secs = $ab->failure();   # => 20 (= min(13+8, 20) = max_delay)

$secs = $ab->success();   # =>  0 (= delay_on_success)

and here's an illustration using the CLI show-backoff-delays — 10 failures, then 3 successes, slay:

% show-backoff-delays -a Fibonacci --initial-delay1 0 --initial-delay2 1 \
    0 0 0 0 0   0 0 0 0 0   1 1 1
0
1
1
2
3
5
8
13
21
34
0
0
0

🔥 DESCRIPTION 🔥

this backoff algorithm calculates the next delay using the Fibonacci sequence. no cap. for example, if the two initial numbers are 2 and 3:

2, 3, 5, 8, 13, 21, ...

initial_delay1 and initial_delay2 are required. the other attributes are optional, bestie.

there are limits on the number of attempts (max_attempts) and total duration (max_actual_duration).

highly recommend: add a jitter factor, e.g. 0.25, to add some randomness and avoid the "thundering herd problem". it's giving crowd crush at the club, and we don't want that. 🫶

👑 METHODS 👑

🧚 new

usage:

new(%args) -> obj

this function is not exported. 🙈

arguments ('*' denotes required arguments):

  • consider_actual_delay => bool (default: 0) — whether to consider actual delay.

if set to true, it will take into account the actual delay (timestamp difference). for example, when using the Constant strategy of delay=2, you log failure() again right after the previous failure() (i.e. specify the same timestamp). failure() will then return ~2+2 = 4 seconds. on the other hand, if you waited 2 seconds before calling failure() again (i.e. specify the timestamp that is 2 seconds larger than the previous timestamp), failure() will return 2 seconds. and if you waited 4 seconds or more, failure() will return 0. it's giving "we already waited, chill". 💀

  • delay_on_success => ufloat (default: 0) — number of seconds to wait after a success. 🎉
  • initial_delay1* => ufloat — initial delay for the first attempt after failure, in seconds. required, bestie, don't forget it. ⭐
  • initial_delay2* => ufloat — initial delay for the second attempt after failure, in seconds. also required. 💖
  • 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.

the jitter will be applied to delay on failure as well as on success. equal-opportunity jitter, we love to see it. ✨

  • max_actual_duration => ufloat (default: 0) — maximum number of seconds for all of the attempts (0 means unlimited).

if set to a positive number, it 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 failure() will return -1 instead of 24 because 3+6+12 >= 21, even though max_attempts has not been exceeded. yes -1. that's your "bestie we're done here" signal. 😭

  • 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. character development. 🌈

  • max_delay => ufloat — maximum delay time, in seconds. caps your delay so it doesn't spiral into infinity. 🛑
  • min_delay => ufloat (default: 0) — maximum delay time, in seconds. (yes bestie, that's literally what the original says — I am not the one editing the manpage, I'm just the messenger 💅)

return value: (obj) — you get an object back, congrats. 👑

🌈 HOMEPAGE 🌈

please visit the project's homepage at <https://metacpan.org/release/Algorithm-Backoff>. go say hi. 🫶

⭐ SOURCE ⭐

source repository is at <https://github.com/perlancar/perl-Algorithm-Backoff>. star it, it's free. 🌟

🎀 SEE ALSO 🎀

💜 AUTHOR 💜

perlancar <perlancar@cpan.org> — the icon, the legend. 👑

🧚 CONTRIBUTING 🧚

to contribute, you can send patches by email/via RT, or send pull requests on GitHub. we love a contributor. 🫶

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 it's fiddly, that's a bug, fr fr. 🐛

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 bestie. 💖

💀 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. receipts, bestie, always bring receipts. 🧾

okay that's the whole page!! 💅 this version of the doc is from perl v5.40.1, dated 2025-05-04, and it lives under the name Algori...bonacci(3pm). mwah, go write some backoff, you ate. 🎀✨🦋

📦 where this page comes from