view release on metacpan or  search on metacpan

lib/AnyEvent/Retry.pm  view on Meta::CPAN

            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, C<< $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.

=head1 METHODS

=head2 new({INITARGS})

Create a new, un-C<start>-ed retry-er object.  If you C<undef> this object,
your job is cancelled and your C<on_failure> callback is notified.

See the INITARGS section below for information on what params to pass.

=head2 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.)

=head2 pause

Stop the timer, pausing the job until C<resume> is called.

=head2 resume

Resume the task as though the last-running timer just expired.

=head1 INITARGS

=head2 try

Required.  This is the coderef to run repeatedly.  It is passed two
coderefs as args, C<success_cb> and C<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
C<try> block can kick off asynchronous jobs.

=head2 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 C<max_tries>, C<exception>, or C<demolish>.

Note that if C<on_failure> is called, it's guaranteed that
C<on_success> will never be called.

=head2 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 C<success_cb>.

Note that if C<on_success> is called, it's guaranteed that
C<on_failure> will never be called.

=head2 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.

=head2 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 C<start>.

=head2 interval

Required.  Controls how long to wait between retries.  It must be a
blessed Moose object that does the L<AnyEvent::Retry::Interval> role.

Some existing interval classes are L<AnyEvent::Retry::Constant>,
L<AnyEvent::Retry::Fibonacci>, and L<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
C<AnyEvent::Retry::Interval::>, unless it is prefxed with a C<+>) 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 C<new>.

=head1 AUTHOR