# [−][src]Struct hdrhistogram::sync::SyncHistogram

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>`

[src]

`pub fn refresh(&mut self)`

[src]

Block until writes from all `Recorder`

instances for this histogram have been
incorporated.

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

[src]

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>`

[src]

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`

[src]

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

`pub fn low(&self) -> u64`

[src]

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

`pub fn high(&self) -> u64`

[src]

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

`pub fn sigfig(&self) -> u8`

[src]

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

`pub fn count(&self) -> u64`

[src]

use `len`

instead

Get the total number of samples recorded.

`pub fn len(&self) -> u64`

[src]

Get the total number of samples recorded.

`pub fn is_empty(&self) -> bool`

[src]

Returns true if this histogram has no recorded values.

`pub fn buckets(&self) -> u8`

[src]

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>`

[src]

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>

[src]

&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>

[src]

&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>

[src]

&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>

[src]

&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>

[src]

&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)`

[src]

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

`pub fn reset(&mut self)`

[src]

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

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

[src]

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>`

[src]

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)`

[src]

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>`

[src]

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)`

[src]

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>

[src]

&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>

[src]

&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>`pub fn iter_quantiles(`

&self,

ticks_per_half_distance: u32

) -> HistogramIterator<T, Iter<T>>

[src]

&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>`pub fn iter_linear(&self, step: u64) -> HistogramIterator<T, Iter<T>>`

[src]

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>`pub fn iter_log(&self, start: u64, exp: f64) -> HistogramIterator<T, Iter<T>>`

[src]

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>`pub fn iter_recorded(&self) -> HistogramIterator<T, Iter>`

[src]

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>`pub fn iter_all(&self) -> HistogramIterator<T, Iter>`

[src]

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`

[src]

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`

[src]

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`

[src]

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`

[src]

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`

[src]

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

`pub fn stdev(&self) -> f64`

[src]

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

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

[src]

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`

[src]

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`

[src]

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`

[src]

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`

[src]

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`

[src]

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`

[src]

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`

[src]

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`

[src]

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`

[src]

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`

[src]

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: Counter> From<Histogram<C>> for SyncHistogram<C>`

[src]

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

[src]

`type Target = Histogram<C>`

The resulting type after dereferencing.

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

[src]

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

[src]

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

[src]

## Auto Trait Implementations

`impl<C> Send for SyncHistogram<C> where`

C: Send,

C: Send,

`impl<C> Unpin for SyncHistogram<C> where`

C: Unpin,

C: Unpin,

`impl<C> Sync for SyncHistogram<C> where`

C: Send + Sync,

C: Send + Sync,

`impl<C> UnwindSafe for SyncHistogram<C> where`

C: UnwindSafe,

C: UnwindSafe,

`impl<C> RefUnwindSafe for SyncHistogram<C> where`

C: RefUnwindSafe,

C: RefUnwindSafe,

## Blanket Implementations

`impl<T> From<T> for T`

[src]

`impl<T, U> Into<U> for T where`

U: From<T>,

[src]

U: From<T>,

`impl<T, U> TryFrom<U> for T where`

U: Into<T>,

[src]

U: Into<T>,

`type Error = Infallible`

The type returned in the event of a conversion error.

`fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`

[src]

`impl<T, U> TryInto<U> for T where`

U: TryFrom<T>,

[src]

U: TryFrom<T>,

`type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

`fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`

[src]

`impl<T> BorrowMut<T> for T where`

T: ?Sized,

[src]

T: ?Sized,

`fn borrow_mut(&mut self) -> &mut T`

[src]

`impl<T> Borrow<T> for T where`

T: ?Sized,

[src]

T: ?Sized,

`impl<T> Any for T where`

T: 'static + ?Sized,

[src]

T: 'static + ?Sized,