NAME
    Retry::Backoff - Retry a piece of code, with backoff strategies

VERSION
    This document describes version 0.004 of Retry::Backoff (from Perl
    distribution Retry-Backoff), released on 2023-01-08.

SYNOPSIS
     use Retry::Backoff 'retry';

     # by default, will use Algorithm::Backoff::Exponential with these parameters:
     # - initial_delay =   1 (1 second)
     # - max_delay     = 300 (5 minutes)
     # - max_attempts  =  10
     retry { ... };

     # select backoff strategy (see corresponding Algorithm::Backoff::* for list of
     # parameters)
     retry { ... } strategy=>'Constant', initial_delay=>1, max_attempts=>10;

     # other available 'retry' arguments
     retry { ... }
         on_success   => sub { my $h = shift; ... },
         on_failure   => sub { my $h = shift; ... },
         retry_if     => sub { my $h = shift; ... },
         non_blocking => 0;

DESCRIPTION
    This module provides "retry" to retry a piece of code if it dies.
    Several backoff (delay between retries) strategies are available from
    "Algorithm::Backoff":: modules.

FUNCTIONS
  retry
    Usage:

     retry { attempt-code... } %args;

    Run attempt-code, retry if it dies. Known arguments:

    *   strategy

        String. Default is "Exponential" (with "initial_delay"=1,
        "max_delay"=300, and "max_attempts"=10).

    *   on_success

        Coderef. Will be called if attempt-code is deemed as successful.

    *   on_failure

        Coderef. Will be called if attempt-code is deemed to have failed.

    *   on_final_failure

        Coderef. Will be called if attempt-code is deemed to have failed and
        will not be retried.

    *   retry_if

        Coderef. If this argument is not specified, attempt-code is deemed
        to have failed if it dies. If this argument is specified, then the
        coderef will determine whether the attempt-code is deemed to have
        failed (retry_if code returns true) or succeeded (retry_if code
        returns false).

        Coderef will be passed:

         \%h

        containing these keys:

         error
         action_retry
         attempt_result
         attempt_parameters

    *   non_blocking

        Boolean. If set to true, instead of delaying after a failure (or a
        success, depending on your backoff parameters), "retry" will
        immediately return. Then when called again it will immediately
        return (instead of retrying the attempt-code) until the required
        amount of delay has passed. To use this feature, you actually need
        to use the underlying OO code instead of the "retry" function:

         my $retry = Retry::Backoff->new(
             attempt_code => sub { ... },
             non_blocking => 1,
             ....
         );
         while (1) {
             # if the action failed, it doesn't sleep next time it's called, it won't do
             # anything until it's time to retry
             $action->run;

             # do something else while time goes on
         }

    The rest of the arguments will be passed to the backoff strategy module
    ("Algorithm::Backoff::*").

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Retry-Backoff>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Retry-Backoff>.

SEE ALSO
    Code is based on Action::Retry.

    Other similar modules: Sub::Retry, Retry.

    Backoff strategies are from Algorithm::Backoff::* modules.

AUTHOR
    perlancar <perlancar@cpan.org>

CONTRIBUTOR
    Dave Baird <dave@zerofive.co.uk>

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) 2023, 2021, 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=Retry-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.

