NAME
AnyEvent::Retry - try something until it works
VERSION
version 0.03
SYNOPSIS
This module lets you retry a non-blocking task at timed intervals until it succeeds.
If you work for Aperture Science, something like this might be good:
my $r = AnyEvent::Retry->new(
on_failure => sub {
my ($error_type, $error_message) = @_;
$condvar->croak($error_message);
},
on_success => sub {
my ($result) = @_;
$condvar->send($result);
},
max_tries => 100, # eventually give up
interval => { Constant => { interval => 1 } }, # try every second
try => {
my ($success, $error) = @_;
$error->('out of cake!') if $cake-- < 0;
do_science( on_success => $success, on_error => $error );
},
);
$r->start; # keep on trying until you run out of cake
my $neat_gun = $condvar->recv;Now, as long as you have cake, you will keep doing science (every second). When your science results in the creation of a neat gun, $neat_gun will contain it. If there's an error, $condvar->recv will die.
This sort of thing is also good for networking or sysadmin tasks; poll the mail server until you get an email message, poll a webserver until the super-hot tickets go on sale (and then buy them), etc.
METHODS
new({INITARGS})
Create a new, un-start-ed retry-er object. If you undef this object, your job is cancelled and your on_failure callback is notified.
See the INITARGS section below for information on what params to pass.
start
Start the job. Dies if the job is already running.
(You can call this again when the job is done to run the job again.)
pause
Stop the timer, pausing the job until resume is called.
resume
Resume the task as though the last-running timer just expired.
INITARGS
try
Required. This is the coderef to run repeatedly. It is passed two coderefs as args, success_cb and error_cb. Your coderef must call one of those; success with a true value if the process is complete and should not run again, success with a false value if the process should run again, or error with an error message if the process failed (and will not run again).
This is "continuation passing style". It's necessary so that your try block can kick off asynchronous jobs.
on_failure
Required. Callback to call when the job fails. Called a maximum of one time.
When called, it will be called with two args; the type of error, and the error message.
The type of error can be max_tries, exception, or demolish.
Note that if on_failure is called, it's guaranteed that on_success will never be called.
on_success
Required. Called when your job succeeds. Called a maximum of one time.
When called, it will be called with one arg; the value your try block code passed to the success_cb.
Note that if on_success is called, it's guaranteed that on_failure will never be called.
max_tries
Optional. The maximum number of times to run your job before considering it failed.
If it's set to 0, then your job will be run an infinite number of times, subject to the continued existence of the Universe.
Defaults to 0.
autostart
Optional. Boolean. Defaults to 0.
If set to 1, the job will start as soon as the constructor is finished. You need not call start.
interval
Required. Controls how long to wait between retries. It must be a blessed Moose object that does the AnyEvent::Retry::Interval role.
Some existing interval classes are AnyEvent::Retry::Constant, AnyEvent::Retry::Fibonacci, and AnyEvent::Retry::Multi.
This attribute has a coercion from strings and hashrefs. If you pass a string, it will be treated as a class name (under AnyEvent::Retry::Interval::, unless it is prefxed with a +) to instantiate.
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.
AUTHOR
Jonathan Rockway <jrockway@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2010 by Jonathan Rockway.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.