biz.onixs.util

Class Throttler

java.lang.Object

biz.onixs.util.Throttler

public class Throttler
extends Object

Limits an event rate using the event time marks.

The limitation of the event rate is based on tracking of timestamps, that are associated with each traceable event. The timestamp is just a long number, that continuously increased or at least keeps the same between two sequential events. In particular cases it can be "milliseconds since epoch", "microseconds since epoch", or something other - this must be considered by the users code.

The allowed event rate is specified as "the maximum number of events within the given interval", where the interval must be specified using the same measurement units, as ones used for time marks of events. Talking more formally, the allowed rate is a maximum number of sequential events where the difference between time marks of the first and the last event is less or equal to the specified interval.

The rate specification is passed via constructor parameters during construction of a new instance of the throttler, or via reset(int, long) method.

Tracing of events is implemented by the tryAdd(long) method. This method returns a value that denotes "allowing" or "disallowing" for the given event:

• If the value is zero, the event "allowed", and the appropriate time mark will be kept by the throttler.
• If the value is greater than zero, the adding failed, and the appropriate event "disallowed". Also, the returned values denote the number of units that must be added to the time mark to succeed the adding.

In the most trivial case, if the time mark is measured in milliseconds and obtained from the System.currentTimeMillis() call, the non-zero value returned by tryAdd(long) method denotes the number of milliseconds that have to be passed to the subsequent Thread.sleep(long) in the user's code.

 Throttler throttler = new Throttler(NUMBER_OF_EVENTS, INTERVAL_IN_MILLIS);
 // ...
 while(!stopCondition) {
     long wait = throttler.tryAdd(System.currentTimeMillis());
     if (wait == 0) {
         break; // Time mark added
     }
     Thread.sleep(wait); // Wait for the required time
 }
 

Each throttler can be "active" and "inactive":

• Active throttler has some valid interval and the number of events, that are specified via constructor parameters, or via the reset(int, long) method.
• Inactive throttler was created without rate specification, or the reset() method has been used there. Calls to the tryAdd(long) method always return zero.

The throttler is not thread-safe so appropriate synchronization must be used for multithreaded access to the single throttler.

Constructor Summary

Constructors

Constructor and Description
Throttler() Creates the inactive throttler.
Throttler(int maxEvents, long interval) Creates the active throttler.

Method Summary

Modifier and Type	Method and Description
long	getInterval() Returns interval duration.
int	getMaxEvents() Returns maximum number of events for the given interval.
boolean	isActive() Checks if the throttler active.
void	reset() Deactivates the throttler.
void	reset(int maxEvents, long interval) Resets the throttler.
String	toString() String representation of the throttler.
long	tryAdd(long timeMark) Tries to put new time mark into internal storage of the throttler.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Throttler

public Throttler()

Creates the inactive throttler.

The inactive throttler always "allows" events, i.e. its tryAdd(long) method returns zero. The throttler can be activated by the reset(int, long) method.

Throttler

public Throttler(int maxEvents,
                 long interval)

Creates the active throttler.

The active throttler has a valid event rate specification, and its tryAdd(long) method returns a value depending on the actual event rate.

Parameters:

maxEvents - Maximum number of events allowed within the given interval. The value must be greater than zero.

interval - The interval length. The value must be greater than zero.

Method Detail

isActive

public boolean isActive()

Checks if the throttler active.

Returns:

• true - if the throttler active (some valid rate specified);
• false - otherwise.

getMaxEvents

public int getMaxEvents()

Returns maximum number of events for the given interval.

Returns:

• >0 - the specified number of events allowed during the given interval(if the throttler is active);
• -1 - the throttler inactive.

getInterval

public long getInterval()

Returns interval duration.

Returns:

• >0 - the specified duration of the throttling interval (if the throttler is active);
• -1 - the throttler inactive.

reset

public void reset(int maxEvents,
                  long interval)

Resets the throttler.

Resets the throttler or turns it into active state. All stored time marks removed.

Parameters:

maxEvents - Maximum number of events allowed within the given interval. The value must be greater than zero.

interval - The interval length. The value must be greater than zero.

reset

public void reset()

Deactivates the throttler.

Turns the throttler to the "inactive" state, so all the tryAdd(long) calls will return zero.

tryAdd

public long tryAdd(long timeMark)

Tries to put new time mark into internal storage of the throttler.

Parameters:

timeMark - The mark to add.

Returns:

• 0 - the adding succeeded.
• >0 - the adding failed, and the time mark must be increased by the returned value.

toString

public String toString()

String representation of the throttler.

Overrides:

toString in class Object

Returns:

The string representation.