view release on metacpan or  search on metacpan

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

=head1 NAME

AnyEvent::RetryTimer - Retry timers for AnyEvent

=head1 VERSION

0.1

=head1 SYNOPSIS

   use AnyEvent::RetryTimer;

   my $con =
      Something::Connection->new;

   my $timer;

   $con->on_disconnect (sub {
      $timer ||=
         AnyEvent::RetryTimer->new (
            on_retry => sub {
               $con->connect;
            });

      $timer->retry;

      my $secs = $timer->current_interval;

      warn "Lost connection, reconnecting in $secs seconds!";
   });

   $con->on_connect (sub {
      warn "Connected successfully!";

      $timer->success;
      undef $timer;
   });

=head1 DESCRIPTION

This is a small helper utility to manage timed retries.

This is a pattern I often stumble across when managing network connections.
And I'm tired to reimplement it again and again. So I wrote this module.

At the moment it only implements a simple exponential back off retry mechanism
(with configurable multiplier) using L<AnyEvent> timers. If there are
other back off strategies you find useful you are free to send a
feature request or even better a patch!

=head1 METHODS

=over 4

=item my $timer = AnyEvent::RetryTimer->new (%args)

This is the constructor, it constructs the object.

At the end of the objects lifetime, when you get rid of the last reference to
C<$timer>, it will stop and running timeouts and not call any of the configured
callbacks again.

C<%args> can contain these keys:

=over 4

=item on_retry => $retry_cb->($timer)

C<$retry_cb> is the callback that will be called for (re)tries.

When this constructor is called and no C<no_first_try> is given,
an initial retry interval of the length 0 is started, which counts as the
first try.

Later it is also called after a retry interval has passed, which was initiated
by a call to the C<retry> method.

The first argument is the C<$timer> object itself.

=item no_first_try => $bool

This parameter defines whether the C<$retry_cb> will be called when the
L<AnyEvent::RetryTimer> object is created or not. If C<$bool> is true
C<$retry_cb> will not be called.

The default is false.

=item backoff => 'exponential'

This is the back off algorithm that is used. Currently
only C<exponential> is implemented and is the default.

=item max_retries => $max_retry_cnt

This is the maximum number of retries that are done
between the first call to C<retry> and the finishing
call to C<success>.

If the number of retries is exceeded by a call to C<retry>
the C<on_max_retries> callback is called (see below).

Please note that a call to C<success> will of course reset the internal count
of calls to C<retry>.

Default for this option is C<0> (disabled).

=item on_max_retries => $max_retry_cb->($timer)

After C<max_retries> the C<$max_retry_cb> callback will be
called with the C<$timer> as first argument.

It is usually called when a call to C<retry> would exceed
C<max_retries>.

=back

And then there are keys that are specific to the C<backoff>
method used:

=over 4