Proc::BackOff
Usage:
use Proc::BackOff::Linear; my $obj = Proc::BackOff::Linear->new( { slope => 5 } ); while ( 1 ) { # delay will return # 0 : No delay needed. # N : or the number of seconds until back off is completed. sleep $obj->delay() if $obj->delay(); # or $obj->sleep(); if ( do_attempt() ) { # success $obj->success(); # passing success to Proc::BackOff will reset # Proc::BackOff } else { # failure $obj->failure(); # passing failure will instruct Proc::BackOff to # increment the time to back off } # 100 failures in a row, time to exit die "complete failure" if $obj->failure_count() > 100; } $obj->reset(); # reset back the same state as it was new.
Proc::BackOff is a base module meant to be directly inherited from and then modified by overloading the calculate_back_off object method.
Use: Proc::BackOff::Linear, Proc::BackOff::Random, or Proc::BackOff::Exponential.
Any success $obj->success() will result, in the back off being removed.
$obj->success()
This is for internal use only.
Do not call this function, call new from: Proc::BackOff::Linear, Proc::BackOff::Random, or Proc::BackOff::Exponential.
Delay will return the following
> 0, number of seconds until the delay is over 0 delay is up. Meaning that you should do your next attempt.
This is a short cut for:
sleep $obj->delay() if $obj->delay();
Success will clear Proc::BackOff delay.
Simply just resets $obj back to a state in which no "backing off" exists.
Failure will indicicate to the object to increment the current BackOff time.
The calculate_back_off function is called to get the time in seconds to wait.
The time waited is time+calculated_back_off time, however it is capped by $self->max_timeout().
Is this a number we can use?
1 1.234 'count'
are valid values.
Returns the new back off value.
This is the key function you want to overload if you wish to create your own BackOff library.
The following functions can be used.
$self->failure_count()
The current number of times, that failure has been sequentially called.
$self->failure_start()
When as reported by time in seconds from epoch was failure first called
$self->failure_time()
When was the last failure reported ie, $self->failure() called.
$self->failure_over()
When in time since epoch will the failure be over.
returns 1 if a back off is in progress
returns 0 if a back off is not in progress.
The difference between backOff_in_progress and delay() > 0, is that at the end of a timeout, delay() will return 0, while the backoff will still be in progress.
Subroutine automatically created by mk_accessors.
Get $obj->max_timeout()
Set $obj->max_timeout( 60*60 ) ; # 60 * 60 seconds = 1 hour
The Maximum amount of time to wait.
A max_timeout value of zero, means there is no Maximum.
When was $obj->failure() last called? Time in seconds since epoch.
Get $obj->failure_time()
This variable is not meant to be set by the end user. This variable is set when $obj->failure() is called.
When in seconds since epoch is the failure_over()?
This is used internally by object method delay();
I have included an exponential, linear, and random back off. You can use any of these sub classes to make a new back off library. Please consider sending me any additional BackOff functions, so that I may include it for others to use.
Please send me any bugfixes or corrections. Even spelling correctins :).
Please file any bugs with:
L<http://rt.cpan.org/Public/Dist/Display.html?Name=Proc-BackOff>
0.02 2007-08-12 -- Daniel Lo - Documentation fixes. No code changes. 0.01 2007-04-17 -- Daniel Lo - Initial version
Daniel Lo <daniel_lo@picturetrail.com>
Copyright (C) PictureTrail Inc. 1999-2007 Santa Clara, California, United States of America.
This code is released to the public for public use under Perl's Artisitic licence.
To install Proc::BackOff, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Proc::BackOff
CPAN shell
perl -MCPAN -e shell install Proc::BackOff
For more information on module installation, please visit the detailed CPAN module installation guide.