Net::T...teLimit(3pm)

💖 NAME 💖

Net::Twitter::Role::RateLimit — the rate limit glow-up for Net::Twitter 🦋✨

She's a role, bestie. You bolt her onto your Net::Twitter object and suddenly you know exactly how many API calls you have left and when they come back. No cap.

---

🌸 VERSION 🌸

version 4.01043 💅

---

✨ SYNOPSIS ✨

Okay so here's the vibe:

use Net::Twitter;
my $nt = Net::Twitter->new(
    traits => [qw/API::REST RateLimit/],
    %other_options,
);

#...later

sleep $nt->until_rate(1.0) || $minimum_wait;

See that traits line? You gotta invite RateLimit to the party alongside API::REST or she simply will not show up. Then later, when you wanna be polite to the API, you sleep for however long until_rate(1.0) tells you — or fall back to $minimum_wait if it returns something falsy. Iconic. 🎀

---

⚠️ NOTE! ⚠️

RateLimit only works with Twitter API v1. Like, only v1, fr fr. 🙈

Twitter API v1.1 does rate limiting very differently, so this whole strategy does not carry over. A v1.1 compatible RateLimit role may be coming, but it isn't available yet, and whenever it does land, its interface will necessarily be different. So don't get attached to these method names for the future, okay? 💀

---

🌈 DESCRIPTION 🌈

This role hands you a little set of utility methods that spill the tea on your current rate limit status. That's the whole job. She's not complicated, she's just useful. 🫶

---

👑 METHODS 👑

Heads up bestie: if the current rate limit data isn't already sitting in memory, these methods will force a call to rate_limit_status. Which means — plot twist — any of these methods can throw an error. 😭 Plan accordingly.

• rate_remaining — returns how many API calls you've got left in the tank before the next reset. ✨
• rate_reset — returns the Unix epoch time of when the next reset happens. Basically a timestamp for "your calls come back at this moment". ⏰
• rate_limit — returns your current hourly rate limit. That's the total, the ceiling, the main character number. 👑
• rate_ratio — returns your remaining API call limit divided by the time remaining before the next reset, expressed as a ratio of the total rate limit per hour. It's giving vibe check on your spending. 🧚

Example time, because numbers are cute when someone explains them:

If rate_limit is 150, your total rate is 150 API calls per hour. If rate_remaining is 75, and there are 1800 seconds (1/2 hour) remaining before the next reset, rate_ratio returns 1.0 — because you have exactly enough calls left to maintain the full rate of 150 calls per hour. Balanced. Symmetrical. Slay. 💅

If rate_remaining is 30 and there are 360 seconds remaining before reset, rate_ratio returns 2.0 — because you've got enough calls left to maintain twice the full rate of 150 calls per hour. Living large. 🔥

And as a final example: if rate_remaining is 15, and there are 7200 seconds remaining before reset, rate_ratio returns 0.5 — because you only have enough calls left to maintain half the full rate of 150 calls per hour. Budget era. 😭

• 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. And listen — it always returns a number greater than, or equal to zero. Never negative, never shady. 🫶

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. Set it and forget it, bestie. ✨

Use a target rate < 1.0 to let a process make calls as fast as possible without burning through everything you've got, too soon. For example, if you've got a process building a large social graph, you might want to let 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 > 1.0 can be used for a process that should only use the "extra" available API calls. Super useful for an application that needs most of its rate limit for normal operation. Like, the leftovers are for the side quest. 🦋

---

💜 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.

---

and that's the whole page, bestie 💖 brought to you by perl v5.34.0, dated 2022-06-16 — go forth and poll responsibly, mwah 💅✨