NAME

AnyEvent::RetryTimer - Retry timers for AnyEvent

VERSION

0.1

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;
   });

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 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!

METHODS

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 $timer, it will stop and running timeouts and not call any of the configured callbacks again.

%args can contain these keys:

on_retry => $retry_cb->($timer)

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

When this constructor is called and no 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 retry method.

The first argument is the $timer object itself.

no_first_try => $bool

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

The default is false.

backoff => 'exponential'

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

max_retries => $max_retry_cnt

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

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

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

Default for this option is 0 (disabled).

on_max_retries => $max_retry_cb->($timer)

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

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

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

exponential

start_interval => $secs

This is the length of the first interval. Given in seconds.

Default is 10.

multiplier => $float

This is the multiplier for the retry intervals. Each time a retry is done the previous (if any) interval will be multiplied with $float and used for the next interval.

Default is 1.5.

max_interval => $max_interval_secs

As exponential back off intervals can increase quite a lot you can give the maximum time to wait in $max_interval_secs.

Default is 3600 * 4, which is 4 hours.

$timer->retry

This method initiates or continues retries. If already a retry interval is installed (eg. by the constructor or another previous unfinished call to retry), the call will be a nop.

That means you can call retry directly after you created this object and will not cause the initial try to be "retried".

If you are interested in the length of the current interval (after a call to this method), you can call the current_interval method.

$timer->success

This signals that the last retry was successful and it will reset any state or intervals to the initial settings given to the constructor.

You can reuse the $timer object after a call to success.

my $secs = $timer->current_interval

Returns the length of the current interval to the next call to the $retry_cb.

AUTHOR

Robin Redeker, <elmex@ta-sa.org>

SEE ALSO

AnyEvent

COPYRIGHT & LICENSE

Copyright 2009 Robin Redeker, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.