at.borkowski.spicej.rt

Class RateCalculator

java.lang.Object

at.borkowski.spicej.rt.RateCalculator

public class RateCalculator
extends Object

A utility class for calculating parameters necessary for rate limitation of bytes per seconds. The way spiceJ works internally, three parameters are required to set up a byte-rate limited stream:

• Tick interval: How many nanoseconds are between two ticks (see TickSource)
• Bytes per tick: How many bytes are allowed to be transmitted/received per tick
• Prescale: By how much to divide the incoming ticks ( 1 - prescale ticks are skipped before actually allowing data to be sent or received). This is a possibility of skipping ticks to allow for very low bitrates without having extensive tick intervals.

This class allows for easy calculation of bytes per second to these three parametes while respecting some bounds:

• Minimum interval: The interval must not be shorter than MIN_INTERVAL_NS nanoseconds to avoid overhead by CPU usage.
• Maximum interval: An upper bound must not be exceeded for the tick interval, MAX_INTERVAL_NS ns.

The error generated by this class is influenced by the scale used in calculations (see SCALE) is tested by RateCalculatorTest (in test sources).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RateCalculator.Result

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_BYTES_PER_TICK The enforced upper bound for bytes per tick.
static double	MAX_ERROR The error margin permitted for calculations.
static int	MAX_INTERVAL_NS The enforced upper bound for the interval.
static float	MAX_RATE The highest byte rate representable with our data model (this is not necessarily the exact maximum value, but a value close enough to the maximum upper bound.
static int	MIN_INTERVAL_NS The default enforced lower bound for the interval.
static float	MIN_RATE The minimum byte rate representable with our data model (this is not necessarily the exact minimum value, but a value close enough to the minimum lower bound.
static int	NS_PER_S Nanoseconds per second.
static RoundingMode	ROUND The rounding mode (see BigDecimal) used for internal calculation.
static int	SCALE The scale (see BigDecimal) used for internal calculations.

Method Summary

Modifier and Type	Method and Description
static RateCalculator.Result	calculate(float rateBytesPerSecond) Performs a calculation with the default minimal interval (see MIN_INTERVAL_NS).
static RateCalculator.Result	calculate(float rateBytesPerSecond, int minInterval) Performs a calculation with the given minimal interval.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MIN_RATE

public static final float MIN_RATE

The minimum byte rate representable with our data model (this is not necessarily the exact minimum value, but a value close enough to the minimum lower bound.

See Also:

Constant Field Values

MAX_RATE

public static final float MAX_RATE

The highest byte rate representable with our data model (this is not necessarily the exact maximum value, but a value close enough to the maximum upper bound.

See Also:

Constant Field Values

NS_PER_S

public static final int NS_PER_S

Nanoseconds per second.

See Also:

Constant Field Values

MIN_INTERVAL_NS

public static final int MIN_INTERVAL_NS

The default enforced lower bound for the interval. Intervals lower than this might not be reliably possible on some hardware.

See Also:

Constant Field Values

MAX_INTERVAL_NS

public static final int MAX_INTERVAL_NS

The enforced upper bound for the interval. Rates requiring a higher interval will be forced to be realized use prescaling.

See Also:

Constant Field Values

MAX_BYTES_PER_TICK

public static final int MAX_BYTES_PER_TICK

The enforced upper bound for bytes per tick. Higher values result in a bigger buffer and higher memory usage.

See Also:

Constant Field Values

SCALE

public static final int SCALE

The scale (see BigDecimal) used for internal calculations.

See Also:

Constant Field Values

ROUND

public static final RoundingMode ROUND

The rounding mode (see BigDecimal) used for internal calculation.

MAX_ERROR

public static final double MAX_ERROR

The error margin permitted for calculations.

See Also:

Constant Field Values

Method Detail

calculate

public static RateCalculator.Result calculate(float rateBytesPerSecond)

Performs a calculation with the default minimal interval (see MIN_INTERVAL_NS). See RateCalculator for details.

Parameters:

rateBytesPerSecond - The rate in bytes per second to target

Returns:

the calculation result

calculate

public static RateCalculator.Result calculate(float rateBytesPerSecond,
                                              int minInterval)

Performs a calculation with the given minimal interval. See RateCalculator for details.

Parameters:

rateBytesPerSecond - The rate in bytes per second to target

minInterval - The minimal interval in nanoseconds.

Returns:

the calculation result