uzor-framework 1.5.7

uzor app engine: one kernel of single-writer engines driven by a typed input bus
Documentation
//! Generic named-stage frame profiler + the shared EMA helper.
//!
//! Moved from `the old framework module::frame_profiler`. There is no JSON
//! sink (design L-U7); callers read [`FrameProfiler::stage_ms`] /
//! [`FrameProfiler::stages`].
//!
//! Stage names are caller-supplied `&'static str` keys, not a fixed enum.
//! The aggregator owns no clock and no serializer: feed milliseconds in,
//! read the smoothed map back out.
//!
//! **This module owns NO clock.** It lives in the platform-agnostic core
//! (`std::time::Instant` panics at runtime on `wasm32-unknown-unknown`,
//! and this crate compiles for every window backend), so the aggregator
//! only ever accepts caller-measured durations via
//! [`FrameProfiler::record_ms`] — pure math + naming. The measuring edge
//! stays wherever a real monotonic clock exists (e.g.
//! `uzor-desktop::Manager` brackets with `Instant` and feeds the result
//! in; a web backend would feed `performance.now()` deltas).
//!
//! [`EmaF64`] deduplicates a smoothing formula that used to be
//! hand-rolled independently in two places: the source app's own
//! `FrameProfile::ema` (`previous * 0.92 + sample * 0.08`) and
//! `Manager`'s own whole-frame `fps_ema` (`previous * 0.9 + sample *
//! 0.1`). `Manager::fps_ema`'s public behavior (the `f32` field, its
//! exact smoothing formula/seed) is unchanged — it now computes that
//! same formula through an [`EmaF64`] tracker instead of the formula
//! written out inline a second time.

use std::collections::HashMap;

/// Exponential moving average over `f64` samples, with an
/// alpha-per-`update`-call smoothing factor (rather than a
/// fixed-at-construction one) so a single small primitive can back both
/// this module's per-stage profiler (alpha `0.08`, the source app's own
/// constant) and `uzor-desktop::Manager`'s own whole-frame `fps_ema`
/// (alpha `0.1`) without needing two copies of the formula.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct EmaF64 {
    value: f64,
    initialized: bool,
}

impl Default for EmaF64 {
    fn default() -> Self {
        Self {
            value: 0.0,
            initialized: false,
        }
    }
}

impl EmaF64 {
    /// A fresh, uninitialized tracker — its very first [`EmaF64::update`]
    /// call wins outright (no smoothing against `0.0`).
    pub fn new() -> Self {
        Self::default()
    }

    /// A tracker pre-seeded with `value`, marked initialized — the first
    /// real [`EmaF64::update`] call blends against `value` instead of
    /// replacing it outright. Useful when a caller has a sensible
    /// starting guess (e.g. an assumed `60.0` fps before the first frame
    /// has actually been timed) rather than wanting the very first
    /// sample to jump straight to its own raw value.
    pub fn seeded(value: f64) -> Self {
        Self {
            value,
            initialized: true,
        }
    }

    /// Fold `sample` into the running average at smoothing factor
    /// `alpha` (`0.0..=1.0`; higher = more responsive to new samples,
    /// lower = smoother/slower) and return the new value. The very first
    /// call on an uninitialized (`Self::new`/`Self::default`) tracker
    /// always wins outright — matches both source call sites' own
    /// `if initialized { blend } else { sample }` cold-start rule,
    /// avoiding a synthetic warm-up period biased toward whatever value
    /// the struct happened to start at.
    pub fn update(&mut self, sample: f64, alpha: f64) -> f64 {
        self.value = if self.initialized {
            self.value * (1.0 - alpha) + sample * alpha
        } else {
            sample
        };
        self.initialized = true;
        self.value
    }

    /// Current smoothed value (`0.0` if never updated and not seeded).
    pub fn value(&self) -> f64 {
        self.value
    }

    /// Whether at least one [`EmaF64::update`] has run, or the tracker
    /// was constructed via [`EmaF64::seeded`].
    pub fn is_initialized(&self) -> bool {
        self.initialized
    }
}

/// Named-stage, per-frame profiler with independent EMA smoothing per
/// stage — the generic mechanism behind the source app's own
/// `FrameProfile`. Stage names are caller-supplied `&'static str` keys
/// (e.g. `"grid"`, `"scene_build"`, `"overlay"`), not a fixed enum, so
/// any app's own frame-phase vocabulary ports over unchanged.
///
/// Clock-free by design (module doc) — the caller measures each stage
/// with whatever monotonic clock its platform has and feeds the elapsed
/// milliseconds into [`FrameProfiler::record_ms`].
#[derive(Debug, Clone)]
pub struct FrameProfiler {
    alpha: f64,
    stages: HashMap<&'static str, EmaF64>,
    frames: u64,
}

impl FrameProfiler {
    /// The source app's own smoothing constant
    /// (`previous * 0.92 + sample * 0.08`).
    pub const DEFAULT_ALPHA: f64 = 0.08;

    /// A profiler smoothing every stage at `alpha` (see [`EmaF64::update`]).
    pub fn new(alpha: f64) -> Self {
        Self {
            alpha,
            stages: HashMap::new(),
            frames: 0,
        }
    }

    /// Record a caller-measured sample in milliseconds for `stage`,
    /// folding it into that stage's own running EMA — the stage's
    /// tracker is created (uninitialized) on first use, so its own first
    /// sample wins outright rather than blending against a synthetic
    /// `0.0`.
    pub fn record_ms(&mut self, stage: &'static str, sample_ms: f64) {
        self.stages
            .entry(stage)
            .or_default()
            .update(sample_ms, self.alpha);
    }

    /// Current smoothed value (ms) for `stage`, or `0.0` if it has never
    /// been recorded.
    pub fn stage_ms(&self, stage: &str) -> f64 {
        self.stages.get(stage).map_or(0.0, EmaF64::value)
    }

    /// Every currently-tracked stage's smoothed value — iteration order
    /// is NOT guaranteed (backed by a `HashMap`); a caller that needs a
    /// fixed field order should read [`FrameProfiler::stage_ms`] per
    /// named stage instead.
    pub fn stages(&self) -> impl Iterator<Item = (&'static str, f64)> + '_ {
        self.stages.iter().map(|(&name, ema)| (name, ema.value()))
    }

    /// Total frames [`FrameProfiler::end_frame`] has been called for.
    pub fn frame_count(&self) -> u64 {
        self.frames
    }

    /// Bump the frame counter — call once per frame (typically after
    /// recording that frame's stages), independent of how many stages
    /// were actually recorded that frame.
    pub fn end_frame(&mut self) {
        self.frames = self.frames.wrapping_add(1);
    }
}

impl Default for FrameProfiler {
    fn default() -> Self {
        Self::new(Self::DEFAULT_ALPHA)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn ema_first_sample_wins_outright_when_uninitialized() {
        let mut ema = EmaF64::new();
        assert!(!ema.is_initialized());
        assert_eq!(ema.update(42.0, 0.1), 42.0);
        assert!(ema.is_initialized());
    }

    #[test]
    fn ema_blends_subsequent_samples_by_alpha() {
        let mut ema = EmaF64::new();
        ema.update(100.0, 0.1);
        let next = ema.update(0.0, 0.1);
        assert!(
            (next - 90.0).abs() < 1e-9,
            "expected 100*0.9 + 0*0.1 = 90, got {next}"
        );
    }

    #[test]
    fn ema_seeded_blends_the_seed_on_the_very_first_real_sample() {
        let mut ema = EmaF64::seeded(60.0);
        assert!(ema.is_initialized());
        let next = ema.update(120.0, 0.1);
        assert!((next - (60.0 * 0.9 + 120.0 * 0.1)).abs() < 1e-9);
    }

    #[test]
    fn ema_converges_toward_a_sustained_constant_sample() {
        let mut ema = EmaF64::new();
        for _ in 0..500 {
            ema.update(16.0, 0.2);
        }
        assert!(
            (ema.value() - 16.0).abs() < 1e-6,
            "a sustained constant sample must converge, got {}",
            ema.value()
        );
    }

    #[test]
    fn frame_profiler_default_alpha_matches_the_source_apps_own_smoothing_constant() {
        assert_eq!(FrameProfiler::DEFAULT_ALPHA, 0.08);
        let profiler = FrameProfiler::default();
        assert_eq!(profiler.frame_count(), 0);
    }

    #[test]
    fn frame_profiler_record_ms_creates_and_smooths_a_named_stage() {
        let mut profiler = FrameProfiler::new(0.08);
        profiler.record_ms("grid", 10.0);
        assert_eq!(
            profiler.stage_ms("grid"),
            10.0,
            "first sample must win outright"
        );
        let smoothed = {
            profiler.record_ms("grid", 20.0);
            profiler.stage_ms("grid")
        };
        assert!((smoothed - (10.0 * 0.92 + 20.0 * 0.08)).abs() < 1e-9);
    }

    #[test]
    fn frame_profiler_stage_ms_returns_zero_for_a_never_recorded_stage() {
        let profiler = FrameProfiler::new(0.08);
        assert_eq!(profiler.stage_ms("never_recorded"), 0.0);
    }

    #[test]
    fn frame_profiler_end_frame_increments_the_frame_counter_independent_of_stage_recording() {
        let mut profiler = FrameProfiler::new(0.08);
        profiler.end_frame();
        profiler.record_ms("grid", 1.0);
        profiler.end_frame();
        assert_eq!(profiler.frame_count(), 2);
    }

    #[test]
    fn frame_profiler_stages_iterates_every_recorded_stage() {
        let mut profiler = FrameProfiler::new(0.08);
        profiler.record_ms("grid", 1.0);
        profiler.record_ms("overlay", 2.0);
        let mut names: Vec<&str> = profiler.stages().map(|(name, _)| name).collect();
        names.sort_unstable();
        assert_eq!(names, vec!["grid", "overlay"]);
    }
}