Schedule::RateLimiter(3pm)

1RateLimiter(3)        User Contributed Perl Documentation       RateLimiter(3)
2
3
4

NAME

6       Schedule::RateLimiter - prevent events from happening too quickly.
7

SYNOPSIS

9         use Schedule::RateLimiter;
10
11         # Don't let this event happen more than 5 times in a 60 second period.
12         my $throttle = Schedule::RateLimiter->new ( iterations => 5,
13                                             seconds    => 60 );
14
15         # Cycle forever, but not too fast.
16         while ( 1 ) {
17             $throttle->event();
18             &do_something;
19         }
20

DESCRIPTION

22       This module provides a way to voluntarily restrict how many times a
23       given action may take place within a specified time frame.  Such a tool
24       may be useful if you have written something which periodically polls
25       some public resource and want to ensure that you do not overburden that
26       resource with too many requests.
27
28       Initially, one might think that solving this problem would be as simple
29       as sleeping for the number of seconds divided by the number of
30       iterations in between each event.  However, that would only be correct
31       if the event took no time at all.
32
33       If you know exactly how much time each event is going to take then you
34       could build an even more complicated one-liner such as this:
35
36         sleep( (seconds / iterations) - single_event_time )
37
38       This module is intended to address the other cases when the exact run-
39       time of each event is unknown and variable.  This module will try very
40       hard to allow an event to happen as many times as possible without
41       exceeding the specified bounds.
42
43       For example, suppose you want to write something that checks an
44       'incoming' directory once a minute for files and then does something
45       with those files if it finds any.  If it takes you two seconds to
46       process those files, then you want to wait 58 seconds before polling
47       the directory again.  If it takes 30 seconds to process those files,
48       then you only want to wait 30 seconds.  And if it takes 3 minutes, then
49       you want to poll the directory again immediately as soon as you are
50       done.
51
52         my $throttle = Schedule::RateLimiter->new ( seconds => 60 );
53         &poll_and_process while ( $throttle->event );
54

METHODS

56   " new() "
57       Creates and returns a new Schedule::RateLimiter object.
58
59       The constructor takes up to three parameters:
60
61       ·   block (default: true)
62
63           This parameter accepts a true or false value to set the default
64           "block" behavior on future calls to event().  It makes it more
65           convenient to turn blocking off for an entire object at a time.
66
67       ·   iterations (default: 1)
68
69           This specifies the number of times an event may take place within
70           the given time period.  This must be a positive, non-zero integer.
71
72       ·   seconds (required)
73
74           This specifies the minimum number of seconds that must transpire
75           before we will allow (iterations + 1) events to happen.  A value of
76           0 disables throttling.  You may specify fractional time periods.
77
78       example:
79
80         my $throttle = Schedule::RateLimiter->new ( iterations => 2,
81                                             seconds    => 10 );
82
83         # Event 1
84         $throttle->event();
85         # Event 2
86         $throttle->event();
87         # Event 3
88         $throttle->event();
89         # 10 seconds will have transpired since event 1 at this point.
90         # Event 4
91         $throttle->event();
92         # 10 seconds will have transpired since event 2 at this point.
93
94   " event() "
95       Called to signal the beginning of an event.  This method will return
96       true or false to indicate if it is ok to proceed with the event.  This
97       method uses Time::HiRes to do its calculations and sleeping, so the
98       precision of this method will be the same as the precision of
99       Time::HiRes on your platform.
100
101       Takes one (optional) parameter:
102
103       ·   block (default: true)
104
105           If set to a false value, this method will do a non-blocking check
106           to see if it is ok for the event to occur.  If it is not ok, this
107           method will return a false value and assume that the event did not
108           take place.  Otherwise, this method will return a true value and
109           assume that the event did take place.
110
111       example:
112
113         # Stop when the code moves too fast.
114         while ( 1 ) {
115             if ($throttle->event( block => 0 )) {
116                 &do_something;
117             } else {
118                 die 'I went too fast!';
119             }
120         }
121

BUGS

123       This module needs to keep a record of when every iteration took place,
124       so if you are allowing a large number of iterations to happen in the
125       given time period, this could potentially use a lot of memory.
126

KNOWN ISSUES

128       If you have multiple iterations that typically happen very quickly, and
129       you want to limit them in a long period of time, they will "clump"
130       together.  That is, they all happen at just about the same time, and
131       then the system waits for a long period before doing the same "clump"
132       again.  That's just the nature of the best-fit algorithm.  Anything
133       that is done to try to separate single events with longer waits than
134       necessary will potentially create a sub-optimal situation if an event
135       in the future takes longer than expected.  If you really want all of
136       your events to start at even time periods apart from each other, then
137       set the number of iterations to 1 and adjust the number of seconds
138       accordingly.
139

AUTHOR

141       Daniel J. Wright, <wright@pair.com>
142