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

VERSION
    This document describes version 0.002 of Retry::Backoff (from Perl
    distribution Retry-Backoff), released on 2019-06-20.

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', 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.

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

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.

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>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2019 by 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.