[FLINK-40326][core] Do not over-grant capacity in GatedRateLimiter

[Savonitar]

What is the purpose of the change

The decrement in acquire() was generalized from a constant 1 to numberOfEvents as part of FLIP-535, but the gate was left closing only at capacityLeft <= 0, so a cycle can admit more events than capacityPerCycle. The gate is now closed unless the capacity left covers the whole request.

Brief change log

• Close the gate in GatedRateLimiter#acquire(int) unless the capacity left covers the whole request, rather than only once it has reached zero
• Reject a non-positive numberOfEvents
• Initialize gatingFuture eagerly, so notifyCheckpointComplete before the first acquire() no longer throws a NullPointerException
• Correct the class Javadoc

Verifying this change

This change added the following tests:

• Added four tests to GatedRateLimiterTest, one per defect, each fails against the unfixed code

Does this pull request potentially affect one of the following parts:

• Dependencies (does it add or upgrade a dependency): (no)
• The public API, i.e., is any changed class annotated with @Public(Evolving): (yes, but Javadoc only )
• The serializers: (no, a transient modifier is dropped, but GatedRateLimiter does not implement Serializable (only RateLimiterStrategy does), so it had no effect.)
• The runtime per-record code paths (performance sensitive): (yes, acquire(int) is called once per input record when rate limiting is enabled.)
• Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: (no)
• The S3 file system connector: (no)

Documentation

• Does this pull request introduce a new feature? (no)
• If yes, how is the feature documented? (not applicable)

---

Was generative AI tooling used to co-author this PR?

• Yes (please specify the tool below)

Generated-by: [Tool Name and Version]

[flinkbot]

CI report:

• 0988ec0 Azure: SUCCESS

Bot commands

The @flinkbot bot supports the following commands:

• @flinkbot run azure re-run the last Azure build