org.opensolaris.os.dtrace
Class LogDistribution

java.lang.Object
  extended by org.opensolaris.os.dtrace.Distribution
      extended by org.opensolaris.os.dtrace.LogDistribution
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<LogDistribution>, java.lang.Iterable<Distribution.Bucket>, AggregationValue

public final class LogDistribution
extends Distribution
implements java.io.Serializable, java.lang.Comparable<LogDistribution>

A power-of-two logarithmic frequency distribution aggregated by the DTrace quantize() action. Aggregated values fall into consecutive ranges, each twice as large as the previous range. Each range, known as a bucket, begins at two to the power of n and ends at one less than the beginning of the next bucket, two to the power of n + 1. The zero bucket is the degenerate case and holds the frequency of the base value zero. For example, the first bucket after 0 starts at 1 (2 to the power of 0) and ends at 1 (one less than 2 to the power of 1). The next bucket starts at 2 (2 to the power of 1) and ends at 3 (one less than 2 to the power of 2). Each bucket frequency is incremented for each aggregated value that falls into its range. Buckets are typically identified by their lower bound: 1, 2, 4, 8, etc. Mirroring these are buckets with negative ranges: -1, -2, -4, -8, etc. The range of an entire LogDistribution is (-263 .. 263).

Immutable. Supports persistence using XMLEncoder.

See Also:
LinearDistribution, Aggregation, Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class org.opensolaris.os.dtrace.Distribution
Distribution.Bucket
 
Constructor Summary
LogDistribution(java.util.List<Distribution.Bucket> frequencies)
          Creates a logarithmic distribution with the given frequencies.
 
Method Summary
 int compareTo(LogDistribution d)
          Compares the double values of getValue() for overall magnitude, and if those are equal, compares the frequencies at the zero bucket (the bucket whose range has a minimum and maximum value of zero).
 java.lang.Number getValue()
          Gets the numeric value of this distribution used to compare distributions by overall magnitude, defined as the sum total of each bucket's frequency times the minimum of its range.
 
Methods inherited from class org.opensolaris.os.dtrace.Distribution
asList, equals, get, getBuckets, getDisplayRange, getTotal, hashCode, iterator, size, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

LogDistribution

public LogDistribution(java.util.List<Distribution.Bucket> frequencies)
Creates a logarithmic distribution with the given frequencies. Supports XML persistence.

Parameters:
frequencies - list of frequencies in bucket ranges bounded by consucutive powers of two
Throws:
java.lang.NullPointerException - if frequencies is null
java.lang.IllegalArgumentException - if any bucket does not have the expected range (bounded by consecutive powers of two)
Method Detail

getValue

public java.lang.Number getValue()
Description copied from class: Distribution
Gets the numeric value of this distribution used to compare distributions by overall magnitude, defined as the sum total of each bucket's frequency times the minimum of its range.

Specified by:
getValue in interface AggregationValue
Specified by:
getValue in class Distribution
Returns:
non-null numeric value

compareTo

public int compareTo(LogDistribution d)
Compares the double values of getValue() for overall magnitude, and if those are equal, compares the frequencies at the zero bucket (the bucket whose range has a minimum and maximum value of zero).

Specified by:
compareTo in interface java.lang.Comparable<LogDistribution>