AverageRateLimiter (EngineBlock API)

java.lang.Object
- io.engineblock.activityapi.rates.AverageRateLimiter

All Implemented Interfaces:

Startable, RateLimiter
```
public class AverageRateLimiter
extends Object
implements Startable, RateLimiter
```
This rate limiter uses nanoseconds as the unit of timing. This works well because it is the native precision of the system timer interface via System.nanoTime(). It is also low-error in terms of rounding between floating point rates and nanoseconds, at least in the round numbers that users tend to use. Further, the current scheduling state is maintained as an atomic view of accumulated nanoseconds granted to callers -- referred to here as the ticks accumulator. This further simplifies the implementation by allowing direct comparison of scheduled times with the current state of the high-resolution system timer.
Each time acquire() or acquire(long) is called, a discrete scheduled time is calculated from the current state of the ticks accumulator. If the calculated time is in the future, then the method blocks (in the calling thread) using Thread.sleep(long, int). Finally, the method is unblocked, and the nanosecond scheduling gap is returned to the caller.
This implementation of the rate limiter is simplified to only support averaging rate limits. The RateLimiters class provides a convenient way for using either the averaging rate limiter or the strict rate limiter at runtime, while allowing the averaging rate limiter to be used when desired for higher client-side throughput.
Note that the ticks accumulator can not rate limit a single event. Acquiring a grant at some nanosecond size simply consumes nanoseconds from the schedule, with the start time of the allotted time span being conceptually aligned with the start time of the requested event. In other words, previous allocations of the timeline determine the start time of a subsequent caller, not the caller itself.

Field Summary

Fields
Modifier and Type Field and Description

protected AtomicLong ticksTimeline

Fields
Modifier and Type	Field and Description
`protected AtomicLong`	`ticksTimeline`

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`AverageRateLimiter()`
	`AverageRateLimiter(ActivityDef def, String label, RateSpec rateSpec)` Create a rate limiter.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`long`	`acquire()` Block until it is time for the next operation, according to the nanoseconds per op as set by `RateLimiter.setRate(double)`
`long`	`acquire(long nanos)` See `AverageRateLimiter` for interface docs.
`long`	`getLastSeenNanoTimeline()` visible for testing
`protected long`	`getNanoClockTime()`
`long`	`getOpNanos()` Get the number of nanoseconds allotted to each operations.
`double`	`getRate()` Return the rate in ops/s.
`protected long`	`getRateSchedulingDelay()`
`RateSpec`	`getRateSpec()` Get the rate spec that this rate limiter was created from.
`AtomicLong`	`getTicksTimeline()` * visible for testing
`long`	`getTotalSchedulingDelay()` Return the total number of nanoseconds behind schedule that this rate limiter is, including the full history across all rates.
`protected void`	`init()`
`protected void`	`setActivityDef(ActivityDef def)`
`protected void`	`setLabel(String label)`
`void`	`setRate(double rate)` Set the rate in ops/s.
`void`	`setRateSpec(RateSpec updatingRateSpec)` Modify the rate of a running rate limiter.
`void`	`start()`
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - ticksTimeline
```
protected final AtomicLong ticksTimeline
```
- Constructor Detail
  - AverageRateLimiter
```
protected AverageRateLimiter()
```
  - AverageRateLimiter
```
public AverageRateLimiter(ActivityDef def,
                          String label,
                          RateSpec rateSpec)
```
    Create a rate limiter.
    
    Parameters:
    
    def - The activity definition for this rate limiter
    
    label - The label for the rate limiting facet within the activity
    
    rateSpec - the rate limiter configuration
- Method Detail
  - setLabel
```
protected void setLabel(String label)
```
  - setActivityDef
```
protected void setActivityDef(ActivityDef def)
```
  - init
```
protected void init()
```
  - getNanoClockTime
```
protected long getNanoClockTime()
```
  - acquire
```
public long acquire(long nanos)
```
    See AverageRateLimiter for interface docs. effective calling overhead of acquire() is ~20ns
    
    Specified by:
    
    acquire in interface RateLimiter
    
    Parameters:
    
    nanos - nanoseconds of time allotted to this event
    
    Returns:
    
    nanoseconds that have already elapsed since this event's ideal time
  - acquire
```
public long acquire()
```
    Description copied from interface: RateLimiter
    
    Block until it is time for the next operation, according to the nanoseconds per op as set by RateLimiter.setRate(double)
    
    Specified by:
    
    acquire in interface RateLimiter
    
    Returns:
    
    the number of nanos behind schedule when this op returns
  - getOpNanos
```
public long getOpNanos()
```
    Description copied from interface: RateLimiter
    
    Get the number of nanoseconds allotted to each operations.
    
    Specified by:
    
    getOpNanos in interface RateLimiter
    
    Returns:
    
    nanosecond op length
  - getRate
```
public double getRate()
```
    Description copied from interface: RateLimiter
    
    Return the rate in ops/s.
    
    Specified by:
    
    getRate in interface RateLimiter
    
    Returns:
    
    ops/s
  - setRate
```
public void setRate(double rate)
```
    Description copied from interface: RateLimiter
    
    Set the rate in ops/s. This is a friendly way to calculate the nanoseconds per op.
    
    Specified by:
    
    setRate in interface RateLimiter
    
    Parameters:
    
    rate - The desired ops/s rate.
  - getTotalSchedulingDelay
```
public long getTotalSchedulingDelay()
```
    Description copied from interface: RateLimiter
    
    Return the total number of nanoseconds behind schedule that this rate limiter is, including the full history across all rates. When the rate is changed, this value is check-pointed to an accumulator and also included in any subsequent measurement.
    
    Specified by:
    
    getTotalSchedulingDelay in interface RateLimiter
    
    Returns:
    
    nanoseconds behind schedule since the rate limiter was started
  - getRateSchedulingDelay
```
protected long getRateSchedulingDelay()
```
  - start
```
public void start()
```
    Specified by:
    
    start in interface Startable
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - getRateSpec
```
public RateSpec getRateSpec()
```
    Description copied from interface: RateLimiter
    
    Get the rate spec that this rate limiter was created from.
    
    Specified by:
    
    getRateSpec in interface RateLimiter
    
    Returns:
    
    a RateSpec that describes this rate limiter
  - setRateSpec
```
public void setRateSpec(RateSpec updatingRateSpec)
```
    Description copied from interface: RateLimiter
    
    Modify the rate of a running rate limiter.
    
    Specified by:
    
    setRateSpec in interface RateLimiter
    
    Parameters:
    
    updatingRateSpec - The rate and burstRatio specification
  - getTicksTimeline
```
public AtomicLong getTicksTimeline()
```
    * visible for testing
    
    Returns:
    
    ticksTimeline value - the long value of the shared timeslice marker
  - getLastSeenNanoTimeline
```
public long getLastSeenNanoTimeline()
```
    visible for testing
    
    Returns:
    
    lastSeenNanoTime - the long value of the shared view of the clock

Class AverageRateLimiter

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ticksTimeline

Constructor Detail

AverageRateLimiter

AverageRateLimiter

Method Detail

setLabel

setActivityDef

init

getNanoClockTime

acquire

acquire

getOpNanos

getRate

setRate

getTotalSchedulingDelay

getRateSchedulingDelay

start

toString

getRateSpec

setRateSpec

getTicksTimeline

getLastSeenNanoTimeline