Package io.engineblock.activityapi.ratelimits

Class RateSpec

  • public class RateSpec
extends java.lang.Object

    Rate Limiter Specifications

    A rate spec represent the configuration of a rate limiter. It is the event carrier for applying changes to a rate limiter. For scripting purposes, rate limiters can be controlled via assignment of a configuration string. A future version of the scripting API will support direct method access. For now, the following semantics will apply to the configuration value assigned to any of the rate parameters like cyclerate and striderate.

    Controlling Rate Limiters

    Rate limiters specifiers can be easily constructed programmatically. However, in scripting, these will often be controlled by assigning a configuration string.

    When a rate limiter is configured using the configuration String, it can be in one of the following forms:

    • <rate>
    • <rate>,<burst ratio>
    • <rate>,<burst ratio>,<verb>
    Where: rate is the ops per second, expressed as any positive floating point value. burst ratio is a floating point value greater than 1.0 which determines how much faster the rate limiter may go to catch up to the overall. verb is one of configure, start, or restart, as explained below. For example:
    • 200 - allow up to 200 ops to start per second, with the default burst ratio of 1.1. Start the rate limiter automatically.
    • 3.6,2 - Allow up to 3.6 ops to start per second, but allow up to 7.2 ops per second if needed to catch up. Start the rate limiter automatically
    • 1000,1.05,restart - Allow up to 1000 ops per second on average, but allow 1050 ops per second if the workload gets behind. If the rate limiter was already running, restart it, clearing any previous backlog (wait time) and resource pools.

    Rate Limiter Life Cycle

    A rate limiter can be directly configured, started, restarted. Indirectly, rate limiter construction and initialization occurs as needed.

    (constructed)
    Rate limiters are constructed and assigned automatically when they are first configured. A rate limiter may not be explicitly constructed by the user.
    configure
    When a rate limiter is configured, the rate spec is applied to it. If the rate limiters is already running, then this new rate is applied to it. Applying the same rate parameters a second time to a given rate limiter is a no-op.
    (initialization)
    A rate limiter is initialized immediately before it is initially started. Rate limiters are also re-initialized when they are restarted. When a rate limiter is initialized, the start time is set to the current time, and the resource pools and accumulated wait time are zeroed. A rate limiter may not be explicitly initialized by the user.
    start
    Starting a rate limiter activates the rate metering logic according to the current time. From the time a rate limiter is started, any unused time will accumulate as wait time. A rate limiter is required to be reset immediately before it is started for the first time.
    restart
    Restarting a rate limiter is the same as starting it initially. The only difference is that restarting forces a re-initialization as part of the configuration.

    • Field Detail

      • opsPerSec

        public double opsPerSec
        Target rate in Operations Per Second

      • burstRatio

        public double burstRatio

    • Constructor Detail

      • RateSpec

        public RateSpec​(double opsPerSec,
                double burstRatio)

      • RateSpec

        public RateSpec​(double opsPerSec,
                double burstRatio,
                RateSpec.Verb type)

      • RateSpec

        public RateSpec​(java.lang.String spec)

    • Method Detail

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • withOpsPerSecond

        public RateSpec withOpsPerSecond​(double rate)

      • withBurstRatio

        public RateSpec withBurstRatio​(double burstRatio)

      • getNanosPerOp

        public long getNanosPerOp()

      • getRate

        public double getRate()

      • getBurstRatio

        public double getBurstRatio()

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • isAutoStart

        public boolean isAutoStart()

      • isRestart

        public boolean isRestart()