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

use std::collections::BTreeSet;

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

/// A `BTreeSet<T>` wrapper that records creation count and capacity samples.
///
/// Like `TrackedBTreeMap`, the capacity hint is accepted but ignored for the
/// inner allocation.
///
/// # Samples record `len()`, NOT peak occupancy
///
/// B-tree capacity is not observable.  On every `Drop` (or `IntoIterator` /
/// `From` conversion), `inner.len()` is pushed as the sample — this is the
/// element count **at the moment of Drop**, not the maximum ever observed.
///
/// For sets that may shrink before Drop (e.g. via `BTreeSet::clear` or
/// repeated `remove` calls), the recorded sample **undercounts** the true
/// peak.  Use `BTreeSet::len()` at the known peak point if accurate peak
/// tracking is required.
pub struct TrackedBTreeSet<T: Ord> {
    inner: BTreeSet<T>,
    #[allow(dead_code)]
    name: &'static str,
    file: &'static str,
    line: u32,
    column: u32,
}

impl<T: Ord> TrackedBTreeSet<T> {
    pub fn new_named(
        _cap_hint: usize,
        name: &'static str,
        file: &'static str,
        line: u32,
        column: u32,
    ) -> Self {
        registry::record_creation(name, file, line, column);
        Self {
            inner: BTreeSet::new(),
            name,
            file,
            line,
            column,
        }
    }

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

impl<T: Ord> std::ops::DerefMut for TrackedBTreeSet<T> {
    fn deref_mut(&mut self) -> &mut BTreeSet<T> {
        &mut self.inner
    }
}

impl<T: Ord> Drop for TrackedBTreeSet<T> {
    fn drop(&mut self) {
        registry::record_sample(self.file, self.line, self.column, self.inner.len());
    }
}

impl<T: Ord> From<TrackedBTreeSet<T>> for BTreeSet<T> {
    fn from(tracked: TrackedBTreeSet<T>) -> BTreeSet<T> {
        registry::record_sample(
            tracked.file,
            tracked.line,
            tracked.column,
            tracked.inner.len(),
        );
        // SAFETY: `tracked` is owned and forgotten below; ptr::read bit-copies `inner`.
        let inner = unsafe { std::ptr::read(&tracked.inner) };
        std::mem::forget(tracked);
        inner
    }
}

impl<T: Ord> IntoInner for TrackedBTreeSet<T> {
    type Inner = BTreeSet<T>;
    #[inline]
    fn into_inner(self) -> BTreeSet<T> {
        BTreeSet::from(self)
    }
}

impl<T: Ord> IntoIterator for TrackedBTreeSet<T> {
    type Item = T;
    type IntoIter = std::collections::btree_set::IntoIter<T>;

    fn into_iter(self) -> Self::IntoIter {
        registry::record_sample(self.file, self.line, self.column, self.inner.len());
        // SAFETY: `self` is owned and forgotten below; ptr::read bit-copies `inner`.
        let inner = unsafe { std::ptr::read(&self.inner) };
        std::mem::forget(self);
        inner.into_iter()
    }
}