@@ -20,31 +20,28 @@ thread_local! {
20
20
21
21
/// A trait for registering and recording metrics.
22
22
///
23
- /// This is the core trait that allows interoperability between exporter implementations and the
24
- /// macros provided by `metrics`.
23
+ /// This is the core trait that allows interoperability between exporter implementations and the macros provided by
24
+ /// `metrics`.
25
25
pub trait Recorder {
26
26
/// Describes a counter.
27
27
///
28
- /// Callers may provide the unit or a description of the counter being registered. Whether or
29
- /// not a metric can be re-registered to provide a unit/description, if one was already passed
30
- /// or not, as well as how units/descriptions are used by the underlying recorder, is an
31
- /// implementation detail.
28
+ /// Callers may provide the unit or a description of the counter being registered. Whether or not a metric can be
29
+ /// re-registered to provide a unit/description, if one was already passed or not, as well as how units/descriptions
30
+ /// are used by the underlying recorder, is an implementation detail.
32
31
fn describe_counter ( & self , key : KeyName , unit : Option < Unit > , description : SharedString ) ;
33
32
34
33
/// Describes a gauge.
35
34
///
36
- /// Callers may provide the unit or a description of the gauge being registered. Whether or
37
- /// not a metric can be re-registered to provide a unit/description, if one was already passed
38
- /// or not, as well as how units/descriptions are used by the underlying recorder, is an
39
- /// implementation detail.
35
+ /// Callers may provide the unit or a description of the gauge being registered. Whether or not a metric can be
36
+ /// re-registered to provide a unit/description, if one was already passed or not, as well as how units/descriptions
37
+ /// are used by the underlying recorder, is an implementation detail.
40
38
fn describe_gauge ( & self , key : KeyName , unit : Option < Unit > , description : SharedString ) ;
41
39
42
40
/// Describes a histogram.
43
41
///
44
- /// Callers may provide the unit or a description of the histogram being registered. Whether or
45
- /// not a metric can be re-registered to provide a unit/description, if one was already passed
46
- /// or not, as well as how units/descriptions are used by the underlying recorder, is an
47
- /// implementation detail.
42
+ /// Callers may provide the unit or a description of the histogram being registered. Whether or not a metric can be
43
+ /// re-registered to provide a unit/description, if one was already passed or not, as well as how units/descriptions
44
+ /// are used by the underlying recorder, is an implementation detail.
48
45
fn describe_histogram ( & self , key : KeyName , unit : Option < Unit > , description : SharedString ) ;
49
46
50
47
/// Registers a counter.
@@ -125,19 +122,16 @@ impl_recorder!(T, std::sync::Arc<T>);
125
122
126
123
/// Guard for setting a local recorder.
127
124
///
128
- /// When using a local recorder, we take a reference to the recorder and only hold it for as long as
129
- /// the duration of the closure. However, we must store this reference in a static variable
130
- /// (thread-local storage) so that it can be accessed by the macros. This guard ensures that the
131
- /// pointer we store to the reference is cleared when the guard is dropped, so that it can't be used
132
- /// after the closure has finished, even if the closure panics and unwinds the stack.
125
+ /// When using a local recorder, we take a reference to the recorder and only hold it for as long as the duration of the
126
+ /// closure. However, we must store this reference in a static variable (thread-local storage) so that it can be
127
+ /// accessed by the macros. This guard ensures that the pointer we store to the reference is cleared when the guard is
128
+ /// dropped, so that it can't be used after the closure has finished, even if the closure panics and unwinds the stack.
133
129
///
134
130
/// ## Note
135
131
///
136
- /// The guard has a lifetime parameter `'a` that is bounded using a
137
- /// `PhantomData` type. This upholds the guard's contravariance, it must live
138
- /// _at most as long_ as the recorder it takes a reference to. The bounded
139
- /// lifetime prevents accidental use-after-free errors when using a guard
140
- /// directly through [`crate::set_default_local_recorder`].
132
+ /// The guard has a lifetime parameter `'a` that is bounded using a `PhantomData` type. This upholds the guard's
133
+ /// contravariance, it must live _at most as long_ as the recorder it takes a reference to. The bounded lifetime
134
+ /// prevents accidental use-after-free errors when using a guard directly through [`crate::set_default_local_recorder`].
141
135
pub struct LocalRecorderGuard < ' a > {
142
136
prev_recorder : Option < NonNull < dyn Recorder > > ,
143
137
phantom : PhantomData < & ' a dyn Recorder > ,
@@ -146,10 +140,9 @@ pub struct LocalRecorderGuard<'a> {
146
140
impl < ' a > LocalRecorderGuard < ' a > {
147
141
/// Creates a new `LocalRecorderGuard` and sets the thread-local recorder.
148
142
fn new ( recorder : & ' a dyn Recorder ) -> Self {
149
- // SAFETY: While we take a lifetime-less pointer to the given reference, the reference we
150
- // derive _from_ the pointer is given the same lifetime of the reference
151
- // used to construct the guard -- captured in the guard type itself --
152
- // and so derived references never outlive the source reference.
143
+ // SAFETY: While we take a lifetime-less pointer to the given reference, the reference we derive _from_ the
144
+ // pointer is given the same lifetime of the reference used to construct the guard -- captured in the guard type
145
+ // itself -- and so derived references never outlive the source reference.
153
146
let recorder_ptr = unsafe { NonNull :: new_unchecked ( recorder as * const _ as * mut _ ) } ;
154
147
155
148
let prev_recorder =
@@ -168,11 +161,11 @@ impl<'a> Drop for LocalRecorderGuard<'a> {
168
161
169
162
/// Sets the global recorder.
170
163
///
171
- /// This function may only be called once in the lifetime of a program. Any metrics recorded
172
- /// before this method is called will be completely ignored.
164
+ /// This function may only be called once in the lifetime of a program. Any metrics recorded before this method is
165
+ /// called will be completely ignored.
173
166
///
174
- /// This function does not typically need to be called manually. Metrics implementations should
175
- /// provide an initialization method that installs the recorder internally.
167
+ /// This function does not typically need to be called manually. Metrics implementations should provide an
168
+ /// initialization method that installs the recorder internally.
176
169
///
177
170
/// # Errors
178
171
///
@@ -184,25 +177,21 @@ where
184
177
GLOBAL_RECORDER . set ( recorder)
185
178
}
186
179
187
- /// Sets the recorder as the default for the current thread for the duration of
188
- /// the lifetime of the returned [`LocalRecorderGuard`].
180
+ /// Sets the recorder as the default for the current thread for the duration of the lifetime of the returned
181
+ /// [`LocalRecorderGuard`].
189
182
///
190
- /// This function is suitable for capturing metrics in asynchronous code, in particular
191
- /// when using a single-threaded runtime. Any metrics registered prior to the returned
192
- /// guard will remain attached to the recorder that was present at the time of registration,
193
- /// and so this cannot be used to intercept existing metrics.
183
+ /// This function is suitable for capturing metrics in asynchronous code, in particular when using a single-threaded
184
+ /// runtime. Any metrics registered prior to the returned guard will remain attached to the recorder that was present at
185
+ /// the time of registration, and so this cannot be used to intercept existing metrics.
194
186
///
195
- /// Additionally, local recorders can be used in a nested fashion. When setting a new
196
- /// default local recorder, the previous default local recorder will be captured if one
197
- /// was set, and will be restored when the returned guard drops.
187
+ /// Additionally, local recorders can be used in a nested fashion. When setting a new default local recorder, the
188
+ /// previous default local recorder will be captured if one was set, and will be restored when the returned guard drops.
198
189
/// the lifetime of the returned [`LocalRecorderGuard`].
199
190
///
200
- /// Any metrics recorded before a guard is returned will be completely ignored.
201
- /// Metrics implementations should provide an initialization method that
202
- /// installs the recorder internally.
191
+ /// Any metrics recorded before a guard is returned will be completely ignored. Metrics implementations should provide
192
+ /// an initialization method that installs the recorder internally.
203
193
///
204
- /// The function is suitable for capturing metrics in asynchronous code that
205
- /// uses a single threaded runtime.
194
+ /// The function is suitable for capturing metrics in asynchronous code that uses a single threaded runtime.
206
195
///
207
196
/// If a global recorder is set, it will be restored once the guard is dropped.
208
197
#[ must_use]
@@ -222,19 +211,18 @@ pub fn with_local_recorder<T>(recorder: &dyn Recorder, f: impl FnOnce() -> T) ->
222
211
223
212
/// Runs the closure with a reference to the current recorder for this scope.
224
213
///
225
- /// If a local recorder has been set, it will be used. Otherwise, the global recorder will be used.
226
- /// If neither a local recorder or global recorder have been set, a no-op recorder will be used.
214
+ /// If a local recorder has been set, it will be used. Otherwise, the global recorder will be used. If neither a local
215
+ /// recorder or global recorder have been set, a no-op recorder will be used.
227
216
///
228
217
/// It should typically not be necessary to call this function directly, as it is used primarily by generated code. You
229
218
/// should prefer working with the macros provided by `metrics` instead: `counter!`, `gauge!`, `histogram!`, etc.
230
219
pub fn with_recorder < T > ( f : impl FnOnce ( & dyn Recorder ) -> T ) -> T {
231
220
LOCAL_RECORDER . with ( |local_recorder| {
232
221
if let Some ( recorder) = local_recorder. get ( ) {
233
- // SAFETY: If we have a local recorder, we know that it is valid because it can only be
234
- // set during the duration of a closure that is passed to `with_local_recorder`, which
235
- // is the only time this method can be called and have a local recorder set. This
236
- // ensures that the lifetime of the recorder is valid for the duration of this method
237
- // call.
222
+ // SAFETY: If we have a local recorder, we know that it is valid because it can only be set during the
223
+ // duration of a closure that is passed to `with_local_recorder`, which is the only time this method can be
224
+ // called and have a local recorder set. This ensures that the lifetime of the recorder is valid for the
225
+ // duration of this method call.
238
226
unsafe { f ( recorder. as_ref ( ) ) }
239
227
} else if let Some ( global_recorder) = GLOBAL_RECORDER . try_load ( ) {
240
228
f ( global_recorder)
0 commit comments