BackOff.pm

filter: Statementstmt 89.5% 43 / 48 Branchbran 55.5% 10 / 18 Conditioncond 44.4% 4 / 9 MC/DCmcdc 0.0% 0 / 6 Subroutinesub 72.7% 8 / 11 Podpod 100% 8 / 8 totaltotal 73.0% 73 / 100 CC 13 SCAR 12.4
CC
13
Cov
76%
sleep
6.0
new
4.4
failure
4.1
CRAP 3.5
« BackOff/Exponential.pm ↑ Summary
1 package Proc::BackOff;
2  
3 # Inheritance
4 5 ▶use base qw( Class::Accessor );
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 # Set up get/set fields
7 5 __PACKAGE__->mk_accessors( 'max_timeout',
8 'failure_count', # current failure count
9 'failure_start', # time that inital failure
10 # - started. Recorded for
11 # - future classes
12 'failure_time', # time of last failure
13 'failure_over', # when will the failure be over?
14 'backOff_in_progress', # back off is in progress.
15 'init', # was this initalized?
16 );
17  
18 # standard pragmas
19 5 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
20 5 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 # standard perl modules
23  
24 # CPAN & others
25  
26 5 our $VERSION = '0.02';
27  
28 =head1 NAME
29  
30 Proc::BackOff
31  
32 =head1 SYNOPSIS
33  
34 Usage:
35  
36 use Proc::BackOff::Linear;
37  
38 my $obj = Proc::BackOff::Linear->new( { slope => 5 } );
39  
40 while ( 1 ) {
41 # delay will return
42 # 0 : No delay needed.
43 # N : or the number of seconds until back off is completed.
44  
45 sleep $obj->delay() if $obj->delay();
46 # or
47 $obj->sleep();
48  
49 if ( do_attempt() ) {
50 # success
51 $obj->success(); # passing success to Proc::BackOff will reset
52 # Proc::BackOff
53 } else {
54 # failure
55 $obj->failure(); # passing failure will instruct Proc::BackOff to
56 # increment the time to back off
57 }
58  
59 # 100 failures in a row, time to exit
60 die "complete failure" if $obj->failure_count() > 100;
61 }
62  
63 $obj->reset(); # reset back the same state as it was new.
64  
65 =head1 DESCRIPTION
66  
67 Proc::BackOff is a base module meant to be directly inherited from and then
68 modified by overloading the calculate_back_off object method.
69  
70 Use: Proc::BackOff::Linear, Proc::BackOff::Random, or Proc::BackOff::Exponential.
71  
72 Any success C<$obj-E<gt>success()> will result, in the back off being removed.
73  
74 =head1 METHODS
75  
76 =head2 new()
77  
78 This is for internal use only.
79  
80 Do not call this function, call new from:
81 L<Proc::BackOff::Linear>,
82 L<Proc::BackOff::Random>, or L<Proc::BackOff::Exponential>.
83  
84 =cut
85  
86 5 ▶sub new {
Subroutine new: called CC=4 SCAR=14.8
Pod documented
87 5 my ( $proto, $fields ) = @_;
88  
89 5 ▶ my $class = ref $proto || $proto;
Condition33%1/3
ref $proto || $proto
l!l&&r!l&&!r
050
MC/DC0%0/2
ref $proto || $proto
ref $proto $proto
Truth table33%1/3
A || B
A= ref $protoB= $proto
ABresult
1X1
011
000
90  
91 5 ▶ $fields = {} unless defined $fields;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $fields 0 5 5
92  
93 # make a copy of $fields.
94 5 my $obj = bless {%$fields}, $class;
95  
96 # reset uses max_timeout, so max_timeout must be set first.
97 5 ▶ $obj->max_timeout(0) unless defined $obj->max_timeout();
Branch: 1 branch
BranchTrueFalseTotal
unless defined $obj->max_timeout 5 0 5
98  
99 5 $obj->reset();
100  
101 5 return $obj;
102 }
103  
104 =head2 delay()
105  
106 Delay will return the following
107  
108 > 0, number of seconds until the delay is over
109 0 delay is up. Meaning that you should do your next attempt.
110  
111 =cut
112  
113 50 ▶sub delay {
Subroutine delay: called CC=4 SCAR=14.0
Pod documented
114 50 my $self = shift;
115  
116 50 ▶ return 0 if $self->failure_time() == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $self->failure_time == 0 0 50 50
117 50 ▶ return 0 if $self->backOff_in_progress() == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $self->backOff_in_progress == 0 0 50 50
118  
119 # current time - end of timeout
120 50 my $time = time; # to help with debugging
121 50 my $timeLeft = $self->failure_over() - $time;
122  
123 # $timeLeft < 0 we are done
124 # $timeLeft = 0 we are done
125 # $timeLeft > 0 we have time remaining
126  
127 50 ▶ return $timeLeft > 0 ? $timeLeft : 0;
Branch: 1 branch
BranchTrueFalseTotal
$timeLeft > 0 ? : 39 11 50
128 }
129  
130 =head2 sleep()
131  
132 This is a short cut for:
133  
134 sleep $obj->delay() if $obj->delay();
135  
136 =cut
137  
138 0 ▶sub sleep {
Subroutine sleep: not called CC=2 SCAR=17.9
Pod documented
139 0 my $self = shift;
140  
141 0 ▶ sleep $self->delay() if $self->delay();
Branch: 1 branch
BranchTrueFalseTotal
if $self->delay 0 0 0
142 }
143  
144  
145 =head2 success()
146  
147 Success will clear Proc::BackOff delay.
148  
149 =cut
150  
151 0 ▶sub success {
Subroutine success: not called CC=1 SCAR=6.9
Pod documented
152 0 my $self = shift;
153  
154 0 $self->reset();
155 }
156  
157 =head2 reset()
158  
159 Simply just resets $obj back to a state in which no "backing off" exists.
160  
161 =cut
162  
163 5 ▶sub reset {
Subroutine reset: called CC=1 SCAR=0.0
Pod documented
164 5 my $self = shift;
165  
166 5 $self->failure_count(0);
167 5 $self->failure_over(0);
168 5 $self->failure_time(0);
169 5 $self->failure_start(0);
170 5 $self->backOff_in_progress(0);
171 }
172  
173 =head2 failure()
174  
175 Failure will indicicate to the object to increment the current BackOff time.
176  
177 The calculate_back_off function is called to get the time in seconds to wait.
178  
179 The time waited is time+calculated_back_off time, however it is capped by
180 $self->max_timeout().
181  
182 =cut
183  
184 50 ▶sub failure {
Subroutine failure: called CC=4 SCAR=14.1
Pod documented
185 50 my $self = shift;
186  
187 50 $self->backOff_in_progress(1);
188 50 $self->failure_count( $self->failure_count() + 1 );
189  
190 50 my $time = time;
191 50 ▶ $self->failure_start($time) if $self->failure_start() == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $self->failure_start == 0 5 45 50
192 50 $self->failure_time($time);
193  
194 50 my $moreTime = $self->calculate_back_off();
195  
196 # if - max_timeout > 0, then we cap timeout at max_timeout
197 50 ▶ $moreTime = $self->max_timeout()
Branch: 1 branch
BranchTrueFalseTotal
if $self->max_timeout > 0 and $moreTime > $self->max_timeout 0 50 50
Condition33%1/3
$self->max_timeout > 0 and $moreTime > $self->max_timeout
!ll&&!rl&&r
5000
MC/DC0%0/2
$self->max_timeout > 0 and $moreTime > $self->max_timeout
$self->max_timeout > 0 $moreTime > $self->max_timeout
Truth table33%1/3
A and B
A= $self->max_timeout > 0B= $moreTime > $self->max_timeout
ABresult
0X0
100
111
198 if ( $self->max_timeout() > 0 && $moreTime > $self->max_timeout() );
199 # else - To infinity and beyond! -Buzz Lightyear
200  
201 50 $self->failure_over($time+$moreTime);
202 }
203  
204 =head2 valid_number_check()
205  
206 Is this a number we can use?
207  
208 1
209 1.234
210 'count'
211  
212 are valid values.
213  
214 =cut
215  
216 12 ▶sub valid_number_check {
Subroutine valid_number_check: called CC=3 SCAR=11.4
Pod documented
217 12 my $self = shift;
218 12 ▶ return undef unless defined $_[0];
Branch: 1 branch
BranchTrueFalseTotal
unless defined $_[0] 0 12 12
219  
220 # Regex from: http://p3m.org/faq/C3/Q3.html
221 12 ▶ return $_[0] =~ /^-?(?:\d+(?:\.\d*)?|\.\d+)$/ || $_[0] eq 'count';
Condition66%2/3
$_[0] =~ /^-?(?:\d+(?:\.\d*)?|\.\d+)$/ || $_[0] eq 'count'
l!l&&r!l&&!r
570
MC/DC0%0/2
$_[0] =~ /^-?(?:\d+(?:\.\d*)?|\.\d+)$/ || $_[0] eq 'count'
$_[0] =~ /^-?(?:\d+(?:\.\d*)?|\.\d+)$/ $_[0] eq 'count'
Truth table66%2/3
A || B
A= $_[0] =~ /^-?(?:\d+(?:\.\d*)?|\.\d+)$/B= $_[0] eq 'count'
ABresult
1X1
011
000
222 }
223  
224  
225 =head2 calculate_back_off()
226  
227 Returns the new back off value.
228  
229 This is the key function you want to overload if you wish to create your own
230 BackOff library.
231  
232 The following functions can be used.
233  
234 =over 4
235  
236 =item * $self->failure_count()
237  
238 The current number of times, that failure has been sequentially called.
239  
240 =item * $self->failure_start()
241  
242 When as reported by time in seconds from epoch was failure first called
243  
244 =item * $self->failure_time()
245  
246 When was the last failure reported ie, $self->failure() called.
247  
248 =item * $self->failure_over()
249  
250 When in time since epoch will the failure be over.
251  
252 =back
253  
254 =cut
255  
256 0 ▶sub calculate_back_off {
Subroutine calculate_back_off: not called CC=1 SCAR=6.9
Pod documented
257 0 die "Virtual Method";
258 }
259  
260 # subroutines automatically created by mk_accessors
261 # Class
262  
263 =head2 backOff_in_progress()
264  
265 returns 1 if a back off is in progress
266  
267 returns 0 if a back off is not in progress.
268  
269 The difference between backOff_in_progress and delay() > 0, is that at the end
270 of a timeout, delay() will return 0, while the backoff will still be in
271 progress.
272  
273 =head2 max_timeout()
274  
275 Subroutine automatically created by mk_accessors.
276  
277 Get $obj->max_timeout()
278  
279 Set $obj->max_timeout( 60*60 ) ; # 60 * 60 seconds = 1 hour
280  
281 The Maximum amount of time to wait.
282  
283 A max_timeout value of zero, means there is no Maximum.
284  
285 =head2 failure_time()
286  
287 Subroutine automatically created by mk_accessors.
288  
289 When was $obj->failure() last called? Time in seconds since epoch.
290  
291 Get $obj->failure_time()
292  
293 This variable is not meant to be set by the end user. This variable is set when
294 $obj->failure() is called.
295  
296 =head2 failure_over()
297  
298 When in seconds since epoch is the failure_over()?
299  
300 This is used internally by object method delay();
301  
302 =cut
303  
304 5 1;
305  
306 =head1 Inheritance
307  
308 I have included an exponential, linear, and random back off. You can use any of
309 these sub classes to make a new back off library. Please consider sending me
310 any additional BackOff functions, so that I may include it for others to use.
311  
312 =head1 Notes
313  
314 Please send me any bugfixes or corrections. Even spelling correctins :).
315  
316 Please file any bugs with:
317  
318 L<http://rt.cpan.org/Public/Dist/Display.html?Name=Proc-BackOff>
319  
320 =head1 Changes
321  
322 0.02 2007-08-12 -- Daniel Lo
323 - Documentation fixes. No code changes.
324  
325 0.01 2007-04-17 -- Daniel Lo
326 - Initial version
327  
328 =head1 AUTHOR
329  
330 Daniel Lo <daniel_lo@picturetrail.com>
331  
332 =head1 LICENSE
333  
334 Copyright (C) PictureTrail Inc. 1999-2007
335 Santa Clara, California, United States of America.
336  
337 This code is released to the public for public use under Perl's Artisitic
338 licence.
339  
340 =cut
« BackOff/Exponential.pm ↑ Summary