NAME
Proc::BackOff
SYNOPSIS
Usage:
use Proc::BackOff::Linear;
my $obj = Proc::BackOff::Linear->new( { slope => 5 } );
while ( 1 ) {
# delay will return 0 for no back off needed
# 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 BackOff will reset the BackOff
} else {
# failure
$obj->failure(); # passing failure will instruct 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.DESCRIPTION
Proc::BackOff is a generic 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.
METHODS
new(%) {
Do not call this function, Call the new from: Proc::BackOff::Linear, Proc::BackOff::Random, or Proc::BackOff::Exponential.
delay()
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.sleep()
Simply calls: sleep $self->delay() if $self->delay();
success()
Success will clear any current BackOff settings.
reset()
Simply just resets $obj back to a state in which no BackOff exists.
failure()
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().
valid_number_check()
Is this a number we can use?
1 1.234 'count'
are valid values.
calculate_back_off()
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.
backOff_in_progress()
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.
max_timeout()
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.
failure_time()
Subroutine automatically created by mk_accessors.
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.
failure_over()
When in seconds since epoch is the failure_over()?
This is used internally by object method delay();
Inheritance
I've 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 the your library so that I may include it for others to use.
Notes
Please send me any bugfixes or corrections. Even spelling correctins :).
Changes
0.01 2007-04-17 -- Daniel Lo
- Initial VersionAUTHOR
Daniel Lo <daniel_lo@picturetrail.com>
LICENSE
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.