Skip to main content

cu_memmon/
lib.rs

1#![cfg_attr(not(feature = "std"), no_std)]
2
3//! Per-task heap-allocation monitor for Copper.
4//!
5//! `CuMemMon` consumes the [`CuMonitor::observe_alloc`] hook the runtime emits
6//! around every task and bridge lifecycle step and reports:
7//! - per-step allocation deltas (running totals + per-call peak),
8//! - per-task lifetime balance (`alloc - dealloc` since the task's `start`),
9//! - a throttled `[mem]` one-liner from `process_copperlist`,
10//! - a final per-task **leak report** at runtime shutdown.
11//!
12//! Optional realtime-strict mode (`realtime_strict: true` in the monitor's
13//! RON config) latches any non-zero allocation observed during `Preprocess`,
14//! `Process`, or `Postprocess` and surfaces it from the *following*
15//! `process_copperlist` call as a `CuError`. In practice that is the very same
16//! iteration's `process_copperlist` (it runs after all the step hooks), so the
17//! violation aborts the run within the same tick it occurred in. The runtime
18//! treats the returned error as a fatal monitor error and shuts down cleanly
19//! — unrelated task errors are not escalated by this path. The first violating
20//! step in a copperlist wins (later violations in the same window are
21//! observed but don't overwrite the latched cause).
22//!
23//! When the runtime is **not** built with `cu29/memory_monitoring`, the macro
24//! emits no allocation scopes, so `observe_alloc` is never called. `CuMemMon`
25//! detects this in two complementary ways:
26//! - At `start()` it probes the public counter API
27//!   ([`cu29::monitoring::global_allocated_bytes`]). If that returns `None`
28//!   the runtime side is off and we warn immediately.
29//! - If the runtime side is on but no `observe_alloc` ever fires (the macro
30//!   side was built without the feature — possible when features are wired
31//!   piecemeal instead of through the `cu29` umbrella), the first scheduled
32//!   summary tick emits a one-shot warning.
33
34extern crate alloc;
35
36use alloc::vec::Vec;
37use core::sync::atomic::{AtomicBool, AtomicU64, Ordering};
38use cu29::__private::sync::Mutex;
39use cu29::prelude::*;
40
41#[cfg(all(feature = "std", debug_assertions))]
42use alloc::string::String;
43#[cfg(all(feature = "std", debug_assertions))]
44use alloc::string::ToString;
45#[cfg(all(feature = "std", debug_assertions))]
46use std::collections::HashMap as StdHashMap;
47
48/// Number of copperlists between throttled `[mem]` summary lines.
49/// Picked to be roughly once per second at 100 Hz; users that want quieter
50/// runs can disable via `summary_every: 0` in the monitor config.
51const DEFAULT_SUMMARY_EVERY: u64 = 100;
52
53/// One slot per (component, step). We collapse all five steps into separate
54/// counters per component for compact storage and O(1) updates.
55#[derive(Default, Clone, Copy)]
56struct StepCounters {
57    allocated: u64,
58    deallocated: u64,
59    calls: u64,
60    /// Largest single-call allocation seen for this step.
61    max_allocated: u64,
62}
63
64#[derive(Clone, Copy)]
65struct ComponentCounters {
66    start: StepCounters,
67    preprocess: StepCounters,
68    process: StepCounters,
69    postprocess: StepCounters,
70    stop: StepCounters,
71}
72
73impl ComponentCounters {
74    const fn new() -> Self {
75        const Z: StepCounters = StepCounters {
76            allocated: 0,
77            deallocated: 0,
78            calls: 0,
79            max_allocated: 0,
80        };
81        Self {
82            start: Z,
83            preprocess: Z,
84            process: Z,
85            postprocess: Z,
86            stop: Z,
87        }
88    }
89
90    fn slot(&mut self, step: CuComponentState) -> &mut StepCounters {
91        match step {
92            CuComponentState::Start => &mut self.start,
93            CuComponentState::Preprocess => &mut self.preprocess,
94            CuComponentState::Process => &mut self.process,
95            CuComponentState::Postprocess => &mut self.postprocess,
96            CuComponentState::Stop => &mut self.stop,
97        }
98    }
99
100    fn lifetime_alloc(&self) -> u64 {
101        self.start.allocated
102            + self.preprocess.allocated
103            + self.process.allocated
104            + self.postprocess.allocated
105            + self.stop.allocated
106    }
107
108    fn lifetime_dealloc(&self) -> u64 {
109        self.start.deallocated
110            + self.preprocess.deallocated
111            + self.process.deallocated
112            + self.postprocess.deallocated
113            + self.stop.deallocated
114    }
115}
116
117#[derive(Clone, Copy)]
118struct RtViolation {
119    step: CuComponentState,
120    allocated: u64,
121    deallocated: u64,
122}
123
124struct State {
125    per_component: Vec<ComponentCounters>,
126    /// True iff the runtime was compiled with `memory_monitoring`.
127    /// Probed in `new()` by reading the public counters from the runtime.
128    counters_available: bool,
129    /// Pending realtime-strict violations to surface from the next
130    /// `process_copperlist`. One slot per component; latest wins.
131    rt_pending: Vec<Option<RtViolation>>,
132}
133
134pub struct CuMemMon {
135    components: &'static [MonitorComponentMetadata],
136    component_count: usize,
137    realtime_strict: bool,
138    summary_every: u64,
139    /// Monotonic copperlist counter, drives the throttled summary.
140    cl_counter: AtomicU64,
141    state: Mutex<State>,
142    /// True once we've emitted the "feature off" warning, so we don't spam.
143    feature_off_warned: AtomicBool,
144    /// Set to true the first time `observe_alloc` fires. Combined with
145    /// `counters_available`, this catches the case where the runtime crate has
146    /// `memory_monitoring` enabled but the derive crate doesn't — the probe
147    /// would otherwise read as "active" while no scope ever runs.
148    first_observation_seen: AtomicBool,
149    /// True once we've warned that the macro side seems to be off despite the
150    /// runtime side being on. Prevents spamming the log every summary tick.
151    derive_off_warned: AtomicBool,
152    /// Total observed allocations / deallocations across the whole runtime
153    /// (cheap monotonic counters for the periodic summary header).
154    total_alloc: AtomicU64,
155    total_dealloc: AtomicU64,
156}
157
158fn lock_state(state: &Mutex<State>) -> StateGuard<'_> {
159    #[cfg(feature = "std")]
160    {
161        state.lock().unwrap_or_else(|poison| poison.into_inner())
162    }
163    #[cfg(not(feature = "std"))]
164    {
165        state.lock()
166    }
167}
168
169#[cfg(feature = "std")]
170type StateGuard<'a> = std::sync::MutexGuard<'a, State>;
171#[cfg(not(feature = "std"))]
172type StateGuard<'a> = spin::MutexGuard<'a, State, spin::relax::Spin>;
173
174fn parse_realtime_strict(cfg: Option<&ComponentConfig>) -> CuResult<bool> {
175    let Some(cfg) = cfg else { return Ok(false) };
176    if let Some(strict) = cfg.get::<bool>("realtime_strict")? {
177        return Ok(strict);
178    }
179    Ok(false)
180}
181
182fn parse_summary_every(cfg: Option<&ComponentConfig>) -> CuResult<u64> {
183    let Some(cfg) = cfg else {
184        return Ok(DEFAULT_SUMMARY_EVERY);
185    };
186    if let Some(value) = cfg.get::<u32>("summary_every")? {
187        return Ok(value as u64);
188    }
189    Ok(DEFAULT_SUMMARY_EVERY)
190}
191
192fn step_label(step: CuComponentState) -> &'static str {
193    match step {
194        CuComponentState::Start => "start",
195        CuComponentState::Preprocess => "pre",
196        CuComponentState::Process => "process",
197        CuComponentState::Postprocess => "post",
198        CuComponentState::Stop => "stop",
199    }
200}
201
202#[inline]
203fn is_realtime_step(step: CuComponentState) -> bool {
204    matches!(
205        step,
206        CuComponentState::Preprocess | CuComponentState::Process | CuComponentState::Postprocess
207    )
208}
209
210impl CuMemMon {
211    fn component_name(&self, component_id: ComponentId) -> &'static str {
212        debug_assert!(component_id.index() < self.component_count);
213        self.components[component_id.index()].id()
214    }
215}
216
217impl CuMonitor for CuMemMon {
218    fn new(metadata: CuMonitoringMetadata, _runtime: CuMonitoringRuntime) -> CuResult<Self> {
219        let components = metadata.components();
220        let component_count = components.len();
221        let realtime_strict = parse_realtime_strict(metadata.monitor_config())?;
222        let summary_every = parse_summary_every(metadata.monitor_config())?;
223
224        // Probe the runtime API: when `memory_monitoring` is off, the macro
225        // never emits ScopedAllocCounter, so this hook would otherwise never
226        // fire — `start()` uses this to print a single warning.
227        let counters_available = cu29::monitoring::global_allocated_bytes().is_some();
228
229        let state = State {
230            per_component: alloc::vec![ComponentCounters::new(); component_count],
231            counters_available,
232            rt_pending: alloc::vec![None; component_count],
233        };
234
235        Ok(Self {
236            components,
237            component_count,
238            realtime_strict,
239            summary_every,
240            cl_counter: AtomicU64::new(0),
241            state: Mutex::new(state),
242            feature_off_warned: AtomicBool::new(false),
243            first_observation_seen: AtomicBool::new(false),
244            derive_off_warned: AtomicBool::new(false),
245            total_alloc: AtomicU64::new(0),
246            total_dealloc: AtomicU64::new(0),
247        })
248    }
249
250    fn start(&mut self, ctx: &CuContext) -> CuResult<()> {
251        // Mirror NoMonitor: tee every live structured log entry to stdout in
252        // std debug builds so apps that pick cu_memmon as their (only)
253        // monitor still see info!/warning!/error! on the console.
254        register_console_listener();
255
256        let state = lock_state(&self.state);
257        if !state.counters_available {
258            warning!(
259                ctx,
260                "cu_memmon enabled but cu29 was built without `memory_monitoring`. \
261                 No allocation scopes emitted; all reports will be zero."
262            );
263            self.feature_off_warned.store(true, Ordering::Relaxed);
264        } else {
265            info!(
266                ctx,
267                "cu_memmon started: {} components, realtime_strict={}, summary_every={}",
268                self.component_count,
269                self.realtime_strict,
270                self.summary_every,
271            );
272        }
273        Ok(())
274    }
275
276    fn process_copperlist(&self, ctx: &CuContext, _view: CopperListView<'_>) -> CuResult<()> {
277        // 1) Surface realtime-strict violations: drain pending and return a
278        //    CuError. The runtime will treat this as fatal and shut down.
279        if self.realtime_strict {
280            let drained = {
281                let mut state = lock_state(&self.state);
282                drain_rt_violations(&mut state.rt_pending)
283            };
284            if !drained.is_empty() {
285                // Format only the first violation; multiples in the same
286                // copperlist are rare and a single trip-wire suffices.
287                let (component_id, viol) = drained[0];
288                let name = self.component_name(component_id);
289                return report_rt_violation(ctx, name, viol);
290            }
291        }
292
293        // 2) Throttled summary. `summary_every == 0` disables the summary.
294        if self.summary_every == 0 {
295            return Ok(());
296        }
297        let n = self.cl_counter.fetch_add(1, Ordering::Relaxed) + 1;
298        if !n.is_multiple_of(self.summary_every) {
299            return Ok(());
300        }
301        // Snapshot under the lock; format without holding it.
302        let snapshot: Vec<(&'static str, ComponentCounters)> = {
303            let state = lock_state(&self.state);
304            if !state.counters_available {
305                return Ok(());
306            }
307            self.components
308                .iter()
309                .zip(state.per_component.iter())
310                .map(|(meta, counters)| (meta.id(), *counters))
311                .collect()
312        };
313        // Detect the derive-side-off misconfiguration: the runtime crate has
314        // the counting allocator installed (counters_available == true) but
315        // the proc-macro never emitted any ScopedAllocCounter scopes, so
316        // observe_alloc has never fired by the time the first summary fires.
317        // Warn once and continue; the summary lines will read all-zero on
318        // their own and that explains why.
319        if !self.first_observation_seen.load(Ordering::Relaxed)
320            && !self.derive_off_warned.swap(true, Ordering::Relaxed)
321        {
322            warning!(
323                ctx,
324                "cu_memmon: runtime allocator counters are active but no allocation \
325                 scopes have fired after {} copperlists. This usually means cu29-derive \
326                 was built without the `memory_monitoring` feature. Enable it via the \
327                 cu29 umbrella crate: `cu29 = {{ features = [\"memory_monitoring\"] }}`.",
328                n,
329            );
330        }
331        for (name, c) in snapshot.iter() {
332            let leak = c.lifetime_alloc().saturating_sub(c.lifetime_dealloc());
333            info!(
334                ctx,
335                "[mem] {} start=+{}B -{}B | proc max=+{}B over {} calls | stop=+{}B -{}B | leak={}B",
336                *name,
337                c.start.allocated,
338                c.start.deallocated,
339                c.process.max_allocated,
340                c.process.calls,
341                c.stop.allocated,
342                c.stop.deallocated,
343                leak,
344            );
345        }
346        Ok(())
347    }
348
349    fn observe_alloc(
350        &self,
351        component_id: ComponentId,
352        step: CuComponentState,
353        allocated_bytes: usize,
354        deallocated_bytes: usize,
355    ) {
356        let alloc_u64 = allocated_bytes as u64;
357        let dealloc_u64 = deallocated_bytes as u64;
358        // Aggregate counters first — relaxed atomics suffice for an
359        // eventually-correct periodic summary header.
360        self.total_alloc.fetch_add(alloc_u64, Ordering::Relaxed);
361        self.total_dealloc.fetch_add(dealloc_u64, Ordering::Relaxed);
362        // Record that the macro side did wire up scopes, so the periodic
363        // probe in process_copperlist doesn't false-alarm.
364        self.first_observation_seen.store(true, Ordering::Relaxed);
365
366        let mut state = lock_state(&self.state);
367        let idx = component_id.index();
368        debug_assert!(
369            idx < state.per_component.len(),
370            "cu_memmon: component id {idx} out of bounds {}",
371            state.per_component.len()
372        );
373        let Some(component) = state.per_component.get_mut(idx) else {
374            return;
375        };
376        let slot = component.slot(step);
377        slot.allocated = slot.allocated.saturating_add(alloc_u64);
378        slot.deallocated = slot.deallocated.saturating_add(dealloc_u64);
379        slot.calls = slot.calls.saturating_add(1);
380        if alloc_u64 > slot.max_allocated {
381            slot.max_allocated = alloc_u64;
382        }
383
384        // Latch realtime violations: first non-zero alloc on a hot-path step
385        // becomes a pending error that the following process_copperlist
386        // surfaces. First-wins: once a violation is latched we keep it, so
387        // the surfaced cause names the *earliest* offending step rather than
388        // whatever happened to fire last.
389        if self.realtime_strict
390            && is_realtime_step(step)
391            && allocated_bytes > 0
392            && state.rt_pending[idx].is_none()
393        {
394            state.rt_pending[idx] = Some(RtViolation {
395                step,
396                allocated: alloc_u64,
397                deallocated: dealloc_u64,
398            });
399        }
400    }
401
402    fn process_error(
403        &self,
404        _component_id: ComponentId,
405        _step: CuComponentState,
406        _error: &CuError,
407    ) -> Decision {
408        // cu_memmon is a passive observer for non-memory errors: hand the
409        // runtime's default policy back. Memory violations are escalated via
410        // process_copperlist returning Err, not through here.
411        Decision::Ignore
412    }
413
414    fn stop(&mut self, ctx: &CuContext) -> CuResult<()> {
415        let state = lock_state(&self.state);
416        if !state.counters_available {
417            unregister_console_listener();
418            return Ok(());
419        }
420        info!(
421            ctx,
422            "cu_memmon final report: total +{}B / -{}B",
423            self.total_alloc.load(Ordering::Relaxed),
424            self.total_dealloc.load(Ordering::Relaxed),
425        );
426        for (idx, counters) in state.per_component.iter().enumerate() {
427            let name = self.components[idx].id();
428            let lifetime_alloc = counters.lifetime_alloc();
429            let lifetime_dealloc = counters.lifetime_dealloc();
430            let process_alloc = counters.process.allocated;
431            let process_calls = counters.process.calls;
432            if lifetime_alloc > lifetime_dealloc {
433                let leak = lifetime_alloc - lifetime_dealloc;
434                warning!(
435                    ctx,
436                    "cu_memmon: task {} leak={}B (alloc {}B, dealloc {}B); process allocated {}B over {} calls",
437                    name,
438                    leak,
439                    lifetime_alloc,
440                    lifetime_dealloc,
441                    process_alloc,
442                    process_calls,
443                );
444            } else if lifetime_alloc < lifetime_dealloc {
445                // Symmetric anomaly: the task freed more than it allocated
446                // within its own scopes. Usually means it returned memory
447                // originally allocated outside its observed lifecycle.
448                let excess = lifetime_dealloc - lifetime_alloc;
449                warning!(
450                    ctx,
451                    "cu_memmon: task {} dealloc excess={}B (alloc {}B, dealloc {}B); process allocated {}B over {} calls — task may free memory it didn't allocate within its own steps",
452                    name,
453                    excess,
454                    lifetime_alloc,
455                    lifetime_dealloc,
456                    process_alloc,
457                    process_calls,
458                );
459            } else {
460                info!(
461                    ctx,
462                    "cu_memmon: task {} balanced (alloc {}B, dealloc {}B); process allocated {}B over {} calls",
463                    name,
464                    lifetime_alloc,
465                    lifetime_dealloc,
466                    process_alloc,
467                    process_calls,
468                );
469            }
470        }
471        drop(state);
472        unregister_console_listener();
473        Ok(())
474    }
475}
476
477fn drain_rt_violations(pending: &mut [Option<RtViolation>]) -> Vec<(ComponentId, RtViolation)> {
478    let mut out = Vec::new();
479    for (idx, slot) in pending.iter_mut().enumerate() {
480        if let Some(v) = slot.take() {
481            out.push((ComponentId::new(idx), v));
482        }
483    }
484    out
485}
486
487#[cfg(feature = "std")]
488fn format_rt_violation_message(name: &str, viol: RtViolation) -> String {
489    alloc::format!(
490        "cu_memmon: realtime violation: component {} allocated {} B (deallocated {} B) during {}",
491        name,
492        viol.allocated,
493        viol.deallocated,
494        step_label(viol.step),
495    )
496}
497
498#[cfg(feature = "std")]
499fn report_rt_violation(ctx: &CuContext, name: &str, viol: RtViolation) -> CuResult<()> {
500    let msg = format_rt_violation_message(name, viol);
501    error!(ctx, "{}", msg.as_str());
502    Err(CuError::from(msg.as_str()))
503}
504
505#[cfg(not(feature = "std"))]
506fn report_rt_violation(ctx: &CuContext, name: &str, viol: RtViolation) -> CuResult<()> {
507    error!(
508        ctx,
509        "cu_memmon: realtime violation: component {} allocated {} B (deallocated {} B) during {}",
510        name,
511        viol.allocated,
512        viol.deallocated,
513        step_label(viol.step),
514    );
515    Err(CuError::from("cu_memmon: realtime allocation violation"))
516}
517
518#[cfg(all(feature = "std", debug_assertions))]
519fn register_console_listener() {
520    use std::println;
521    register_live_log_listener(|entry, format_str, param_names| {
522        let params: Vec<String> = entry.params.iter().map(|v| v.to_string()).collect();
523        let named: StdHashMap<String, String> = param_names
524            .iter()
525            .zip(params.iter())
526            .map(|(k, v)| (k.to_string(), v.clone()))
527            .collect();
528
529        if let Ok(msg) = format_message_only(format_str, params.as_slice(), &named) {
530            println!("[{:?}] {}", entry.level, msg);
531        }
532    });
533}
534
535#[cfg(not(all(feature = "std", debug_assertions)))]
536fn register_console_listener() {}
537
538#[cfg(all(feature = "std", debug_assertions))]
539fn unregister_console_listener() {
540    unregister_live_log_listener();
541}
542
543#[cfg(not(all(feature = "std", debug_assertions)))]
544fn unregister_console_listener() {}
545
546#[cfg(test)]
547mod tests {
548    use super::*;
549
550    #[test]
551    fn step_label_covers_all_states() {
552        assert_eq!(step_label(CuComponentState::Start), "start");
553        assert_eq!(step_label(CuComponentState::Preprocess), "pre");
554        assert_eq!(step_label(CuComponentState::Process), "process");
555        assert_eq!(step_label(CuComponentState::Postprocess), "post");
556        assert_eq!(step_label(CuComponentState::Stop), "stop");
557    }
558
559    #[test]
560    fn is_realtime_step_only_flags_hot_path_states() {
561        assert!(!is_realtime_step(CuComponentState::Start));
562        assert!(is_realtime_step(CuComponentState::Preprocess));
563        assert!(is_realtime_step(CuComponentState::Process));
564        assert!(is_realtime_step(CuComponentState::Postprocess));
565        assert!(!is_realtime_step(CuComponentState::Stop));
566    }
567
568    #[test]
569    fn component_counters_track_per_step_and_lifetime_totals() {
570        let mut c = ComponentCounters::new();
571        c.slot(CuComponentState::Start).allocated += 1024;
572        c.slot(CuComponentState::Process).allocated += 256;
573        c.slot(CuComponentState::Process).deallocated += 256;
574        c.slot(CuComponentState::Stop).deallocated += 1024;
575
576        assert_eq!(c.start.allocated, 1024);
577        assert_eq!(c.process.allocated, 256);
578        assert_eq!(c.process.deallocated, 256);
579        assert_eq!(c.stop.deallocated, 1024);
580
581        assert_eq!(c.lifetime_alloc(), 1024 + 256);
582        assert_eq!(c.lifetime_dealloc(), 256 + 1024);
583        assert_eq!(c.lifetime_alloc().saturating_sub(c.lifetime_dealloc()), 0);
584    }
585
586    #[test]
587    fn drain_rt_violations_takes_pending_only() {
588        let mut pending = alloc::vec![
589            None,
590            Some(RtViolation {
591                step: CuComponentState::Process,
592                allocated: 128,
593                deallocated: 0
594            }),
595            None,
596            Some(RtViolation {
597                step: CuComponentState::Preprocess,
598                allocated: 32,
599                deallocated: 0
600            }),
601        ];
602        let drained = drain_rt_violations(&mut pending);
603        assert_eq!(drained.len(), 2);
604        assert!(pending.iter().all(|s| s.is_none()));
605        // Second drain reports nothing.
606        assert!(drain_rt_violations(&mut pending).is_empty());
607
608        let indices: Vec<usize> = drained.iter().map(|(id, _)| id.index()).collect();
609        assert_eq!(indices, alloc::vec![1, 3]);
610        assert!(matches!(drained[0].1.step, CuComponentState::Process));
611        assert_eq!(drained[0].1.allocated, 128);
612    }
613}