hdrhistogram/errors/
mod.rs

1//! Error types used throughout this library
2use std::error::Error;
3use std::fmt;
4
5/// Errors that can occur when creating a histogram.
6#[derive(Debug, Eq, PartialEq, Clone, Copy)]
7pub enum CreationError {
8    /// Lowest discernible value must be >= 1.
9    LowIsZero,
10    /// Lowest discernible value must be <= `u64::max_value() / 2` because the highest value is
11    /// a `u64` and the lowest value must be no bigger than half the highest.
12    LowExceedsMax,
13    /// Highest trackable value must be >= 2 * lowest discernible value for some internal
14    /// calculations to work out. In practice, high is typically much higher than 2 * low.
15    HighLessThanTwiceLow,
16    /// Number of significant digits must be in the range `[0, 5]`. It is capped at 5 because 5
17    /// significant digits is already more than almost anyone needs, and memory usage scales
18    /// exponentially as this increases.
19    SigFigExceedsMax,
20    /// Cannot represent sigfig worth of values beyond the lowest discernible value. Decrease the
21    /// significant figures, lowest discernible value, or both.
22    ///
23    /// This could happen if low is very large (like 2^60) and sigfigs is 5, which requires 18
24    /// additional bits, which would then require more bits than will fit in a u64. Specifically,
25    /// the exponent of the largest power of two that is smaller than the lowest value and the bits
26    /// needed to represent the requested significant figures must sum to 63 or less.
27    CannotRepresentSigFigBeyondLow,
28    /// The `usize` type is too small to represent the desired configuration. Use fewer significant
29    /// figures or a lower max.
30    UsizeTypeTooSmall,
31}
32
33// TODO like RecordError, this is also an awkward split along resizing.
34/// Errors that can occur when adding another histogram.
35#[derive(Debug, Eq, PartialEq, Clone, Copy)]
36pub enum AdditionError {
37    /// The other histogram includes values that do not fit in this histogram's range.
38    /// Only possible when auto resize is disabled.
39    OtherAddendValueExceedsRange,
40    /// The other histogram includes values that would map to indexes in this histogram that are
41    /// not expressible for `usize`. Configure this histogram to use fewer significant digits. Only
42    /// possible when resize is enabled.
43    ResizeFailedUsizeTypeTooSmall,
44}
45
46/// Errors that can occur when subtracting another histogram.
47#[derive(Debug, Eq, PartialEq, Clone, Copy)]
48pub enum SubtractionError {
49    /// The other histogram includes values that do not fit in this histogram's range.
50    /// Only possible when auto resize is disabled.
51    SubtrahendValueExceedsMinuendRange,
52    /// The other histogram includes counts that are higher than the current count for a value, and
53    /// counts cannot go negative. The subtraction may have been partially applied to some counts as
54    /// this error is returned when the first impossible subtraction is detected.
55    SubtrahendCountExceedsMinuendCount,
56}
57
58// TODO the error conditions here are awkward: one only possible when resize is disabled, the other
59// only when resize is enabled.
60/// Errors that can occur while recording a value and its associated count.
61#[derive(Debug, Eq, PartialEq, Clone, Copy)]
62pub enum RecordError {
63    /// The value to record is not representable in this histogram and resizing is disabled.
64    /// Configure a higher maximum value or enable resizing. Only possible when resizing is
65    /// disabled.
66    ValueOutOfRangeResizeDisabled,
67    /// Auto resizing is enabled and must be used to represent the provided value, but the histogram
68    /// cannot be resized because `usize` cannot represent sufficient length. Configure this
69    /// histogram to use fewer significant digits. Only possible when resizing is enabled.
70    ResizeFailedUsizeTypeTooSmall,
71}
72
73#[allow(missing_docs)]
74#[derive(Debug)]
75pub struct UsizeTypeTooSmall;
76
77impl fmt::Display for CreationError {
78    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
79        match self {
80            CreationError::LowIsZero => write!(f, "Lowest discernible value must be >= 1"),
81            CreationError::LowExceedsMax => write!(f, "Lowest discernible value must be <= `u64::max_value() / 2`"),
82            CreationError::HighLessThanTwiceLow => write!(f, "Highest trackable value must be >= 2 * lowest discernible value for some internal calculations"),
83            CreationError::SigFigExceedsMax => write!(f, "Number of significant digits must be in the range `[0, 5]`"),
84            CreationError::CannotRepresentSigFigBeyondLow => write!(f, "Cannot represent sigfig worth of values beyond the lowest discernible value"),
85            CreationError::UsizeTypeTooSmall =>  write!(f, "The `usize` type is too small to represent the desired configuration"),
86        }
87    }
88}
89
90impl Error for CreationError {}
91
92impl fmt::Display for AdditionError {
93    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
94        match self {
95            AdditionError::OtherAddendValueExceedsRange => write!(f, "The other histogram includes values that do not fit in this histogram's range"),
96            AdditionError::ResizeFailedUsizeTypeTooSmall => write!(f, "The other histogram includes values that would map to indexes in this histogram that are not expressible for `usize`"),
97        }
98    }
99}
100
101impl Error for AdditionError {}
102
103impl fmt::Display for SubtractionError {
104    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
105        match self {
106            SubtractionError::SubtrahendValueExceedsMinuendRange => write!(f, "The other histogram includes values that do not fit in this histogram's range"),
107            SubtractionError::SubtrahendCountExceedsMinuendCount => write!(f, "The other histogram includes counts that are higher than the current count for a value, and counts cannot go negative"),
108        }
109    }
110}
111
112impl Error for SubtractionError {}
113
114impl fmt::Display for RecordError {
115    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
116        match self {
117            RecordError::ValueOutOfRangeResizeDisabled  => write!(f, "The value to record is not representable in this histogram and resizing is disabled"),
118            RecordError::ResizeFailedUsizeTypeTooSmall => write!(f, "Auto resizing is enabled and must be used to represent the provided value, but the histogram cannot be resized because `usize` cannot represent sufficient length"),
119        }
120    }
121}
122
123impl Error for RecordError {}
124
125impl fmt::Display for UsizeTypeTooSmall {
126    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
127        write!(
128            f,
129            "The `usize` type is too small to represent the desired configuration"
130        )
131    }
132}
133
134impl Error for UsizeTypeTooSmall {}
hdrhistogram/errors/mod.rs

hdrhistogram/errors/
mod.rs
