Action::Retry - Module to try to perform an action, with various ways of retrying and sleeping between retries.
version 0.18
# Simple usage, will attempt to run the code, retrying if it dies, retrying # 10 times max, sleeping 1 second between retries # functional interface use Action::Retry qw(retry); retry { do_stuff }; # OO interface use Action::Retry; Action::Retry->new( attempt_code => sub { do_stuff; } )->run(); # Same, but sleep time is doubling each time, and arguments passed to the # attempted code # OO interface my $action = Action::Retry->new( attempt_code => sub { my ($num, $str) = @_; ... }, strategy => 'Linear', ); $action->run(42, "foo"); # functional interface retry { ... } strategy => 'Linear'; # Same, but sleep time is following the Fibonacci sequence # OO interface my $action = Action::Retry->new( attempt_code => sub { ... }, strategy => 'Fibonacci', ); $action->run(); # functional interface retry { ... } strategy => 'Fibonacci'; # The code to check if the attempt succeeded can be customized. Strategies # can take arguments. Code on failure can be specified. # OO way my $action = Action::Retry->new( attempt_code => sub { ... }, retry_if_code => sub { $_[0] =~ /Connection lost/ || $_[1] > 20 }, strategy => { Fibonacci => { multiplicator => 2000, initial_term_index => 3, max_retries_number => 5, } }, on_failure_code => sub { say "Given up retrying" }, ); $action->run(); # functional way retry { ...} retry_if_code => sub { ... }, strategy => { Fibonacci => { multiplicator => 2000, initial_term_index => 3, max_retries_number => 5, } }, on_failure_code => sub { ... }; # Retry code in non-blocking way # OO way my $action = Action::Retry->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 }
ro, CodeRef, required
The code to run to attempt doing the action. Will be evaluated taking care of the caller's context. It will receive parameters that were passed to run()
run()
ro, CodeRef
The code to run to check if we need to retry the action. It will be given as first argument, $@, then as following arguments the return values of the execution of attempt_code.
attempt_code
True return value means the execution of attempt_code was a failure and it needs to be retried. False means it went well.
Defaults to:
# Returns true if there were an exception evaluating to something true sub { $_[0] }
ro, CodeRef, optional
If given, the code to run when retries are given up. It will receive parameters that were passed to run()
ro, defaults to 'Constant'
The strategy for managing retrying times, sleeping, and giving up. It must be an object that does the Action::Retry::Strategy role.
This attribute has a coercion from strings and hashrefs. If you pass a string, it will be treated as a class name (under Action::Retry::Strategy::, unless it is prefxed with a +) to instantiate.
Action::Retry::Strategy::
+
If you pass a hashref, the first key will be treated as a class name as above, and the value of that key will be treated as the args to pass to new.
new
Some existing stragies classes are Action::Retry::Strategy::Constant, Action::Retry::Strategy::Fibonacci, Action::Retry::Strategy::Linear.
Defaults to 'Constant'
'Constant'
ro, defaults to 0
If true, the instance will be in a pseudo non blocking mode. In this mode, the run() function behaves a bit differently: instead of sleeping between retries, the run() command will immediately return. Subsequent call to run() will immediately return, until the time to sleep has been elapsed. This allows to do things like that:
my $action = Action::Retry->new( ... , 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 }
If you need a more advanced non blocking mode and callbacks, then look at AnyEvent::Retry
Does the following:
Runs the attempt_code CodeRef in the proper context in an eval {} block, saving $@ in $error.
$@
$error
Runs the retry_if_code CodeRef in scalar context, giving it as arguments $error, and the return values of attempt_code. If it returns true, we consider that it was a failure, and move to step 3. Otherwise, we consider it means success, and return the return values of attempt_code.
retry_if_code
Ask the strategy if it's still useful to retry. If yes, sleep accordingly, and go back to step 2. If not, go to step 4.
strategy
Runs the on_failure_code CodeRef in the proper context, giving it as arguments $error, and the return values of attempt_code, and returns the results back to the caller.
on_failure_code
Arguments passed to run() will be passed to attempt_code. They will also passed to on_failure_code as well if the case arises.
retry { ..code.. } some => 'arguments';
Is equivalent to
Action::Retry->new(attempt_code => sub { ..code.. }, some => arguments )->run();
A functional interface, alternative to the OO interface.
Here are the strategies currently included by default. Check their documentation for more details.
Provides a simple constant sleep time strategy
Provides an incremental constant sleep time strategy following Fibonacci sequence
Provides a linear incrementing sleep time strategy
I created this module because the other related modules I found didn't exactly do what I wanted. Here is the list and why:
No custom checking code. No retry strategies. Can't sleep under one second. No non-blocking mode. No custom failure code.
No retry strategies. Can't sleep under one second. Retry code is passed the results of the attempt code, but not the exception. No non-blocking mode. No custom failure code.
No custom checking code. Strange exception catching behavior. No retry strategies. No non-blocking mode. No custom failure code.
Depends on AnyEvent, and Moose. Strategies are less flexibles, and they don't have sleep timeouts (only max tries).
Damien "dams" Krotkine
This software is copyright (c) 2013 by Damien "dams" Krotkine.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Action::Retry, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Action::Retry
CPAN shell
perl -MCPAN -e shell install Action::Retry
For more information on module installation, please visit the detailed CPAN module installation guide.