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.

cpanm AnyEvent::Retry

perl -MCPAN -e shell
install AnyEvent::Retry