1#![cfg_attr(not(feature = "std"), no_std)]
2
3extern 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
48const DEFAULT_SUMMARY_EVERY: u64 = 100;
52
53#[derive(Default, Clone, Copy)]
56struct StepCounters {
57 allocated: u64,
58 deallocated: u64,
59 calls: u64,
60 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 counters_available: bool,
129 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 cl_counter: AtomicU64,
141 state: Mutex<State>,
142 feature_off_warned: AtomicBool,
144 first_observation_seen: AtomicBool,
149 derive_off_warned: AtomicBool,
152 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 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 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 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 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 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 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 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 self.total_alloc.fetch_add(alloc_u64, Ordering::Relaxed);
361 self.total_dealloc.fetch_add(dealloc_u64, Ordering::Relaxed);
362 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 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 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 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 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}