NAME¶
Net::Twitter::Role::RateLimit - Rate limit features for Net::Twitter
VERSION¶
version 4.01005
SYNOPSIS¶
use Net::Twitter;
my $nt = Net::Twitter->new(
traits => [qw/API::REST RateLimit/],
%other_options,
);
#...later
sleep $nt->until_rate(1.0) || $minimum_wait;
NOTE!¶
RateLimit only works with Twitter API v1. The rate limiting strategy of Twitter
API v1.1 is very different. A v1.1 compatible RateLimit role may be coming,
but isn't available, yet. It's interface will necessarily be different.
DESCRIPTION¶
This provides utility methods that return information about the current rate
limit status.
METHODS¶
If current rate limit data is not resident, these methods will force a call to
"rate_limit_status". Therefore, any of these methods can throw an
error.
- rate_remaining
- Returns the number of API calls available before the next reset.
- rate_reset
- Returns the Unix epoch time of the next reset.
- rate_limit
- Returns the current hourly rate limit.
- rate_ratio
- Returns remaining API call limit, divided by the time remaining before the
next reset, as a ratio of the total rate limit per hour.
For example, if "rate_limit" is 150, the total rate is 150 API
calls per hour. If "rate_remaining" is 75, and there 1800
seconds (1/2 hour) remaining before the next reset, "rate_ratio"
returns 1.0, because there are exactly enough API calls remaining to
maintain he full rate of 150 calls per hour.
If "rate_remaining" is 30 and there are 360 seconds remaining
before reset, "rate_ratio" returns 2.0, because there are enough
API calls remaining to maintain twice the full rate of 150 calls per hour.
As a final example, if "rate_remaining" is 15, and there are 7200
seconds remaining before reset, "rate_ratio" returns 0.5,
because there are only enough API calls remaining to maintain half the
full rate of 150 calls per hour.
- until_rate($target_ratio)
- Returns the number of seconds to wait before making another rate limited
API call such that $target_ratio of the full rate would be available. It
always returns a number greater than, or equal to zero.
Use a target rate of 1.0 in a timeline polling loop to get a steady polling
rate, using all the allocated calls, and adjusted for other API calls as
they occur.
Use a target rate < 1.0 to allow a process to make calls as fast as
possible but not consume all of the calls available, too soon. For
example, if you have a process building a large social graph, you may want
to allow it make as many calls as possible, with no wait, until 20% of the
available rate remains. Use a value of 0.2 for that purpose.
A target rate > than 1.0 can be used for a process that should only use
"extra" available API calls. This is useful for an application
that requires most of it's rate limit for normal operation.
AUTHOR¶
Marc Mims <marc@questright.com>
LICENSE¶
Copyright (c) 2009 Marc Mims
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.