README
1NAME
2 Proc::BackOff
3
4SYNOPSIS
5 Usage:
6
7 use Proc::BackOff::Linear;
8
9 my $obj = Proc::BackOff::Linear->new( { slope => 5 } );
10
11 while ( 1 ) {
12 # delay will return
13 # 0 : No delay needed.
14 # N : or the number of seconds until back off is completed.
15
16 sleep $obj->delay() if $obj->delay();
17 # or
18 $obj->sleep();
19
20 if ( do_attempt() ) {
21 # success
22 $obj->success(); # passing success to Proc::BackOff will reset
23 # Proc::BackOff
24 } else {
25 # failure
26 $obj->failure(); # passing failure will instruct Proc::BackOff to
27 # increment the time to back off
28 }
29
30 # 100 failures in a row, time to exit
31 die "complete failure" if $obj->failure_count() > 100;
32 }
33
34 $obj->reset(); # reset back the same state as it was new.
35
36DESCRIPTION
37 Proc::BackOff is a base module meant to be directly inherited from and
38 then modified by overloading the calculate_back_off object method.
39
40 Use: Proc::BackOff::Linear, Proc::BackOff::Random, or
41 Proc::BackOff::Exponential.
42
43 Any success "$obj->success()" will result, in the back off being
44 removed.
45
46METHODS
47 new()
48 This is for internal use only.
49
50 Do not call this function, call new from: Proc::BackOff::Linear,
51 Proc::BackOff::Random, or Proc::BackOff::Exponential.
52
53 delay()
54 Delay will return the following
55
56 > 0, number of seconds until the delay is over
57 0 delay is up. Meaning that you should do your next attempt.
58
59 sleep()
60 This is a short cut for:
61
62 sleep $obj->delay() if $obj->delay();
63
64 success()
65 Success will clear Proc::BackOff delay.
66
67 reset()
68 Simply just resets $obj back to a state in which no "backing off"
69 exists.
70
71 failure()
72 Failure will indicicate to the object to increment the current BackOff
73 time.
74
75 The calculate_back_off function is called to get the time in seconds to
76 wait.
77
78 The time waited is time+calculated_back_off time, however it is capped
79 by $self->max_timeout().
80
81 valid_number_check()
82 Is this a number we can use?
83
84 1 1.234 'count'
85
86 are valid values.
87
88 calculate_back_off()
89 Returns the new back off value.
90
91 This is the key function you want to overload if you wish to create your
92 own BackOff library.
93
94 The following functions can be used.
95
96 * $self->failure_count()
97 The current number of times, that failure has been sequentially
98 called.
99
100 * $self->failure_start()
101 When as reported by time in seconds from epoch was failure first
102 called
103
104 * $self->failure_time()
105 When was the last failure reported ie, $self->failure() called.
106
107 * $self->failure_over()
108 When in time since epoch will the failure be over.
109
110 backOff_in_progress()
111 returns 1 if a back off is in progress
112
113 returns 0 if a back off is not in progress.
114
115 The difference between backOff_in_progress and delay() > 0, is that at
116 the end of a timeout, delay() will return 0, while the backoff will
117 still be in progress.
118
119 max_timeout()
120 Subroutine automatically created by mk_accessors.
121
122 Get $obj->max_timeout()
123
124 Set $obj->max_timeout( 60*60 ) ; # 60 * 60 seconds = 1 hour
125
126 The Maximum amount of time to wait.
127
128 A max_timeout value of zero, means there is no Maximum.
129
130 failure_time()
131 Subroutine automatically created by mk_accessors.
132
133 When was $obj->failure() last called? Time in seconds since epoch.
134
135 Get $obj->failure_time()
136
137 This variable is not meant to be set by the end user. This variable is
138 set when $obj->failure() is called.
139
140 failure_over()
141 When in seconds since epoch is the failure_over()?
142
143 This is used internally by object method delay();
144
145Inheritance
146 I have included an exponential, linear, and random back off. You can use
147 any of these sub classes to make a new back off library. Please consider
148 sending me any additional BackOff functions, so that I may include it
149 for others to use.
150
151Notes
152 Please send me any bugfixes or corrections. Even spelling correctins :).
153
154 Please file any bugs with:
155
156 L<http://rt.cpan.org/Public/Dist/Display.html?Name=Proc-BackOff>
157
158Changes
159 0.02 2007-08-12 -- Daniel Lo
160 - Documentation fixes. No code changes.
161
162 0.01 2007-04-17 -- Daniel Lo
163 - Initial version
164
165AUTHOR
166 Daniel Lo <daniel_lo@picturetrail.com>
167
168LICENSE
169 Copyright (C) PictureTrail Inc. 1999-2007 Santa Clara, California,
170 United States of America.
171
172 This code is released to the public for public use under Perl's
173 Artisitic licence.
174
175