captrack 0.1.0

Capacity telemetry for Rust collections — call-site macros that record peak capacity, with zero overhead when disabled.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

use std::hash::{BuildHasher, Hash};

use crate::registry;
use crate::IntoInner;

/// A `scc::HashMap<K, V, S>` wrapper that records creation count and capacity
/// samples.
///
/// `S` defaults to `crate::CapHasher`.
///
/// # Samples record `len()`, NOT peak occupancy
///
/// `scc::HashMap` does not expose a `capacity()` method.  On every `Drop` (or
/// `From` conversion), `inner.len()` is pushed as the sample — this is the
/// element count **at the moment of Drop**, not the maximum ever observed.
///
/// If entries are removed before Drop (e.g. via `HashMap::remove` or bulk
/// operations), the recorded sample **undercounts** the true peak.  Use
/// explicit `len()` snapshots at known peak points if accurate peak tracking
/// is required for shrinking maps.
///
/// `scc::HashMap::len()` is O(N) — only called on Drop (telemetry path).
pub struct TrackedSccHashMap<K, V, S = crate::CapHasher>
where
    K: Eq + Hash + 'static,
    V: 'static,
    S: BuildHasher,
{
    inner: scc::HashMap<K, V, S>,
    #[allow(dead_code)]
    name: &'static str,
    file: &'static str,
    line: u32,
    column: u32,
}

impl<K: Eq + Hash + 'static, V: 'static, S: BuildHasher + Default> TrackedSccHashMap<K, V, S> {
    /// Create with the default hasher (`S::default()`).
    pub fn with_capacity_named(
        cap: usize,
        name: &'static str,
        file: &'static str,
        line: u32,
        column: u32,
    ) -> Self {
        registry::record_creation(name, file, line, column);
        Self {
            inner: scc::HashMap::with_capacity_and_hasher(cap, S::default()),
            name,
            file,
            line,
            column,
        }
    }
}

impl<K: Eq + Hash + 'static, V: 'static, S: BuildHasher> TrackedSccHashMap<K, V, S> {
    /// Create with an explicit hasher instance (per-call override, Axis 2B).
    pub fn with_capacity_and_hasher_named(
        cap: usize,
        hasher: S,
        name: &'static str,
        file: &'static str,
        line: u32,
        column: u32,
    ) -> Self {
        registry::record_creation(name, file, line, column);
        Self {
            inner: scc::HashMap::with_capacity_and_hasher(cap, hasher),
            name,
            file,
            line,
            column,
        }
    }

    /// Wrap an already-constructed `scc::HashMap<K, V, S>` for capacity telemetry.
    ///
    /// Records creation in the registry; `inner` is moved as-is.
    /// The sample metric at `Drop` is `inner.len()` (scc::HashMap has no capacity()).
    #[inline]
    pub fn wrap_from(
        inner: scc::HashMap<K, V, S>,
        name: &'static str,
        file: &'static str,
        line: u32,
        column: u32,
    ) -> Self {
        registry::record_creation(name, file, line, column);
        Self {
            inner,
            name,
            file,
            line,
            column,
        }
    }
}

impl<K: Eq + Hash + 'static, V: 'static, S: BuildHasher> std::ops::Deref
    for TrackedSccHashMap<K, V, S>
{
    type Target = scc::HashMap<K, V, S>;
    fn deref(&self) -> &scc::HashMap<K, V, S> {
        &self.inner
    }
}

impl<K: Eq + Hash + 'static, V: 'static, S: BuildHasher> std::ops::DerefMut
    for TrackedSccHashMap<K, V, S>
{
    fn deref_mut(&mut self) -> &mut scc::HashMap<K, V, S> {
        &mut self.inner
    }
}

impl<K: Eq + Hash + 'static, V: 'static, S: BuildHasher> Drop for TrackedSccHashMap<K, V, S> {
    fn drop(&mut self) {
        // O(N) ack: telemetry only — scc::HashMap::len() is a full traversal,
        // but this only runs on Drop, not on any hot path.
        #[allow(clippy::disallowed_methods)]
        let peak = self.inner.len();
        registry::record_sample(self.file, self.line, self.column, peak);
    }
}

// `Default` is no longer needed — ptr::read replaces mem::replace.
impl<K: Eq + Hash + 'static, V: 'static, S: BuildHasher> From<TrackedSccHashMap<K, V, S>>
    for scc::HashMap<K, V, S>
{
    fn from(tracked: TrackedSccHashMap<K, V, S>) -> scc::HashMap<K, V, S> {
        #[allow(clippy::disallowed_methods)]
        let peak = tracked.inner.len();
        registry::record_sample(tracked.file, tracked.line, tracked.column, peak);
        // SAFETY: `tracked` is owned and forgotten below; ptr::read bit-copies
        // `inner` without requiring `Default` on S.
        let inner = unsafe { std::ptr::read(&tracked.inner) };
        std::mem::forget(tracked);
        inner
    }
}

impl<K: Eq + Hash + 'static, V: 'static, S: BuildHasher> IntoInner for TrackedSccHashMap<K, V, S> {
    type Inner = scc::HashMap<K, V, S>;
    #[inline]
    fn into_inner(self) -> scc::HashMap<K, V, S> {
        scc::HashMap::from(self)
    }
}