NAME

       Net::Twitter::Role::RateLimit - Rate limit features for Net::Twitter

VERSION

       version 4.01043

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) 2016 Marc Mims

       This library is free software; you can redistribute it and/or modify it under  the  same  terms  as  Perl
       itself.

perl v5.34.0                                       2022-06-16                 Net::Twitter::Role::RateLimit(3pm)