.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Net::Twitter::Role::RateLimit 3pm"
.TH Net::Twitter::Role::RateLimit 3pm "2018-01-18" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Twitter::Role::RateLimit \- Rate limit features for Net::Twitter
.SH "VERSION"
.IX Header "VERSION"
version 4.01043
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    use Net::Twitter;
\&    my $nt = Net::Twitter\->new(
\&        traits => [qw/API::REST RateLimit/],
\&        %other_options,
\&    );
\&
\&    #...later
\&
\&    sleep $nt\->until_rate(1.0) || $minimum_wait;
.Ve
.SH "NOTE!"
.IX Header "NOTE!"
RateLimit only works with Twitter \s-1API\s0 v1. The rate limiting strategy of Twitter
\&\s-1API\s0 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.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This provides utility methods that return information about the current
rate limit status.
.SH "METHODS"
.IX Header "METHODS"
If current rate limit data is not resident, these methods will force a call to
\&\f(CW\*(C`rate_limit_status\*(C'\fR.  Therefore, any of these methods can throw an error.
.IP "rate_remaining" 4
.IX Item "rate_remaining"
Returns the number of \s-1API\s0 calls available before the next reset.
.IP "rate_reset" 4
.IX Item "rate_reset"
Returns the Unix epoch time of the next reset.
.IP "rate_limit" 4
.IX Item "rate_limit"
Returns the current hourly rate limit.
.IP "rate_ratio" 4
.IX Item "rate_ratio"
Returns remaining \s-1API\s0 call limit, divided by the time remaining before the next
reset, as a ratio of the total rate limit per hour.
.Sp
For example, if \f(CW\*(C`rate_limit\*(C'\fR is 150, the total rate is 150 \s-1API\s0 calls per hour.
If \f(CW\*(C`rate_remaining\*(C'\fR is 75, and there 1800 seconds (1/2 hour) remaining before
the next reset, \f(CW\*(C`rate_ratio\*(C'\fR returns 1.0, because there are exactly enough
\&\s-1API\s0 calls remaining to maintain he full rate of 150 calls per hour.
.Sp
If \f(CW\*(C`rate_remaining\*(C'\fR is 30 and there are 360 seconds remaining before reset,
\&\f(CW\*(C`rate_ratio\*(C'\fR returns 2.0, because there are enough \s-1API\s0 calls remaining
to maintain twice the full rate of 150 calls per hour.
.Sp
As a final example, if \f(CW\*(C`rate_remaining\*(C'\fR is 15, and there are 7200 seconds
remaining before reset, \f(CW\*(C`rate_ratio\*(C'\fR returns 0.5, because there are only
enough \s-1API\s0 calls remaining to maintain half the full rate of 150 calls per
hour.
.IP "until_rate($target_ratio)" 4
.IX Item "until_rate($target_ratio)"
Returns the number of seconds to wait before making another rate limited \s-1API\s0
call such that \f(CW$target_ratio\fR of the full rate would be available.  It
always returns a number greater than, or equal to zero.
.Sp
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 \s-1API\s0 calls as they
occur.
.Sp
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.
.Sp
A target rate > than 1.0 can be used for a process that should only use
\&\*(L"extra\*(R" available \s-1API\s0 calls.  This is useful for an application that requires
most of it's rate limit for normal operation.
.SH "AUTHOR"
.IX Header "AUTHOR"
Marc Mims <marc@questright.com>
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (c) 2016 Marc Mims
.PP
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.