Struct hdrhistogram::sync::SyncHistogram

pub struct SyncHistogram<C: Counter> { /* fields omitted */ }

A Histogram that can be written to by multiple threads concurrently.

Each writer thread should have a Recorder, which allows it to record new samples without synchronization. New recorded samples are made available through this histogram by calling SyncHistogram::refresh, which blocks until it has synchronized with every recorder.

Methods

impl<C: Counter> SyncHistogram<C>

pub fn refresh(&mut self)

Block until writes from all Recorder instances for this histogram have been incorporated.

pub fn refresh_timeout(&mut self, timeout: Duration)

Block until writes from all Recorder instances for this histogram have been incorporated, or until the given amount of time has passed.

pub fn recorder(&self) -> Recorder<C>

Obtain another multi-threaded writer for this histogram.

Note that writes made to the Recorder will not be visible until the next call to SyncHistogram::refresh.

Methods from Deref<Target = Histogram<C>>

pub fn distinct_values(&self) -> usize

Get the current number of distinct values that can be represented in the histogram.

pub fn low(&self) -> u64

Get the lowest discernible value for the histogram in its current configuration.

pub fn high(&self) -> u64

Get the highest trackable value for the histogram in its current configuration.

pub fn sigfig(&self) -> u8

Get the number of significant value digits kept by this histogram.

pub fn count(&self) -> u64

Deprecated since 6.0.0:

use len instead

Get the total number of samples recorded.

pub fn len(&self) -> u64

Get the total number of samples recorded.

pub fn is_empty(&self) -> bool

Returns true if this histogram has no recorded values.

pub fn buckets(&self) -> u8

Get the number of buckets used by the histogram to cover the highest trackable value.

This method differs from .len() in that it does not count the sub buckets within each bucket.

This method is probably only useful for testing purposes.

pub fn clone_correct(&self, interval: u64) -> Histogram<T>

Get a copy of this histogram, corrected for coordinated omission.

To compensate for the loss of sampled values when a recorded value is larger than the expected interval between value samples, the new histogram will include an auto-generated additional series of decreasingly-smaller (down to the interval) value records for each count found in the current histogram that is larger than the interval.

Note: This is a post-correction method, as opposed to the at-recording correction method provided by record_correct. The two methods are mutually exclusive, and only one of the two should be be used on a given data set to correct for the same coordinated omission issue.

See notes in the description of the Histogram calls for an illustration of why this corrective behavior is important.

If interval is larger than 0, add auto-generated value records as appropriate if value is larger than interval.

pub fn set_to<B: Borrow<Histogram<T>>>(
    &mut self,
    source: B
) -> Result<(), AdditionError>

Overwrite this histogram with the given histogram. All data and statistics in this histogram will be overwritten.

pub fn set_to_corrected<B: Borrow<Histogram<T>>>(
    &mut self,
    source: B,
    interval: u64
) -> Result<(), RecordError>

Overwrite this histogram with the given histogram while correcting for coordinated omission. All data and statistics in this histogram will be overwritten. See clone_correct for more detailed explanation about how correction is applied

pub fn add<B: Borrow<Histogram<T>>>(
    &mut self,
    source: B
) -> Result<(), AdditionError>

Add the contents of another histogram to this one.

Returns an error if values in the other histogram cannot be stored; see AdditionError.

pub fn add_correct<B: Borrow<Histogram<T>>>(
    &mut self,
    source: B,
    interval: u64
) -> Result<(), RecordError>

Add the contents of another histogram to this one, while correcting for coordinated omission.

To compensate for the loss of sampled values when a recorded value is larger than the expected interval between value samples, the values added will include an auto-generated additional series of decreasingly-smaller (down to the given interval) value records for each count found in the current histogram that is larger than interval.

Note: This is a post-recording correction method, as opposed to the at-recording correction method provided by record_correct. The two methods are mutually exclusive, and only one of the two should be be used on a given data set to correct for the same coordinated omission issue.

See notes in the description of the Histogram calls for an illustration of why this corrective behavior is important.

See RecordError for error conditions.

pub fn subtract<B: Borrow<Histogram<T>>>(
    &mut self,
    subtrahend: B
) -> Result<(), SubtractionError>

Subtract the contents of another histogram from this one.

See SubtractionError for error conditions.

pub fn clear(&mut self)

Clear the contents of this histogram while preserving its statistics and configuration.

pub fn reset(&mut self)

Reset the contents and statistics of this histogram, preserving only its configuration.

pub fn auto(&mut self, enabled: bool)

Control whether or not the histogram can auto-resize and auto-adjust it's highest trackable value as high-valued samples are recorded.

pub fn record(&mut self, value: u64) -> Result<(), RecordError>

Record value in the histogram.

Returns an error if value exceeds the highest trackable value and auto-resize is disabled.

pub fn saturating_record(&mut self, value: u64)

Record value in the histogram, clamped to the range of the histogram.

This method cannot fail, as any values that are too small or too large to be tracked will automatically be clamed to be in range. Be aware that this will hide extreme outliers from the resulting histogram without warning. Since the values are clamped, the histogram will also not be resized to accomodate the value, even if auto-resize is enabled.

pub fn record_n(&mut self, value: u64, count: T) -> Result<(), RecordError>

Record multiple samples for a value in the histogram, adding to the value's current count.

count is the number of occurrences of this value to record.

Returns an error if value cannot be recorded; see RecordError.

pub fn saturating_record_n(&mut self, value: u64, count: T)

Record multiple samples for a value in the histogram, each one clamped to the histogram's range.

count is the number of occurrences of this value to record.

This method cannot fail, as values that are too small or too large to be recorded will automatically be clamed to be in range. Be aware that this will hide extreme outliers from the resulting histogram without warning. Since the values are clamped, the histogram will also not be resized to accomodate the value, even if auto-resize is enabled.

pub fn record_correct(
    &mut self,
    value: u64,
    interval: u64
) -> Result<(), RecordError>

Record a value in the histogram while correcting for coordinated omission.

See record_n_correct for further documentation.

pub fn record_n_correct(
    &mut self,
    value: u64,
    count: T,
    interval: u64
) -> Result<(), RecordError>

Record multiple values in the histogram while correcting for coordinated omission.

To compensate for the loss of sampled values when a recorded value is larger than the expected interval between value samples, this method will auto-generate and record an additional series of decreasingly-smaller (down to interval) value records.

Note: This is a at-recording correction method, as opposed to the post-recording correction method provided by correct_clone. The two methods are mutually exclusive, and only one of the two should be be used on a given data set to correct for the same coordinated omission issue.

Returns an error if value exceeds the highest trackable value and auto-resize is disabled.

Important traits for HistogramIterator<'a, T, P>

impl<'a, T: 'a, P> Iterator for HistogramIterator<'a, T, P> where
    T: Counter,
    P: PickyIterator<T>,  type Item = IterationValue<T>;

pub fn iter_quantiles(
    &self,
    ticks_per_half_distance: u32
) -> HistogramIterator<T, Iter<T>>

Iterate through histogram values by quantile levels.

The iteration mechanic for this iterator may appear somewhat confusing, but it yields fairly pleasing output. The iterator starts with a quantile step size of 1/halving_period. For every iteration, it yields a value whose quantile is that much greater than the previously emitted quantile (i.e., initially 0, 0.1, 0.2, etc.). Once halving_period values have been emitted, the quantile step size is halved, and the iteration continues.

ticks_per_half_distance must be at least 1.

The iterator yields an iterators::IterationValue struct.

One subtlety of this iterator is that you can reach a value whose cumulative count yields a quantile of 1.0 far sooner than the quantile iteration would reach 1.0. Consider a histogram with count 1 at value 1, and count 1000000 at value 1000. At any quantile iteration above 1/1000001 = 0.000000999, iteration will have necessarily proceeded to the index for value 1000, which has all the remaining counts, and therefore quantile (for the value) of 1.0. This is why IterationValue has both quantile() and quantile_iterated_to(). Additionally, to avoid a bunch of unhelpful iterations once iteration has reached the last value with non-zero count, quantile iteration will skip straight to 1.0 as well.

use hdrhistogram::Histogram;
use hdrhistogram::iterators::IterationValue;
let mut hist = Histogram::<u64>::new_with_max(10000, 4).unwrap();
for i in 0..10000 {
    hist += i;
}

let mut perc = hist.iter_quantiles(1);

println!("{:?}", hist.iter_quantiles(1).collect::<Vec<_>>());

assert_eq!(
    perc.next(),
    Some(IterationValue::new(hist.value_at_quantile(0.0001), 0.0001, 0.0, 1, 1))
);
// step size = 50
assert_eq!(
    perc.next(),
    Some(IterationValue::new(hist.value_at_quantile(0.5), 0.5, 0.5, 1, 5000 - 1))
);
// step size = 25
assert_eq!(
    perc.next(),
    Some(IterationValue::new(hist.value_at_quantile(0.75), 0.75, 0.75, 1, 2500))
);
// step size = 12.5
assert_eq!(
    perc.next(),
    Some(IterationValue::new(hist.value_at_quantile(0.875), 0.875, 0.875, 1, 1250))
);
// step size = 6.25
assert_eq!(
    perc.next(),
    Some(IterationValue::new(hist.value_at_quantile(0.9375), 0.9375, 0.9375, 1, 625))
);
// step size = 3.125
assert_eq!(
    perc.next(),
    Some(IterationValue::new(hist.value_at_quantile(0.9688), 0.9688, 0.96875, 1, 313))
);
// etc...

Important traits for HistogramIterator<'a, T, P>

impl<'a, T: 'a, P> Iterator for HistogramIterator<'a, T, P> where
    T: Counter,
    P: PickyIterator<T>,  type Item = IterationValue<T>;

pub fn iter_linear(&self, step: u64) -> HistogramIterator<T, Iter<T>>

Iterates through histogram values using linear value steps. The iteration is performed in steps of size step, each one yielding the count for all values in the preceeding value range of size step. The iterator terminates when all recorded histogram values are exhausted.

The iterator yields an iterators::IterationValue struct.

use hdrhistogram::Histogram;
use hdrhistogram::iterators::IterationValue;
let mut hist = Histogram::<u64>::new_with_max(1000, 3).unwrap();
hist += 100;
hist += 500;
hist += 800;
hist += 850;

let mut perc = hist.iter_linear(100);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(99, hist.quantile_below(99), hist.quantile_below(99), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(199, hist.quantile_below(199), hist.quantile_below(199), 0, 1))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(299, hist.quantile_below(299), hist.quantile_below(299), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(399, hist.quantile_below(399), hist.quantile_below(399), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(499, hist.quantile_below(499), hist.quantile_below(499), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(599, hist.quantile_below(599), hist.quantile_below(599), 0, 1))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(699, hist.quantile_below(699), hist.quantile_below(699), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(799, hist.quantile_below(799), hist.quantile_below(799), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(899, hist.quantile_below(899), hist.quantile_below(899), 0, 2))
);
assert_eq!(perc.next(), None);

Important traits for HistogramIterator<'a, T, P>

impl<'a, T: 'a, P> Iterator for HistogramIterator<'a, T, P> where
    T: Counter,
    P: PickyIterator<T>,  type Item = IterationValue<T>;

pub fn iter_log(&self, start: u64, exp: f64) -> HistogramIterator<T, Iter<T>>

Iterates through histogram values at logarithmically increasing levels. The iteration is performed in steps that start at start and increase exponentially according to exp. The iterator terminates when all recorded histogram values are exhausted.

The iterator yields an iterators::IterationValue struct.

use hdrhistogram::Histogram;
use hdrhistogram::iterators::IterationValue;
let mut hist = Histogram::<u64>::new_with_max(1000, 3).unwrap();
hist += 100;
hist += 500;
hist += 800;
hist += 850;

let mut perc = hist.iter_log(1, 10.0);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(0, hist.quantile_below(0), hist.quantile_below(0), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(9, hist.quantile_below(9), hist.quantile_below(9), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(99, hist.quantile_below(99), hist.quantile_below(99), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(999, hist.quantile_below(999), hist.quantile_below(999), 0, 4))
);
assert_eq!(perc.next(), None);

Important traits for HistogramIterator<'a, T, P>

impl<'a, T: 'a, P> Iterator for HistogramIterator<'a, T, P> where
    T: Counter,
    P: PickyIterator<T>,  type Item = IterationValue<T>;

pub fn iter_recorded(&self) -> HistogramIterator<T, Iter>

Iterates through all recorded histogram values using the finest granularity steps supported by the underlying representation. The iteration steps through all non-zero recorded value counts, and terminates when all recorded histogram values are exhausted.

The iterator yields an iterators::IterationValue struct.

use hdrhistogram::Histogram;
use hdrhistogram::iterators::IterationValue;
let mut hist = Histogram::<u64>::new_with_max(1000, 3).unwrap();
hist += 100;
hist += 500;
hist += 800;
hist += 850;

let mut perc = hist.iter_recorded();
assert_eq!(
    perc.next(),
    Some(IterationValue::new(100, hist.quantile_below(100), hist.quantile_below(100), 1, 1))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(500, hist.quantile_below(500), hist.quantile_below(500), 1, 1))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(800, hist.quantile_below(800), hist.quantile_below(800), 1, 1))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(850, hist.quantile_below(850), hist.quantile_below(850), 1, 1))
);
assert_eq!(perc.next(), None);

Important traits for HistogramIterator<'a, T, P>

impl<'a, T: 'a, P> Iterator for HistogramIterator<'a, T, P> where
    T: Counter,
    P: PickyIterator<T>,  type Item = IterationValue<T>;

pub fn iter_all(&self) -> HistogramIterator<T, Iter>

Iterates through all histogram values using the finest granularity steps supported by the underlying representation. The iteration steps through all possible unit value levels, regardless of whether or not there were recorded values for that value level, and terminates when all recorded histogram values are exhausted.

The iterator yields an iterators::IterationValue struct.

use hdrhistogram::Histogram;
use hdrhistogram::iterators::IterationValue;
let mut hist = Histogram::<u64>::new_with_max(10, 1).unwrap();
hist += 1;
hist += 5;
hist += 8;

let mut perc = hist.iter_all();
assert_eq!(perc.next(), Some(IterationValue::new(0, 0.0, 0.0, 0, 0)));
assert_eq!(
    perc.next(),
    Some(IterationValue::new(1, hist.quantile_below(1), hist.quantile_below(1), 1, 1))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(2, hist.quantile_below(2), hist.quantile_below(2), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(3, hist.quantile_below(3), hist.quantile_below(3), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(4, hist.quantile_below(4), hist.quantile_below(4), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(5, hist.quantile_below(5), hist.quantile_below(5), 1, 1))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(6, hist.quantile_below(6), hist.quantile_below(6), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(7, hist.quantile_below(7), hist.quantile_below(7), 0, 0))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(8, hist.quantile_below(8), hist.quantile_below(8), 1, 1))
);
assert_eq!(
    perc.next(),
    Some(IterationValue::new(9, hist.quantile_below(9), hist.quantile_below(9), 0, 0))
);
assert_eq!(perc.next(), Some(IterationValue::new(10, 1.0, 1.0, 0, 0)));

pub fn min(&self) -> u64

Get the lowest recorded value level in the histogram. If the histogram has no recorded values, the value returned will be 0.

pub fn max(&self) -> u64

Get the highest recorded value level in the histogram. If the histogram has no recorded values, the value returned is undefined.

pub fn min_nz(&self) -> u64

Get the lowest recorded non-zero value level in the histogram. If the histogram has no recorded values, the value returned is u64::max_value().

pub fn equivalent(&self, value1: u64, value2: u64) -> bool

Determine if two values are equivalent with the histogram's resolution. Equivalent here means that value samples recorded for any two equivalent values are counted in a common total count.

pub fn mean(&self) -> f64

Get the computed mean value of all recorded values in the histogram.

pub fn stdev(&self) -> f64

Get the computed standard deviation of all recorded values in the histogram

pub fn value_at_percentile(&self, percentile: f64) -> u64

Get the value at a given percentile.

This is simply value_at_quantile multiplied by 100.0. For best floating-point precision, use value_at_quantile directly.

pub fn value_at_quantile(&self, quantile: f64) -> u64

Get the value at a given quantile.

When the given quantile is > 0.0, the value returned is the value that the given percentage of the overall recorded value entries in the histogram are either smaller than or equivalent to. When the given quantile is 0.0, the value returned is the value that all value entries in the histogram are either larger than or equivalent to.

Two values are considered "equivalent" if self.equivalent would return true.

If the total count of the histogram has exceeded u64::max_value(), this will return inaccurate results.

pub fn percentile_below(&self, value: u64) -> f64

Get the percentile of samples at and below a given value.

This is simply quantile_below* multiplied by 100.0. For best floating-point precision, use quantile_below` directly.

pub fn quantile_below(&self, value: u64) -> f64

Get the quantile of samples at or below a given value.

The value returned is the quantile of values recorded in the histogram that are smaller than or equivalent to the given value.

Two values are considered "equivalent" if self.equivalent would return true.

If the value is larger than the maximum representable value, it will be clamped to the max representable value.

If the total count of the histogram has reached u64::max_value(), this will return inaccurate results.

pub fn count_between(&self, low: u64, high: u64) -> u64

Get the count of recorded values within a range of value levels (inclusive to within the histogram's resolution).

low gives the lower value bound on the range for which to provide the recorded count. Will be rounded down with lowest_equivalent. Similarly, high gives the higher value bound on the range, and will be rounded up with highest_equivalent. The function returns the total count of values recorded in the histogram within the value range that is >= lowest_equivalent(low) and <= highest_equivalent(high).

If either value is larger than the maximum representable value, it will be clamped to the max representable value.

The count will saturate at u64::max_value().

pub fn count_at(&self, value: u64) -> T

Get the count of recorded values at a specific value (to within the histogram resolution at the value level).

The count is computed across values recorded in the histogram that are within the value range that is >= lowest_equivalent(value) and <= highest_equivalent(value).

If the value is larger than the maximum representable value, it will be clamped to the max representable value.

pub fn lowest_equivalent(&self, value: u64) -> u64

Get the lowest value that is equivalent to the given value within the histogram's resolution. Equivalent here means that value samples recorded for any two equivalent values are counted in a common total count.

pub fn highest_equivalent(&self, value: u64) -> u64

Get the highest value that is equivalent to the given value within the histogram's resolution. Equivalent here means that value samples recorded for any two equivalent values are counted in a common total count.

Note that the return value is capped at u64::max_value().

pub fn median_equivalent(&self, value: u64) -> u64

Get a value that lies in the middle (rounded up) of the range of values equivalent the given value. Equivalent here means that value samples recorded for any two equivalent values are counted in a common total count.

Note that the return value is capped at u64::max_value().

pub fn next_non_equivalent(&self, value: u64) -> u64

Get the next value that is not equivalent to the given value within the histogram's resolution. Equivalent means that value samples recorded for any two equivalent values are counted in a common total count.

Note that the return value is capped at u64::max_value().

pub fn equivalent_range(&self, value: u64) -> u64

Get the size (in value units) of the range of values that are equivalent to the given value within the histogram's resolution. Equivalent here means that value samples recorded for any two equivalent values are counted in a common total count.

Trait Implementations

impl<C: Debug + Counter> Debug for SyncHistogram<C>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<C: Counter> Deref for SyncHistogram<C>

type Target = Histogram<C>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<C: Counter> DerefMut for SyncHistogram<C>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<C: Counter> From<Histogram<C>> for SyncHistogram<C>

fn from(h: Histogram<C>) -> Self

Performs the conversion.