metrics/
handles.rs

1use std::sync::Arc;
2
3use crate::IntoF64;
4
5/// A counter handler.
6pub trait CounterFn {
7    /// Increments the counter by the given amount.
8    fn increment(&self, value: u64);
9
10    /// Sets the counter to at least the given amount.
11    ///
12    /// This is intended to support use cases where multiple callers are attempting to synchronize
13    /// this counter with an external counter that they have no control over.  As multiple callers
14    /// may read that external counter, and attempt to set it here, there could be reordering issues
15    /// where a caller attempts to set an older (smaller) value after the counter has been updated to
16    /// the latest (larger) value.
17    ///
18    /// This method must cope with those cases.  An example of doing so atomically can be found in
19    /// `AtomicCounter`.
20    fn absolute(&self, value: u64);
21}
22
23/// A gauge handler.
24pub trait GaugeFn {
25    /// Increments the gauge by the given amount.
26    fn increment(&self, value: f64);
27
28    /// Decrements the gauge by the given amount.
29    fn decrement(&self, value: f64);
30
31    /// Sets the gauge to the given amount.
32    fn set(&self, value: f64);
33}
34
35/// A histogram handler.
36pub trait HistogramFn {
37    /// Records a value into the histogram.
38    fn record(&self, value: f64);
39}
40
41/// A counter.
42#[derive(Clone)]
43#[must_use = "counters do nothing unless you use them"]
44pub struct Counter {
45    inner: Option<Arc<dyn CounterFn + Send + Sync>>,
46}
47
48/// A gauge.
49#[derive(Clone)]
50#[must_use = "gauges do nothing unless you use them"]
51pub struct Gauge {
52    inner: Option<Arc<dyn GaugeFn + Send + Sync>>,
53}
54
55/// A histogram.
56#[derive(Clone)]
57#[must_use = "histograms do nothing unless you use them"]
58pub struct Histogram {
59    inner: Option<Arc<dyn HistogramFn + Send + Sync>>,
60}
61
62impl Counter {
63    /// Creates a no-op `Counter` which does nothing.
64    ///
65    /// Suitable when a handle must be provided that does nothing i.e. a no-op recorder or a layer
66    /// that disables specific metrics, and so on.
67    pub fn noop() -> Self {
68        Self { inner: None }
69    }
70
71    /// Creates a `Counter` based on a shared handler.
72    pub fn from_arc<F: CounterFn + Send + Sync + 'static>(a: Arc<F>) -> Self {
73        Self { inner: Some(a) }
74    }
75
76    /// Increments the counter.
77    pub fn increment(&self, value: u64) {
78        if let Some(c) = &self.inner {
79            c.increment(value)
80        }
81    }
82
83    /// Sets the counter to an absolute value.
84    pub fn absolute(&self, value: u64) {
85        if let Some(c) = &self.inner {
86            c.absolute(value)
87        }
88    }
89}
90
91impl Gauge {
92    /// Creates a no-op `Gauge` which does nothing.
93    ///
94    /// Suitable when a handle must be provided that does nothing i.e. a no-op recorder or a layer
95    /// that disables specific metrics, and so on.
96    pub fn noop() -> Self {
97        Self { inner: None }
98    }
99
100    /// Creates a `Gauge` based on a shared handler.
101    pub fn from_arc<F: GaugeFn + Send + Sync + 'static>(a: Arc<F>) -> Self {
102        Self { inner: Some(a) }
103    }
104
105    /// Increments the gauge.
106    pub fn increment<T: IntoF64>(&self, value: T) {
107        if let Some(g) = &self.inner {
108            g.increment(value.into_f64())
109        }
110    }
111
112    /// Decrements the gauge.
113    pub fn decrement<T: IntoF64>(&self, value: T) {
114        if let Some(g) = &self.inner {
115            g.decrement(value.into_f64())
116        }
117    }
118
119    /// Sets the gauge.
120    pub fn set<T: IntoF64>(&self, value: T) {
121        if let Some(g) = &self.inner {
122            g.set(value.into_f64())
123        }
124    }
125}
126
127impl Histogram {
128    /// Creates a no-op `Histogram` which does nothing.
129    ///
130    /// Suitable when a handle must be provided that does nothing i.e. a no-op recorder or a layer
131    /// that disables specific metrics, and so on.
132    pub fn noop() -> Self {
133        Self { inner: None }
134    }
135
136    /// Creates a `Histogram` based on a shared handler.
137    pub fn from_arc<F: HistogramFn + Send + Sync + 'static>(a: Arc<F>) -> Self {
138        Self { inner: Some(a) }
139    }
140
141    /// Records a value in the histogram.
142    pub fn record<T: IntoF64>(&self, value: T) {
143        if let Some(ref inner) = self.inner {
144            inner.record(value.into_f64())
145        }
146    }
147}
148
149impl<T> CounterFn for Arc<T>
150where
151    T: CounterFn,
152{
153    fn increment(&self, value: u64) {
154        (**self).increment(value)
155    }
156
157    fn absolute(&self, value: u64) {
158        (**self).absolute(value)
159    }
160}
161impl<T> GaugeFn for Arc<T>
162where
163    T: GaugeFn,
164{
165    fn increment(&self, value: f64) {
166        (**self).increment(value)
167    }
168
169    fn decrement(&self, value: f64) {
170        (**self).decrement(value)
171    }
172
173    fn set(&self, value: f64) {
174        (**self).set(value)
175    }
176}
177
178impl<T> HistogramFn for Arc<T>
179where
180    T: HistogramFn,
181{
182    fn record(&self, value: f64) {
183        (**self).record(value);
184    }
185}
186
187impl<T> From<Arc<T>> for Counter
188where
189    T: CounterFn + Send + Sync + 'static,
190{
191    fn from(inner: Arc<T>) -> Self {
192        Counter::from_arc(inner)
193    }
194}
195
196impl<T> From<Arc<T>> for Gauge
197where
198    T: GaugeFn + Send + Sync + 'static,
199{
200    fn from(inner: Arc<T>) -> Self {
201        Gauge::from_arc(inner)
202    }
203}
204
205impl<T> From<Arc<T>> for Histogram
206where
207    T: HistogramFn + Send + Sync + 'static,
208{
209    fn from(inner: Arc<T>) -> Self {
210        Histogram::from_arc(inner)
211    }
212}
metrics/handles.rs

metrics/
handles.rs
