Algori...nstant(3pm)

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

💖 NAME 💖

Algorithm::Backoff::Constant — backoff using a constant delay, bestie. that's it, that's the whole vibe. it waits the same amount every time. iconic, unbothered, consistent. 👑

🌸 VERSION 🌸

this doc is describing version 0.010 of Algorithm::Backoff::Constant, which ships in the Perl distribution Algorithm-Backoff and was released on 2024-02-24. yes she's got a birthday. 🎂

✨ SYNOPSIS ✨

use Algorithm::Backoff::Constant;

# 1. instantiate

my $ab = Algorithm::Backoff::Constant->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, # optional, set to positive value to add randomness
    delay                  => 2, # required
    #delay_on_success      => 0, # optional, default 0
);

# 2. log success/failure and get a new number of seconds to delay, timestamp is
# optional argument (default is current time) but must be monotonically
# increasing.

my $secs = $ab->failure(1554652553); # => 2
my $secs = $ab->success();           # => 0
my $secs = $ab->failure();           # => 2

okay so here's a lil demo of what that actually looks like, using the CLI show-backoff-delays — that's 5 failures followed by 3 successes 🫶

% show-backoff-delays -a Constant --delay 2 \
    0 0 0 0 0   1 1 1
2
2
2
2
2
0
0
0

look at her go. five 2s, three 0s. no drama, no escalation, just consistency. periodt. 💅

🦋 DESCRIPTION 🦋

this backoff strategy is one of the simplest ones, fr fr: it waits X second(s) after each failure, or Y second(s) (default 0) after a success. there are limits on how many attempts you get (max_attempts) and how long the whole thing can drag on (max_actual_duration). and you can sprinkle in some randomness to dodge the "thundering herd problem" — more on that below. 🌈

👑 METHODS 👑

💜 new

usage:

new(%args) -> obj

this function is not exported — no sneaky imports, you call it properly.

arguments ('*' denotes required arguments):

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

if you set this to true, it takes the actual delay (the timestamp difference) into account. for example, with the Constant strategy of delay=2, if you log failure() again right after the previous failure() — like, you specify the same timestamp — then failure() will return roughly 2+2 = 4 seconds. on the other hand, if you waited 2 seconds before calling failure() again (i.e. you specify a 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. math is math. 🧮

  • delay* => ufloat — number of seconds to wait after a failure. this one's required, she's the main character. 🌟
  • delay_on_success => ufloat (default: 0) — number of seconds to wait after a success.
  • jitter_factor => float — how much randomness to add.

if you set this to a value larger than 0, the actual delay will land somewhere 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 — you know, when everyone wakes up at the exact same moment and tramples the server. 💀

the jitter gets applied to the delay on failure as well as on success. equal opportunity randomness.

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

if you set it to a positive number, it limits the number of seconds for all the attempts. this setting is there to cap how much time you're 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. girl did the math and said no. 🛑

  • max_attempts => uint (default: 0) — maximum number of consecutive failures before giving up.

0 means retry endlessly, never giving up, delulu in the best way. 1 means give up after a single failure (i.e. no retry attempts). 2 means 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 you fail twice then succeed, then on the next failure the algorithm will retry again for a maximum of 3 times. fresh start energy. 🌱

  • max_delay => ufloat — maximum delay time, in seconds.
  • min_delay => ufloat (default: 0) — maximum delay time, in seconds. (yes, the docs say "maximum" here too. i'm just the messenger, bestie, i do not make the rules. 🙈)

return value: (obj) — she gives you an object back, obviously. 🎀

🌐 HOMEPAGE 🌐

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

🍓 SOURCE 🍓

the source repository lives at <https://github.com/perlancar/perl-Algorithm-Backoff>. it's giving open source excellence. 🔥

🔍 SEE ALSO 🔍

  • Algorithm::Backoff
  • the other Algorithm::Backoff::* classes. yes, there's a whole friend group. 💜

🧚 AUTHOR 🧚

perlancar <perlancar@cpan.org> — thank you for your service. 👑

🌈 CONTRIBUTING 🌈

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

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 being extra, that's on purpose — tell her. 😭

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. slay, legally. ⚖️💖

💀 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 or it didn't happen, bestie. 📸

and that's the whole page! this was Algorithm::Backoff::Constant(3pm), and the footer says perl v5.40.1, dated 2025-05-04. love that for us. now go forth and wait exactly the same number of seconds every single time. consistent queen behavior. 💅✨🦋
📦 where this page comes from