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

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

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

/// A `scc::HashSet<T, S>` wrapper that records creation count and capacity
/// samples.
///
/// `S` defaults to `crate::CapHasher`.
///
/// # Samples record `len()`, NOT peak occupancy
///
/// `scc::HashSet` 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, the recorded sample **undercounts** the
/// true peak.  Use explicit `len()` snapshots at known peak points if accurate
/// peak tracking is required for shrinking sets.
///
/// `scc::HashSet::len()` is O(N) — only called on Drop (telemetry path).
pub struct TrackedSccHashSet<T, S = crate::CapHasher>
where
    T: Eq + Hash + 'static,
    S: BuildHasher,
{
    inner: scc::HashSet<T, S>,
    #[allow(dead_code)]
    name: &'static str,
    file: &'static str,
    line: u32,
    column: u32,
}

impl<T: Eq + Hash + 'static, S: BuildHasher + Default> TrackedSccHashSet<T, 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::HashSet::with_capacity_and_hasher(cap, S::default()),
            name,
            file,
            line,
            column,
        }
    }
}

impl<T: Eq + Hash + 'static, S: BuildHasher> TrackedSccHashSet<T, 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::HashSet::with_capacity_and_hasher(cap, hasher),
            name,
            file,
            line,
            column,
        }
    }

    /// Wrap an already-constructed `scc::HashSet<T, S>` for capacity telemetry.
    ///
    /// Records creation in the registry; `inner` is moved as-is.
    /// The sample metric at `Drop` is `inner.len()` (scc::HashSet has no capacity()).
    #[inline]
    pub fn wrap_from(
        inner: scc::HashSet<T, 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<T: Eq + Hash + 'static, S: BuildHasher> std::ops::Deref for TrackedSccHashSet<T, S> {
    type Target = scc::HashSet<T, S>;
    fn deref(&self) -> &scc::HashSet<T, S> {
        &self.inner
    }
}

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

impl<T: Eq + Hash + 'static, S: BuildHasher> Drop for TrackedSccHashSet<T, S> {
    fn drop(&mut self) {
        // O(N) ack: telemetry only — scc::HashSet::len() is a full traversal.
        #[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<T: Eq + Hash + 'static, S: BuildHasher> From<TrackedSccHashSet<T, S>> for scc::HashSet<T, S> {
    fn from(tracked: TrackedSccHashSet<T, S>) -> scc::HashSet<T, 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<T: Eq + Hash + 'static, S: BuildHasher> IntoInner for TrackedSccHashSet<T, S> {
    type Inner = scc::HashSet<T, S>;
    #[inline]
    fn into_inner(self) -> scc::HashSet<T, S> {
        scc::HashSet::from(self)
    }
}