Class SimRateSpec

java.lang.Object
io.nosqlbench.engine.api.activityapi.simrate.SimRateSpec
Direct Known Subclasses:
CycleRateSpec, StrideRateSpec
public class SimRateSpec extends 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.

ChronoUnit Examples


 <p>
 example ticks   op/s          seconds/op   ticks/op
 -----------------------------------------------------------
 1       ns      50   ops/s    0.02, 1/20      20_000_000  (1s of ns / 50)
 2       ns       5   ops/s    0.2,  1/2      200_000_000  (1s of ns / 5)
 3       ns       0.5 ops/s    2.0   2/1    2_000_000_000  (1s of ns / 0.5)
 4       us       0.5 ops/s    2.0   2/1        2_000_000  (1s of us / 0.5)
 5       ms       0.5 ops/s    2.0   2/1            2_000  (1s of ms / 0.5)
  • In examples 1 and 2, the ticks/op are comfortably within the 2147483648 (2^31) range afforded by a 32-bit semaphore count.
  • Example 3 shows where the value technically fits, but leaves no more than around 8% margin for the burst pool. This is insufficient as burst pool should be allowed to be up to 100% the size of the base rate pool.
  • This is remedied in examples 4 and 5 by adjusting the unit of allocation to bigger chunks of time.

  • Field Details

    • DEFAULT_RATE_OPS_S

      public static final double DEFAULT_RATE_OPS_S
      See Also:

    • DEFAULT_BURST_RATIO

      public static final double DEFAULT_BURST_RATIO
      See Also:

    • DEFAULT_VERB

      public static SimRateSpec.Verb DEFAULT_VERB

    • unit

      public ChronoUnit unit

    • opsPerSec

      public double opsPerSec
      Target rate in Operations Per Second

    • burstRatio

      public double burstRatio

    • verb

      public SimRateSpec.Verb verb

  • Constructor Details

    • SimRateSpec

      public SimRateSpec(double opsPerSec, double burstRatio)

    • SimRateSpec

      public SimRateSpec(double opsPerSec, double burstRatio, SimRateSpec.Verb verb)

    • SimRateSpec

      public SimRateSpec(double opsPerSec, double burstRatio, SimRateSpec.Scope scope)

    • SimRateSpec

      public SimRateSpec(double opsPerSec, double burstRatio, SimRateSpec.Verb verb, SimRateSpec.Scope scope)

    • SimRateSpec

      public SimRateSpec(ParameterMap.NamedParameter tuple)

    • SimRateSpec

      public SimRateSpec(String spec)

  • Method Details

    • burstRatio

      public double burstRatio()

    • ticksPerOp

      public int ticksPerOp()

    • nanosToTicks

      public int nanosToTicks(long newNanoTokens)

    • ticksToNanos

      public long ticksToNanos(int newTicks)

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getRate

      public double getRate()

    • getBurstRatio

      public double getBurstRatio()

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • getVerb

      public SimRateSpec.Verb getVerb()

    • isAutoStart

      public boolean isAutoStart()

    • isRestart

      public boolean isRestart()

    • getScope

      public SimRateSpec.Scope getScope()