1// taken from https://github.com/hyperium/http/blob/master/src/extensions.rs.
2
3use crate::sync::{RwLockReadGuard, RwLockWriteGuard};
4use std::{
5 any::{Any, TypeId},
6 collections::HashMap,
7 fmt,
8 hash::{BuildHasherDefault, Hasher},
9};
10
11#[allow(warnings)]
12type AnyMap = HashMap<TypeId, Box<dyn Any + Send + Sync>, BuildHasherDefault<IdHasher>>;
13
14/// With TypeIds as keys, there's no need to hash them. They are already hashes
15/// themselves, coming from the compiler. The IdHasher holds the u64 of
16/// the TypeId, and then returns it, instead of doing any bit fiddling.
17#[derive(Default, Debug)]
18struct IdHasher(u64);
19
20impl Hasher for IdHasher {
21 fn write(&mut self, _: &[u8]) {
22 unreachable!("TypeId calls write_u64");
23 }
24
25 #[inline]
26 fn write_u64(&mut self, id: u64) {
27 self.0 = id;
28 }
29
30 #[inline]
31 fn finish(&self) -> u64 {
32 self.0
33 }
34}
35
36/// An immutable, read-only reference to a Span's extensions.
37#[derive(Debug)]
38#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
39pub struct Extensions<'a> {
40 inner: RwLockReadGuard<'a, ExtensionsInner>,
41}
42
43impl<'a> Extensions<'a> {
44 #[cfg(feature = "registry")]
45 pub(crate) fn new(inner: RwLockReadGuard<'a, ExtensionsInner>) -> Self {
46 Self { inner }
47 }
48
49 /// Immutably borrows a type previously inserted into this `Extensions`.
50 pub fn get<T: 'static>(&self) -> Option<&T> {
51 self.inner.get::<T>()
52 }
53}
54
55/// An mutable reference to a Span's extensions.
56#[derive(Debug)]
57#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
58pub struct ExtensionsMut<'a> {
59 inner: RwLockWriteGuard<'a, ExtensionsInner>,
60}
61
62impl<'a> ExtensionsMut<'a> {
63 #[cfg(feature = "registry")]
64 pub(crate) fn new(inner: RwLockWriteGuard<'a, ExtensionsInner>) -> Self {
65 Self { inner }
66 }
67
68 /// Insert a type into this `Extensions`.
69 ///
70 /// Note that extensions are _not_
71 /// `Layer`-specific—they are _span_-specific. This means that
72 /// other layers can access and mutate extensions that
73 /// a different Layer recorded. For example, an application might
74 /// have a layer that records execution timings, alongside a layer
75 /// that reports spans and events to a distributed
76 /// tracing system that requires timestamps for spans.
77 /// Ideally, if one layer records a timestamp _x_, the other layer
78 /// should be able to reuse timestamp _x_.
79 ///
80 /// Therefore, extensions should generally be newtypes, rather than common
81 /// types like [`String`](std::string::String), to avoid accidental
82 /// cross-`Layer` clobbering.
83 ///
84 /// ## Panics
85 ///
86 /// If `T` is already present in `Extensions`, then this method will panic.
87 pub fn insert<T: Send + Sync + 'static>(&mut self, val: T) {
88 assert!(self.replace(val).is_none())
89 }
90
91 /// Replaces an existing `T` into this extensions.
92 ///
93 /// If `T` is not present, `Option::None` will be returned.
94 pub fn replace<T: Send + Sync + 'static>(&mut self, val: T) -> Option<T> {
95 self.inner.insert(val)
96 }
97
98 /// Get a mutable reference to a type previously inserted on this `ExtensionsMut`.
99 pub fn get_mut<T: 'static>(&mut self) -> Option<&mut T> {
100 self.inner.get_mut::<T>()
101 }
102
103 /// Remove a type from this `Extensions`.
104 ///
105 /// If a extension of this type existed, it will be returned.
106 pub fn remove<T: Send + Sync + 'static>(&mut self) -> Option<T> {
107 self.inner.remove::<T>()
108 }
109}
110
111/// A type map of span extensions.
112///
113/// [ExtensionsInner] is used by `SpanData` to store and
114/// span-specific data. A given `Layer` can read and write
115/// data that it is interested in recording and emitting.
116#[derive(Default)]
117pub(crate) struct ExtensionsInner {
118 map: AnyMap,
119}
120
121impl ExtensionsInner {
122 /// Create an empty `Extensions`.
123 #[cfg(any(test, feature = "registry"))]
124 #[inline]
125 #[cfg(any(test, feature = "registry"))]
126 pub(crate) fn new() -> ExtensionsInner {
127 ExtensionsInner {
128 map: AnyMap::default(),
129 }
130 }
131
132 /// Insert a type into this `Extensions`.
133 ///
134 /// If a extension of this type already existed, it will
135 /// be returned.
136 pub(crate) fn insert<T: Send + Sync + 'static>(&mut self, val: T) -> Option<T> {
137 self.map
138 .insert(TypeId::of::<T>(), Box::new(val))
139 .and_then(|boxed| {
140 #[allow(warnings)]
141 {
142 (boxed as Box<Any + 'static>)
143 .downcast()
144 .ok()
145 .map(|boxed| *boxed)
146 }
147 })
148 }
149
150 /// Get a reference to a type previously inserted on this `Extensions`.
151 pub(crate) fn get<T: 'static>(&self) -> Option<&T> {
152 self.map
153 .get(&TypeId::of::<T>())
154 .and_then(|boxed| (&**boxed as &(dyn Any + 'static)).downcast_ref())
155 }
156
157 /// Get a mutable reference to a type previously inserted on this `Extensions`.
158 pub(crate) fn get_mut<T: 'static>(&mut self) -> Option<&mut T> {
159 self.map
160 .get_mut(&TypeId::of::<T>())
161 .and_then(|boxed| (&mut **boxed as &mut (dyn Any + 'static)).downcast_mut())
162 }
163
164 /// Remove a type from this `Extensions`.
165 ///
166 /// If a extension of this type existed, it will be returned.
167 pub(crate) fn remove<T: Send + Sync + 'static>(&mut self) -> Option<T> {
168 self.map.remove(&TypeId::of::<T>()).and_then(|boxed| {
169 #[allow(warnings)]
170 {
171 (boxed as Box<Any + 'static>)
172 .downcast()
173 .ok()
174 .map(|boxed| *boxed)
175 }
176 })
177 }
178
179 /// Clear the `ExtensionsInner` in-place, dropping any elements in the map but
180 /// retaining allocated capacity.
181 ///
182 /// This permits the hash map allocation to be pooled by the registry so
183 /// that future spans will not need to allocate new hashmaps.
184 #[cfg(any(test, feature = "registry"))]
185 pub(crate) fn clear(&mut self) {
186 self.map.clear();
187 }
188}
189
190impl fmt::Debug for ExtensionsInner {
191 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
192 f.debug_struct("Extensions")
193 .field("len", &self.map.len())
194 .field("capacity", &self.map.capacity())
195 .finish()
196 }
197}
198
199#[cfg(test)]
200mod tests {
201 use super::*;
202
203 #[derive(Debug, PartialEq)]
204 struct MyType(i32);
205
206 #[test]
207 fn test_extensions() {
208 let mut extensions = ExtensionsInner::new();
209
210 extensions.insert(5i32);
211 extensions.insert(MyType(10));
212
213 assert_eq!(extensions.get(), Some(&5i32));
214 assert_eq!(extensions.get_mut(), Some(&mut 5i32));
215
216 assert_eq!(extensions.remove::<i32>(), Some(5i32));
217 assert!(extensions.get::<i32>().is_none());
218
219 assert_eq!(extensions.get::<bool>(), None);
220 assert_eq!(extensions.get(), Some(&MyType(10)));
221 }
222
223 #[test]
224 fn clear_retains_capacity() {
225 let mut extensions = ExtensionsInner::new();
226 extensions.insert(5i32);
227 extensions.insert(MyType(10));
228 extensions.insert(true);
229
230 assert_eq!(extensions.map.len(), 3);
231 let prev_capacity = extensions.map.capacity();
232 extensions.clear();
233
234 assert_eq!(
235 extensions.map.len(),
236 0,
237 "after clear(), extensions map should have length 0"
238 );
239 assert_eq!(
240 extensions.map.capacity(),
241 prev_capacity,
242 "after clear(), extensions map should retain prior capacity"
243 );
244 }
245
246 #[test]
247 fn clear_drops_elements() {
248 use std::sync::Arc;
249 struct DropMePlease(Arc<()>);
250 struct DropMeTooPlease(Arc<()>);
251
252 let mut extensions = ExtensionsInner::new();
253 let val1 = DropMePlease(Arc::new(()));
254 let val2 = DropMeTooPlease(Arc::new(()));
255
256 let val1_dropped = Arc::downgrade(&val1.0);
257 let val2_dropped = Arc::downgrade(&val2.0);
258 extensions.insert(val1);
259 extensions.insert(val2);
260
261 assert!(val1_dropped.upgrade().is_some());
262 assert!(val2_dropped.upgrade().is_some());
263
264 extensions.clear();
265 assert!(
266 val1_dropped.upgrade().is_none(),
267 "after clear(), val1 should be dropped"
268 );
269 assert!(
270 val2_dropped.upgrade().is_none(),
271 "after clear(), val2 should be dropped"
272 );
273 }
274}
275