[improve][broker] Optimize AsyncTokenBucket overflow solution further to reduce fallback to BigInteger

[lhotari]

Motivation

#25262 added a solution to prevent overflow in token & duration calculations. The solution falls back to the usage of BigInteger for very large values. This PR introduces yet another optimization that reduces the need to fallback to BigInteger.
This would be relevant when using multi gigabyte byte rate limits.

Modifications

• Add an internal RateParameters class which precalculates reduced values where the operands are reduced by dividing by the highest common power of ten.

Documentation

• doc
• doc-required
• doc-not-needed
• doc-complete

[codecov-commenter]

Codecov Report

❌ Patch coverage is 80.95238% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.60%. Comparing base (c27ec7d) to head (d25f3d0).
⚠️ Report is 102 commits behind head on master.

Files with missing lines	Patch %	Lines
...org/apache/pulsar/broker/qos/AsyncTokenBucket.java	80.95%	3 Missing and 5 partials ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             master   #25269       +/-   ##
=============================================
+ Coverage     37.33%   72.60%   +35.27%     
- Complexity    13272    34441    +21169     
=============================================
  Files          1902     1959       +57     
  Lines        151358   155543     +4185     
  Branches      17252    17741      +489     
=============================================
+ Hits          56502   112938    +56436     
+ Misses        87162    33592    -53570     
- Partials       7694     9013     +1319     

Flag	Coverage Δ
inttests	25.72% <0.00%> (+0.09%)	⬆️
systests	22.33% <0.00%> (-0.06%)	⬇️
unittests	73.59% <80.95%> (+39.56%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...org/apache/pulsar/broker/qos/AsyncTokenBucket.java	83.80% <80.95%> (+52.85%)	⬆️

... and 1418 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull request overview

This PR further hardens AsyncTokenBucket’s overflow-safe arithmetic by caching pre-reduced rate parameters (rate and rate period) to reduce how often computations must fall back to BigInteger, which is especially relevant for very large byte-rate limits.

Changes:

• Introduce an internal cached RateParameters helper that reduces (rate, ratePeriodNanos) by their highest common power of ten.
• Route token-refill and throttling-duration calculations through the reduced parameters.
• Expand AsyncTokenBucketTest coverage with additional very-large rate inputs.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
pulsar-broker/src/main/java/org/apache/pulsar/broker/qos/AsyncTokenBucket.java	Adds cached reduced-rate parameters and uses them in refill/throttling calculations to reduce BigInteger fallback.
pulsar-broker/src/test/java/org/apache/pulsar/broker/qos/AsyncTokenBucketTest.java	Adds larger rate values to exercise overflow-safe paths at multi-GB/s scale.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.