//! Optional fine-grained timing + RSS instrumentation.

//!

//! Behind the `probe` feature flag every [`Probe::span`] returns a guard

//! that records the elapsed wall-clock on `Drop`, and

//! [`Probe::sample_rss`] records a labelled RSS checkpoint. Events are

//! buffered in a per-thread [`Vec`] and drained by the consumer with

//! [`Probe::drain`].

//!

//! With the feature off every method is a `#[inline]` no-op so

//! release builds without the feature pay zero cost.

//!

//! Consumer (e.g. servo-shot) groups drained events by name to produce

//! the per-phase averages / p99s in its trace report.

use core::marker::PhantomData;

// WASM gate: `Instant::now()` panics on browser WASM (no monotonic clock)

// and `libc::getrusage` isn't available, so on `target_family = "wasm"`

// we drop to the no-op stubs even when the `probe` feature is on.

// `AZ_PROFILE=cpu` then prints "(probe unavailable on this target)"

// rather than crashing.

// [WEB-LIFT 2026-06-11] `web_lift` also forces the no-op imp: the real

// module is Instant::now (mach-time syscall, out-of-image when lifted) +

// thread-local pushes + first-access dtor registration (`_tlv_atexit`).

// With the TLV emulation in place TLS "works", which flips these from

// harmlessly-failing (`try_with` Err) to actually-running — and the

// mach/atexit extern calls inside are unliftable. Profiling is

// meaningless in lifted wasm; the dylib built with `web-transpiler*`

// (which enables `web_lift`) is the web-server build, so desktop

// release builds keep real probes.

#[cfg(all(

    feature = "probe",

    not(target_family = "wasm"),

    not(feature = "web_lift")

))]

mod imp {

    use std::cell::RefCell;

    use std::sync::atomic::{AtomicU8, Ordering};

    use std::time::Instant;

    thread_local! {

        static EVENTS: RefCell<Vec<super::Event>> = const { RefCell::new(Vec::new()) };

        /// Currently-open span count. Read when a span OPENS (its own

        /// depth) and decremented when it closes.

        static DEPTH: std::cell::Cell<u16> = const { std::cell::Cell::new(0) };

        /// Names of the currently-open spans, outermost first. Maintained

        /// UNCONDITIONALLY (even with recording off): this is what a crash

        /// report reads as "what scope was the app in" — a diagnostic that

        /// must not depend on AZ_PROFILE being set. Cost: one push/pop of a

        /// `&'static str` per span.

        static SPAN_NAMES: RefCell<Vec<&'static str>> = const { RefCell::new(Vec::new()) };

    }

    /// Whether spans/samples are RECORDED. The `probe` feature being compiled

    /// in used to mean "always record" — but the dll builds with `probe` on

    /// unconditionally, and the event buffer is only drained by the

    /// `AZ_PROFILE=cpu` report path. Every plain run therefore pushed ~40 B

    /// per span into a thread-local Vec that nothing ever emptied: unbounded

    /// growth, invisible to the `LayoutCache` memory walk (it's a thread-local).

    /// A 5 s resize drag alone is ~375 relayouts × hundreds of spans.

    ///

    /// 0 = uninitialized (resolve from `AZ_PROFILE` on first probe),

    /// 1 = recording, 2 = off.

    static RECORDING: AtomicU8 = AtomicU8::new(0);

    #[inline]

    fn recording() -> bool {

        match RECORDING.load(Ordering::Relaxed) {

            1 => true,

            2 => false,

            _ => {

                // First probe anywhere resolves the mode once. Any profile

                // mode that can consume events counts; the write is

                // idempotent so a racing thread resolving the same env is

                // harmless.

                let on = azul_core::profile::cpu_enabled()

                    || azul_core::profile::memory_enabled()

                    || azul_core::profile::heap_enabled();

                RECORDING.store(if on { 1 } else { 2 }, Ordering::Relaxed);

                on

            }

        }

    }

    pub(super) fn set_recording(on: bool) {

        RECORDING.store(if on { 1 } else { 2 }, Ordering::Relaxed);

    }

    /// RAII guard that records its name + elapsed nanos on drop.

    /// `start == None` means recording was off when the span opened: the

    /// guard is inert (no clock read on open, no TLS touch on drop).

    #[derive(Debug)]

    pub struct Span {

        pub(crate) name: &'static str,

        pub(crate) start: Option<Instant>,

        pub(crate) depth: u16,

    }

    impl Drop for Span {

        fn drop(&mut self) {

            let _ = SPAN_NAMES.try_with(|st| {

                st.borrow_mut().pop();

            });

            let Some(start) = self.start else { return };

            let dur_ns = start.elapsed().as_nanos() as u64;

            // try_with (not with): the lifted-to-wasm web backend has no real

            // TLS, so `with` hits panic_access_error. These probe accesses are

            // inlined into layout_dom_recursive/layout_document, so they can't

            // be stubbed at the symbol level — use the non-panicking access.

            let depth = self.depth;

            let _ = DEPTH.try_with(|d| d.set(d.get().saturating_sub(1)));

            let _ = EVENTS.try_with(|cell| {

                cell.borrow_mut().push(super::Event {

                    name: self.name,

                    kind: super::EventKind::Span { dur_ns },

                    depth,

                });

            });

        }

    }

    pub(super) fn open(name: &'static str) -> Span {

        let _ = SPAN_NAMES.try_with(|st| st.borrow_mut().push(name));

        if !recording() {

            return Span { name, start: None, depth: 0 };

        }

        let depth = DEPTH

            .try_with(|d| {

                let cur = d.get();

                d.set(cur.saturating_add(1));

                cur

            })

            .unwrap_or(0);

        Span { name, start: Some(Instant::now()), depth }

    }

    pub(super) fn sample_rss(label: &'static str, bytes: u64) {

        if !recording() {

            return;

        }

        // try_with: see Span::drop — no real TLS in the lifted wasm backend.

        let depth = DEPTH.try_with(std::cell::Cell::get).unwrap_or(0);

        let _ = EVENTS.try_with(|cell| {

            cell.borrow_mut().push(super::Event {

                name: label,

                kind: super::EventKind::Rss { bytes },

                depth,

            });

        });

    }

    /// The path of currently-open spans on THIS thread, outermost first,

    /// joined with `" > "` — e.g. `dispatch.timer > layout > text_shape`.

    /// Empty when no span is open. Readable from a panic hook (same thread).

    pub(super) fn span_path() -> String {

        SPAN_NAMES

            .try_with(|st| st.borrow().join(" > "))

            .unwrap_or_default()

    }

    pub(super) fn drain() -> Vec<super::Event> {

        EVENTS

            .try_with(|cell| core::mem::take(&mut *cell.borrow_mut()))

            .unwrap_or_default()

    }

    /// `dladdr`-backed pointer→symbol resolution with a leak-once cache.

    /// Span names are `&'static str`, so each distinct callback leaks ONE

    /// small string for the process lifetime — bounded by the number of

    /// distinct callbacks an app has.

    pub(super) fn resolve_fn_name(fn_ptr: usize) -> &'static str {

        use std::collections::HashMap;

        use std::sync::{Mutex, OnceLock};

        static CACHE: OnceLock<Mutex<HashMap<usize, &'static str>>> = OnceLock::new();

        let cache = CACHE.get_or_init(|| Mutex::new(HashMap::new()));

        if let Ok(map) = cache.lock() {

            if let Some(name) = map.get(&fn_ptr) {

                return name;

            }

        }

        let resolved: &'static str = {

            #[cfg(unix)]

            {

                // dladdr resolves names from .dynsym only — a statically

                // linked, non--rdynamic binary yields NO symbol for its own

                // functions. Fallback ladder: (1) `addr2line` against the

                // module's DEBUG symbols (Linux, when the tool is installed —

                // this recovers the real name, e.g. `cb:demo_button_click`,

                // even on static binaries); (2) the MODULE-RELATIVE offset

                // (`cb:+0x<offset>`), stable across runs of the same binary

                // (ASLR shifts the base, not the offset), so distinct

                // callbacks stay distinguishable and comparable per version.

                let mut info: libc::Dl_info = unsafe { core::mem::zeroed() };

                let rc = unsafe { libc::dladdr(fn_ptr as *const libc::c_void, &raw mut info) };

                if rc != 0 && !info.dli_sname.is_null() {

                    let name = unsafe { core::ffi::CStr::from_ptr(info.dli_sname) };

                    match name.to_str() {

                        Ok(sym) if !sym.is_empty() => {

                            Box::leak(format!("cb:{sym}").into_boxed_str())

                        }

                        _ => Box::leak(format!("cb:0x{fn_ptr:x}").into_boxed_str()),

                    }

                } else if rc != 0 && !info.dli_fbase.is_null() {

                    let offset = fn_ptr.wrapping_sub(info.dli_fbase as usize);

                    let module = if info.dli_fname.is_null() {

                        None

                    } else {

                        unsafe { core::ffi::CStr::from_ptr(info.dli_fname) }

                            .to_str()

                            .ok()

                            .map(str::to_owned)

                    };

                    match addr2line_name(module.as_deref(), offset, fn_ptr) {

                        Some(sym) => Box::leak(format!("cb:{sym}").into_boxed_str()),

                        None => Box::leak(format!("cb:+0x{offset:x}").into_boxed_str()),

                    }

                } else {

                    // dladdr failed outright: the raw address still separates

                    // one callback from another within this run.

                    Box::leak(format!("cb:0x{fn_ptr:x}").into_boxed_str())

                }

            }

            #[cfg(not(unix))]

            {

                Box::leak(format!("cb:0x{fn_ptr:x}").into_boxed_str())

            }

        };

        if let Ok(mut map) = cache.lock() {

            map.insert(fn_ptr, resolved);

        }

        resolved

    }

    /// DEBUG-SYMBOL fallback: asks the system's `addr2line` for the function

    /// name at `offset` inside `module` (Linux; other unixes rarely ship

    /// it). Recovers real names on statically linked binaries whose own

    /// functions are absent from `.dynsym` — exactly the case `dladdr`

    /// cannot answer.

    ///

    /// Runs AT MOST ONCE per distinct callback pointer (the leak-once cache

    /// above), so the subprocess cost — up to a few hundred ms the first

    /// time addr2line loads a big binary's DWARF — is a one-time price per

    /// callback, not per span. `AZ_PROBE_ADDR2LINE=0` disables it.

    ///

    /// PIE executables and shared objects map file offsets 1:1 to link-time

    /// addresses, so the module-relative offset is the right query; for a

    /// non-PIE main binary (fixed 0x400000 base) the RAW pointer is, so a

    /// failed first query retries with it.

    /// Probed ONCE per process (first resolution), then a flag test: systems

    /// without addr2line never spawn a second lookup attempt, and nothing

    /// here can fail loudly — "not available" just means the offset form.

    #[cfg(unix)]

    fn addr2line_available() -> bool {

        use std::sync::OnceLock;

        static AVAILABLE: OnceLock<bool> = OnceLock::new();

        *AVAILABLE.get_or_init(|| {

            std::process::Command::new("addr2line")

                .arg("--version")

                .stdout(std::process::Stdio::null())

                .stderr(std::process::Stdio::null())

                .status()

                .is_ok_and(|s| s.success())

        })

    }

    #[cfg(unix)]

    fn addr2line_name(module: Option<&str>, offset: usize, raw_ptr: usize) -> Option<String> {

        if !cfg!(target_os = "linux") {

            return None;

        }

        if std::env::var("AZ_PROBE_ADDR2LINE").is_ok_and(|v| v == "0") {

            return None;

        }

        if !addr2line_available() {

            return None;

        }

        let module: std::borrow::Cow<'_, str> = match module {

            Some(m) if !m.is_empty() => m.into(),

            _ => std::env::current_exe().ok()?.to_string_lossy().into_owned().into(),

        };

        let ask = |addr: usize| -> Option<String> {

            let out = std::process::Command::new("addr2line")

                .arg("-f") // function names…

                .arg("-C") // …demangled

                .arg("-i") // …with the full INLINE stack: a tiny callback's

                //            first instruction often belongs to an inlined

                //            callee (black_box, a getter), and the innermost

                //            frame would name THAT. The callback is the

                //            OUTERMOST frame — the last name in the output.

                .arg("-e")

                .arg(module.as_ref())

                .arg(format!("0x{addr:x}"))

                .output()

                .ok()?;

            if !out.status.success() {

                return None;

            }

            let text = String::from_utf8_lossy(&out.stdout);

            // Lines alternate name/location, innermost first; keep the last

            // usable NAME line (the outermost frame).

            let name = text

                .lines()

                .step_by(2)

                .map(str::trim)

                .filter(|n| !n.is_empty() && *n != "??")

                .last()?;

            Some(name.to_owned())

        };

        ask(offset).or_else(|| ask(raw_ptr))

    }

    pub(super) fn drop_events() {

        let _ = EVENTS.try_with(|cell| cell.borrow_mut().clear());

    }

    pub(super) fn peek_len() -> usize {

        EVENTS.try_with(|cell| cell.borrow().len()).unwrap_or(0)

    }

    pub(super) const fn enabled() -> bool {

        true

    }

}

#[cfg(any(

    not(feature = "probe"),

    target_family = "wasm",

    feature = "web_lift"

))]

mod imp {

    #[derive(Debug)]

    pub struct Span;

    impl Drop for Span {

        #[inline]

    }

    #[inline]

    #[inline]

    #[inline]

    #[inline]

    #[inline]

    #[inline]

    #[inline]

    #[inline]

    #[inline]

}

/// Drained probe event. `Vec<Event>` is what consumers walk to render

/// trace summaries; the order is the order events fired in.

#[derive(Copy, Debug, Clone)]

pub struct Event {

    pub name: &'static str,

    pub kind: EventKind,

    /// Nesting depth at the time the span OPENED (0 = outermost).

    ///

    /// Spans are emitted post-order carrying only a duration, so a

    /// consumer could report a phase's CUMULATIVE time but never its own:

    /// an outer `layout_formatting_context` reports the whole subtree it

    /// contains, and the totals happily exceed wall-clock. With depth, a

    /// consumer walking the post-order stream can subtract each span's

    /// immediate children and get SELF time — which is what actually

    /// names a hot phase. `Rss` samples carry the current depth too.

    pub depth: u16,

}

#[derive(Copy, Debug, Clone)]

pub enum EventKind {

    /// A timed scope's wall-clock duration.

    Span { dur_ns: u64 },

    /// A labelled RSS checkpoint.

    Rss { bytes: u64 },

}

/// Re-exported guard. Held by the caller of [`Probe::span`].

pub use imp::Span;

/// Probe API. All methods are no-ops without the `probe` feature.

#[derive(Copy, Clone, Debug)]

pub struct Probe {

    _no_construct: PhantomData<()>,

}

impl Probe {

    /// Open a timed span. The returned guard records its name + nanos

    /// on drop into the thread-local event buffer — but ONLY while

    /// recording is on (any `AZ_PROFILE` mode, or [`Probe::set_recording`]).

    /// With recording off the guard is inert and the call is one relaxed

    /// atomic load: safe to leave in hot per-node paths.

    #[inline]

    // const only in the no-`probe` stub config; enabled `imp::` calls are non-const

    #[allow(clippy::missing_const_for_fn)]

    /// Force event recording on/off, overriding the lazy `AZ_PROFILE`

    /// resolution. Tests use this (they assert on drained events without

    /// setting env vars); a debug server could too. Flipping mid-span only

    /// perturbs the saturating depth counter, never memory safety.

    #[inline]

    // const only in the no-`probe` stub config; enabled `imp::` calls are non-const

    #[allow(clippy::missing_const_for_fn)]

    /// Record an RSS checkpoint with the given label + byte count. The

    /// caller supplies the bytes (this module does not depend on

    /// platform RSS readers) so consumers can use whatever measurement

    /// helper they own.

    #[inline]

    // const only in the no-`probe` stub config; enabled `imp::` calls are non-const

    #[allow(clippy::missing_const_for_fn)]

    /// Drain the per-thread event buffer.

    #[inline]

    // const only in the no-`probe` stub config; enabled `imp::` calls are non-const

    #[allow(clippy::missing_const_for_fn)]

    /// The names of THIS thread's currently-open spans, outermost first,

    /// joined with `" > "` (empty when none). Maintained even with recording

    /// off — a crash report reads this as "what scope was the app in", and

    /// that diagnostic must not depend on `AZ_PROFILE`.

    #[inline]

    // const only in the no-`probe` stub config; enabled `imp::` calls are non-const

    #[allow(clippy::missing_const_for_fn)]

    /// A timed span NAMED AFTER the function the pointer points at,

    /// resolved through the dynamic linker (`dladdr`) and cached forever:

    /// an `extern "C"` app callback like `my_button_click` becomes span

    /// `cb:my_button_click`, so the per-phase histogram answers

    /// "`my_button_click` takes 0.2 ms on 1.5.0, took 0.1 ms on 1.4.3".

    ///

    /// Resolution runs ONCE per distinct pointer (a leak-once cache bounded

    /// by the number of distinct callbacks); every later call is one map

    /// lookup. When the symbol is unresolvable (static non-`-rdynamic`

    /// binaries keep their own functions out of `.dynsym`), the fallback

    /// ladder is: `addr2line` against the module's debug symbols (Linux,

    /// when installed — recovers the real name; `AZ_PROBE_ADDR2LINE=0`

    /// disables), then the module-relative offset `cb:+0x<offset>` — stable

    /// across runs of the same binary, so distinct callbacks remain

    /// distinguishable and per-version comparisons still work; `cb:0x<addr>`

    /// is the last resort when `dladdr` fails entirely.

    #[inline]

    // const only in the no-`probe` stub config; enabled `imp::` calls are non-const

    #[allow(clippy::missing_const_for_fn)]

    /// Discard the per-thread event buffer without allocating a `Vec` to

    /// hand back. Used by long-running harnesses (e.g. `AZ_E2E_TEST`) that

    /// want to prevent the thread-local buffer from inflating RSS during

    /// thousands of layout passes without actually needing the events.

    #[inline]

    // const only in the no-`probe` stub config; enabled `imp::` calls are non-const

    #[allow(clippy::missing_const_for_fn)]

    /// Current number of events in the per-thread buffer. Cheap to call.

    #[inline]

    // const only in the no-`probe` stub config; enabled `imp::` calls are non-const

    #[allow(clippy::missing_const_for_fn)]

    /// Whether the `probe` feature is compiled in.

    #[inline]

    // const only in the no-`probe` stub config; enabled `imp::` calls are non-const

    #[allow(clippy::missing_const_for_fn)]

}

/// Same monotonic clock used by `font::parsed::monotonic_now_nanos` for

/// LRU stamping. Re-exported here so any caller that wants raw nanos

/// without going through a span guard has one source of truth.

#[inline]

#[allow(clippy::cast_possible_truncation)] // bounded graphics/coord/font/fixed-point/debug-marker cast

    use std::sync::OnceLock;

    use std::time::Instant;

    static LAUNCH: OnceLock<Instant> = OnceLock::new();

/// Format drained probe events as a per-phase timing table to stderr.

///

/// Groups `EventKind::Span` by name and prints count / total / avg / p99 /

/// max in µs. `EventKind::Rss` checkpoints print in wall-clock order with

/// deltas so allocator purges are visible.

///

/// Sorted by total-ns descending so the slowest phase is on top — ideal

/// for spotting which phase spiked during a stuttering frame.

///

/// Called by `AZ_PROFILE=cpu` dumps (both initial layout and relayout),

/// and also by external consumers like `servo-shot --azul-trace`.

#[allow(clippy::cast_possible_truncation, clippy::cast_precision_loss)] // bounded graphics/coord/font/fixed-point/debug-marker cast

/// # Panics

///

/// Panics if the collected timing-sample list is empty.

    use std::collections::BTreeMap;

        }

    }

        "phase", "n", "total(µs)", "avg(µs)", "p99(µs)", "max(µs)"

    );

                    } else {

                    }

                lbl,

                delta

            );

        }

/// Convenience wrapper: sample the process's **current** resident set

/// (not peak) via `task_info` on macOS / `/proc/self/statm` on Linux and

/// push it into the probe event buffer under the given label.

///

/// Using current RSS (not `getrusage.ru_maxrss`) is essential so that

/// allocator purges are visible — peak RSS only moves up. Name kept as

/// `sample_peak_rss` for backwards compatibility with existing

/// checkpoint labels; semantically it is "sample current".

#[inline]

// const only without the `probe` feature; enabled path calls non-const RSS readers

#[allow(clippy::missing_const_for_fn)]

    // [WEB-LIFT 2026-06-11] also no-op under web_lift: current_rss_bytes/

    // peak_rss_bytes_self are mach syscalls (task_info/getrusage) —

    // out-of-image and unliftable. See the `imp` cfg note above.

    #[cfg(all(feature = "probe", not(feature = "web_lift")))]

    {

        // Self-measurement accounting: each sample reads /proc (or the mach

        // equivalent) — hundreds of µs each, ×10 checkpoints per pass. This

        // span makes the PROFILER'S OWN COST a line in its report instead of

        // silently inflating solver3_layout_document's self-time (~5 ms of

        // "unattributed" turned out to be largely this).

        let _p = Probe::span("probe_rss_sample_cost");

        let (current, _virt) = current_rss_bytes();

        let bytes = if current != 0 { current } else { peak_rss_bytes_self() };

        Probe::sample_rss(label, bytes);

    }

    #[cfg(any(not(feature = "probe"), feature = "web_lift"))]

#[cfg(feature = "probe")]

#[must_use] pub fn peak_rss_bytes_pub() -> u64 { peak_rss_bytes_self() }

#[cfg(feature = "probe")]

fn peak_rss_bytes_self() -> u64 {

    #[cfg(unix)]

    unsafe {

        let mut ru: libc::rusage = core::mem::zeroed();

        if libc::getrusage(libc::RUSAGE_SELF, &raw mut ru) != 0 {

            return 0;

        }

        let raw = ru.ru_maxrss as u64;

        if cfg!(target_os = "macos") { raw } else { raw.saturating_mul(1024) }

    }

    // Windows has no getrusage; `PeakWorkingSetSize` is the direct equivalent

    // of `ru_maxrss` and is already in bytes.

    #[cfg(all(target_os = "windows", not(miri)))]

    {

        windows_memory_counters().map_or(0, |c| c.peak_working_set)

    }

    #[cfg(not(any(unix, all(target_os = "windows", not(miri)))))]

    {

        0

    }

}

/// Ask the active global allocator to return freed pages to the OS.

///

/// - With `allocator_mimalloc` feature: calls `mi_collect(true)`, which

///   aggressively returns pages (matches `az_purge_allocator` in azul-dll).

/// - With `allocator_jemalloc` feature: calls `mallctl("arena.0.purge")`.

/// - Otherwise on macOS: falls back to `malloc_zone_pressure_relief`

///   which drains the system zone (no-op when a third-party allocator

///   is the global one — hence the explicit feature flags above).

/// - Other platforms with default allocator: no-op.

///

/// Call after major allocations are freed (e.g. after a layout pass).

#[inline]

// const only on the default-allocator no-op path (e.g. Linux); the mimalloc /

// jemalloc / macOS `malloc_zone_pressure_relief` bodies call non-const fns

#[allow(clippy::missing_const_for_fn)]

    #[cfg(feature = "allocator_mimalloc")]

    {

        // Aggressive purge — returns arenas to the OS when possible.

        unsafe {

            libmimalloc_sys::mi_collect(true);

        }

        static PURGE_TRACE: std::sync::OnceLock<bool> = std::sync::OnceLock::new();

        if *PURGE_TRACE.get_or_init(azul_core::profile::memory_enabled) {

            let (rss, _) = current_rss_bytes();

            eprintln!("[PURGE] mi_collect(true) called — current rss={:.2} MiB", rss as f64 / 1048576.0);

        }

        return;

    }

    #[cfg(feature = "allocator_jemalloc")]

    {

        // Purge all arenas. `arena.<i>.purge` with i = MALLCTL_ARENAS_ALL.

        unsafe {

            let _ = tikv_jemalloc_sys::mallctl(

                b"arena.4096.purge\0".as_ptr() as *const _,

                core::ptr::null_mut(),

                core::ptr::null_mut(),

                core::ptr::null_mut(),

                0,

            );

        }

        return;

    }

    #[cfg(all(target_os = "macos", not(miri), not(any(feature = "allocator_mimalloc", feature = "allocator_jemalloc"))))]

    {

        extern "C" {

            fn malloc_zone_pressure_relief(zone: *mut core::ffi::c_void, goal: usize) -> usize;

        }

        unsafe {

            malloc_zone_pressure_relief(core::ptr::null_mut(), 0);

        }

    }

    // glibc's equivalent of malloc_zone_pressure_relief. Without this the

    // Linux default-allocator path was the "no-op" the doc comment describes,

    // so a purge-then-measure sequence could never show pages coming back.

    #[cfg(all(

        target_os = "linux",

        target_env = "gnu",

        not(miri),

        not(any(feature = "allocator_mimalloc", feature = "allocator_jemalloc"))

    ))]

    {

        // Declared here rather than via `libc::malloc_trim`: this function is

        // NOT gated on the `probe` feature (that is what pulls in libc), and

        // the macOS arm above declares `malloc_zone_pressure_relief` the same

        // way for the same reason.

        extern "C" {

            fn malloc_trim(pad: usize) -> core::ffi::c_int;

        }

    }

/// Sample the process's "real" memory footprint (not peak).

/// Returns (`footprint_bytes`, `virtual_bytes`). On macOS this is

/// `phys_footprint` from `TASK_VM_INFO` — matches Activity Monitor

/// "Memory" and `vmmap`'s "Physical footprint" line, and excludes

/// shared library text pages that would otherwise inflate RSS

/// without costing the process anything uniquely. On Linux this

/// falls back to `/proc/self/statm` resident size (no direct

/// equivalent; the shared-lib inflation is much smaller there).

/// More useful than `getrusage.ru_maxrss` which only moves upward.

#[cfg(feature = "probe")]

#[must_use] pub fn current_rss_bytes() -> (u64, u64) {

    // Miri cannot call the mach `task_info` foreign function; memory profiling

    // is meaningless under Miri anyway, so report zero.

    #[cfg(miri)]

    return (0, 0);

    #[cfg(all(target_os = "macos", not(miri)))]

    {

        // Prefer phys_footprint (TASK_VM_INFO). Fall back to

        // resident_size (MACH_TASK_BASIC_INFO) if the bigger struct

        // isn't populated for some reason.

        let pf = phys_footprint_bytes();

        #[repr(C)]

        struct MachTaskBasicInfo {

            virtual_size: u64,

            resident_size: u64,

            resident_size_max: u64,

            user_time: [u32; 2],

            system_time: [u32; 2],

            policy: i32,

            suspend_count: i32,

        }

        const MACH_TASK_BASIC_INFO: u32 = 20;

        extern "C" {

            fn mach_task_self() -> u32;

            fn task_info(

                target: u32, flavor: u32,

                info: *mut core::ffi::c_void, count: *mut u32,

            ) -> i32;

        }

        unsafe {

            let mut info: MachTaskBasicInfo = core::mem::zeroed();

            let mut count = (core::mem::size_of::<MachTaskBasicInfo>() / 4) as u32;

            let kr = task_info(

                mach_task_self(),

                MACH_TASK_BASIC_INFO,

                &mut info as *mut _ as *mut core::ffi::c_void,

                &mut count,

            );

            if kr == 0 {

                let rss = if pf != 0 { pf } else { info.resident_size };

                (rss, info.virtual_size)

            } else {

                (pf, 0)

            }

        }

    }

    // The doc comment above has always promised a `/proc/self/statm` fallback

    // on Linux. Until 2026-07-29 this arm returned (0, 0) for every non-macOS

    // target, so `sample_peak_rss` silently fell back to ru_maxrss (peak-only,

    // never decreases) and every allocator-purge measurement on Linux read as

    // "no memory was returned".

    #[cfg(all(target_os = "linux", not(miri)))]

    {

        // statm fields are in pages: size resident shared text lib data dt.

        let Ok(statm) = std::fs::read_to_string("/proc/self/statm") else {

            return (0, 0);

        };

        let mut it = statm.split_ascii_whitespace();

        let size: u64 = it.next().and_then(|v| v.parse().ok()).unwrap_or(0);

        let resident: u64 = it.next().and_then(|v| v.parse().ok()).unwrap_or(0);

        let page = unsafe { libc::sysconf(libc::_SC_PAGESIZE) };

        let page = if page > 0 { page as u64 } else { 4096 };

        (

            resident.saturating_mul(page),

            size.saturating_mul(page),

        )

    }

    // Windows: `K32GetProcessMemoryInfo` is the documented equivalent.

    // WorkingSetSize is the RSS analogue (what Task Manager calls "Memory

    // (active private working set)"'s superset), PrivateUsage is the commit

    // charge — the closest thing to the "virtual" slot the other arms fill.

    //

    // Until this arm existed every Windows build reported (0, 0), which made

    // "startup RSS after an update" — the one metric the telemetry rollout

    // gate is built on — silently meaningless on the majority desktop

    // platform (`core/src/profile.rs` documented this as a known hole).

    #[cfg(all(target_os = "windows", not(miri)))]

    {

        windows_memory_counters().map_or((0, 0), |c| (c.working_set, c.private_usage))

    }

    #[cfg(not(any(

        target_os = "macos",

        all(target_os = "linux", not(miri)),

        all(target_os = "windows", not(miri))

    )))]

    { (0, 0) }

}

/// Snapshot of `PROCESS_MEMORY_COUNTERS_EX`, in bytes.

#[cfg(all(feature = "probe", target_os = "windows", not(miri)))]

pub(crate) struct WindowsMemoryCounters {

    /// `WorkingSetSize` — resident bytes; the RSS analogue.

    pub working_set: u64,

    /// `PeakWorkingSetSize` — high-water mark of the above.

    pub peak_working_set: u64,

    /// `PrivateUsage` — commit charge (private bytes).

    pub private_usage: u64,

}

/// Reads `PROCESS_MEMORY_COUNTERS_EX` for the current process.

///

/// `K32GetProcessMemoryInfo` lives directly in `kernel32.dll` (Windows 7+),

/// so this needs no `psapi.dll` import library and no `windows-sys`

/// dependency — matching how the macOS arm above hand-declares `task_info`.

///

/// Returns `None` if the call fails.

#[cfg(all(feature = "probe", target_os = "windows", not(miri)))]

pub(crate) fn windows_memory_counters() -> Option<WindowsMemoryCounters> {

    // Layout per the Win32 header. On 64-bit the two leading DWORDs pack into

    // the first 8 bytes with no tail padding before the first SIZE_T, so the

    // struct maps 1:1; `cb` is validated by the callee against what we pass.

    #[repr(C)]

    struct ProcessMemoryCountersEx {

        cb: u32,

        page_fault_count: u32,

        peak_working_set_size: usize,

        working_set_size: usize,

        quota_peak_paged_pool_usage: usize,

        quota_paged_pool_usage: usize,

        quota_peak_non_paged_pool_usage: usize,

        quota_non_paged_pool_usage: usize,

        pagefile_usage: usize,

        peak_pagefile_usage: usize,

        private_usage: usize,

    }

    #[link(name = "kernel32")]

    extern "system" {

        fn GetCurrentProcess() -> *mut core::ffi::c_void;

        fn K32GetProcessMemoryInfo(

            process: *mut core::ffi::c_void,

            counters: *mut ProcessMemoryCountersEx,

            cb: u32,

        ) -> i32;

    }

    unsafe {

        let mut counters: ProcessMemoryCountersEx = core::mem::zeroed();

        let cb = u32::try_from(core::mem::size_of::<ProcessMemoryCountersEx>()).ok()?;

        counters.cb = cb;

        if K32GetProcessMemoryInfo(GetCurrentProcess(), &mut counters, cb) == 0 {

            return None;

        }

        Some(WindowsMemoryCounters {

            working_set: counters.working_set_size as u64,

            peak_working_set: counters.peak_working_set_size as u64,

            private_usage: counters.private_usage as u64,

        })

    }

}

/// Heap bytes currently held by the libc allocator (`mstats.bytes_used`).

///

/// Unlike RSS, this is what *Rust* allocations plus anything else going

/// through the default malloc zone is actually holding — mmap regions

/// for thread stacks, GL buffers, file-mapped fonts, etc. are NOT counted.

/// A leak that shows up here points to a genuine heap retention (an Arc

/// chain never dropped, a Vec never shrunk, a `Box<T>` forgotten).

///

/// - **macOS**: `mstats().bytes_used`.

/// - **Linux/glibc**: `mallinfo2().uordblks` — the same quantity, total

///   bytes currently handed out by malloc. Resolved with `dlsym` rather

///   than linked directly, because `mallinfo2` is glibc 2.33+ and a hard

///   link reference would break the build on older distros for the sake of

///   an opt-in diagnostic. Falls back to the `c_int`-based `mallinfo()`,

///   which is exact below 2 GiB of live heap.

/// - Everything else: 0.

///

/// CAVEAT (Linux): glibc accounts the **main arena only**. Allocations made

/// on other threads' arenas — and azul spawns font scout/builder threads —

/// are invisible here. A rising number is proof of a leak; a flat one is

/// not proof of its absence. Cross-check with [`current_rss_bytes`].

///

/// This returned 0 on every non-macOS target until 2026-07-29, which is the

/// only reason `dll/tests/leak_regression.rs` is `cfg(target_os = "macos")`:

/// the leak was never macOS-specific, the *instrument* was.

#[cfg(feature = "probe")]

pub fn malloc_heap_bytes() -> u64 {

    #[cfg(target_os = "macos")]

    {

        #[repr(C)]

        struct Mstats {

            bytes_total: usize,

            chunks_used: usize,

            bytes_used: usize,

            chunks_free: usize,

            bytes_free: usize,

        }

        extern "C" {

            fn mstats() -> Mstats;

        }

        unsafe { mstats().bytes_used as u64 }

    }

    #[cfg(all(target_os = "linux", target_env = "gnu", not(miri)))]

    {

        type Mallinfo2Fn = unsafe extern "C" fn() -> libc::mallinfo2;

        static MALLINFO2: std::sync::OnceLock<Option<Mallinfo2Fn>> =

            std::sync::OnceLock::new();

        let resolved = MALLINFO2.get_or_init(|| unsafe {

            // RTLD_DEFAULT is NULL on glibc; the libc crate doesn't define

            // the constant for linux-gnu, so spell it out.

            let sym = libc::dlsym(

                core::ptr::null_mut(),

                c"mallinfo2".as_ptr(),

            );

            if sym.is_null() {

                None

            } else {

                Some(core::mem::transmute::<

                    *mut core::ffi::c_void,

                    Mallinfo2Fn,

                >(sym))

            }

        });

        match resolved {

            Some(mallinfo2) => unsafe { mallinfo2().uordblks as u64 },

            // Pre-2.33 glibc. `uordblks` is a signed int that wraps past

            // 2 GiB; clamp rather than report a negative byte count.

            None => unsafe { libc::mallinfo().uordblks.max(0) as u64 },

        }

    }

    #[cfg(not(any(

        target_os = "macos",

        all(target_os = "linux", target_env = "gnu", not(miri))

    )))]

    { 0 }

}

/// Sample the Mach `phys_footprint` — the memory metric Activity

/// Monitor and `vmmap`'s "Physical footprint" line display. Unlike

/// `resident_size`, this excludes shared library text pages and

/// other kernel-mapped regions that inflate the traditional RSS

/// number without actually costing the process anything. For a

/// short-lived headless render this is a much more honest figure:

/// on a ~20 MiB `ru_maxrss` run, `phys_footprint` is typically ~8 MiB.

/// Returns 0 on non-macOS or if the Mach call fails.

///

/// There's no direct "peak `phys_footprint`" field; track the max

/// across calls in application code if you need it.

#[cfg(feature = "probe")]

// NOT const: the macOS branch calls mach task_info — const only held on

// targets where that branch compiles out (E0015 on aarch64-apple-darwin).

#[allow(clippy::missing_const_for_fn)]

#[must_use] pub fn phys_footprint_bytes() -> u64 {

    // Miri cannot call the mach `task_info` foreign function.

    #[cfg(miri)]

    return 0;

    #[cfg(all(target_os = "macos", not(miri)))]

    {

        // TASK_VM_INFO = 22; the struct is large (~88 u32 counts ≈ 352 B)

        // and phys_footprint lives near the end, so we have to read the

        // whole thing. Layout is from osfmk/mach/task_info.h.

        #[repr(C)]

        struct TaskVmInfo {

            virtual_size: u64,

            region_count: u32,

            page_size: u32,

            resident_size: u64,

            resident_size_peak: u64,

            device: u64,

            device_peak: u64,

            internal: u64,

            internal_peak: u64,

            external: u64,

            external_peak: u64,

            reusable: u64,

            reusable_peak: u64,

            purgeable_volatile_pmap: u64,

            purgeable_volatile_resident: u64,

            purgeable_volatile_virtual: u64,

            compressed: u64,

            compressed_peak: u64,

            compressed_lifetime: u64,

            phys_footprint: u64,

            // there are more fields after this, but we don't need them

            _rest: [u64; 12],

        }

        const TASK_VM_INFO: u32 = 22;

        extern "C" {

            fn mach_task_self() -> u32;

            fn task_info(

                target: u32, flavor: u32,

                info: *mut core::ffi::c_void, count: *mut u32,

            ) -> i32;

        }

        unsafe {

            let mut info: TaskVmInfo = core::mem::zeroed();

            let mut count = (core::mem::size_of::<TaskVmInfo>() / 4) as u32;

            let kr = task_info(

                mach_task_self(),

                TASK_VM_INFO,

                &mut info as *mut _ as *mut core::ffi::c_void,

                &mut count,

            );

            if kr == 0 { info.phys_footprint } else { 0 }

        }

    }

    #[cfg(not(target_os = "macos"))]

    { 0 }

}

/// Background sampler for peak `phys_footprint`. Spawns a thread that

/// polls `phys_footprint_bytes()` every ~2 ms and updates a shared

/// atomic. The kernel does not expose a direct "peak `phys_footprint`"

/// — unlike `resident_size_peak` in `TASK_VM_INFO` — so polling is

/// the only way to catch mid-phase transients that are `MADV_FREE`'d

/// before the next explicit sample point.

///

/// Not started by default; call `start_peak_sampler()` once at

/// process init if you want peak tracking. Overhead is negligible

/// (~1-5 µs per poll on macOS, 500 Hz → <0.25% CPU of one core).

/// `peak_phys_footprint_seen()` reads the current high-water mark.

#[cfg(feature = "probe")]

// NOT const: the macOS branch spawns the sampler thread (E0015 there).

#[allow(clippy::missing_const_for_fn)]

pub fn start_peak_sampler() {

    #[cfg(target_os = "macos")]

    {

        use std::sync::atomic::Ordering;

        // Idempotent — only spawns once.

        static STARTED: std::sync::atomic::AtomicBool =

            std::sync::atomic::AtomicBool::new(false);

        if STARTED.swap(true, Ordering::AcqRel) {

            return;

        }

        std::thread::Builder::new()

            .name("azul-peak-sampler".to_string())

            .spawn(|| loop {

                let now = phys_footprint_bytes();

                let prev = PEAK_PHYS_FOOTPRINT.load(Ordering::Relaxed);

                if now > prev {

                    PEAK_PHYS_FOOTPRINT.store(now, Ordering::Relaxed);

                }

                std::thread::sleep(std::time::Duration::from_micros(250));

            })

            .ok();

    }

}

#[cfg(feature = "probe")]

static PEAK_PHYS_FOOTPRINT: std::sync::atomic::AtomicU64 =

    std::sync::atomic::AtomicU64::new(0);

/// Read the peak `phys_footprint` seen by the background sampler.

/// Returns 0 if `start_peak_sampler` was never called.

#[cfg(feature = "probe")]

pub fn peak_phys_footprint_seen() -> u64 {

    PEAK_PHYS_FOOTPRINT.load(std::sync::atomic::Ordering::Relaxed)

}

/// Reset the global peak high-water mark to the current `phys_footprint`.

/// Paired with `peak_phys_footprint_seen()` so a caller can record

/// "peak during phase X" — call `reset_peak()` at phase entry, then

/// `peak_phys_footprint_seen()` at phase exit. The 500 Hz background

/// sampler runs continuously either way.

#[cfg(feature = "probe")]

pub fn reset_peak() {

    let now = phys_footprint_bytes();

    PEAK_PHYS_FOOTPRINT.store(now, std::sync::atomic::Ordering::Relaxed);

}

/// Record a phase's peak footprint into the probe event stream.

/// Call at phase exit after `reset_peak()` at phase entry. Emits an

/// RSS-kind event with `bytes = peak seen during phase`.

#[cfg(feature = "probe")]

#[inline]

pub fn sample_phase_peak(label: &'static str) {

    let peak = PEAK_PHYS_FOOTPRINT.load(std::sync::atomic::Ordering::Relaxed);

    Probe::sample_rss(label, peak);

}

#[cfg(not(feature = "probe"))]

#[inline]

#[cfg(not(feature = "probe"))]

#[inline]

#[cfg(not(feature = "probe"))]

#[inline]

/// Emit one `{"ev":"phase","label":L,"heap":N,"call":C}` line to the

/// JSONL file named by `AZ_PROFILE_OUT=<path>`. Only fires when

/// `AZ_PROFILE=heap,jsonl` is set *and* the path is given.

///

/// Each call auto-increments a monotonic `call` id so downstream

/// analyzers can group phases belonging to a single `regenerate_layout`

/// invocation.

///

/// `label` convention: `start` at function entry; `<step>` after each

/// phase completes; `end` at function exit. Heap Δ between adjacent

/// labels within the same call-id is the bytes retained by that phase.

///

/// Zero overhead when flags aren't set (two atomic loads). Zero overhead

/// when the `probe` feature is off (no-op stub).

#[cfg(feature = "probe")]

pub fn emit_phase_heap(label: &str) {

    use std::io::Write;

    if !heap_jsonl_enabled() { return; }

    let Some(p) = azul_core::profile::out_path() else { return };

    static CALL_ID: std::sync::atomic::AtomicU64 =

        std::sync::atomic::AtomicU64::new(0);

    // Auto-increment on every "start" label; "end" and intermediates reuse

    // the current id so all phases in one regenerate_layout invocation share

    // a call number.

    static CURRENT_CALL: std::sync::atomic::AtomicU64 =

        std::sync::atomic::AtomicU64::new(0);

    let call_id = if label == "start" {

        let next = CALL_ID.fetch_add(1, std::sync::atomic::Ordering::Relaxed) + 1;

        CURRENT_CALL.store(next, std::sync::atomic::Ordering::Relaxed);

        next

    } else {

        CURRENT_CALL.load(std::sync::atomic::Ordering::Relaxed)

    };

    let heap = malloc_heap_bytes();

    if let Ok(mut f) = std::fs::OpenOptions::new()

        .create(true)

        .append(true)

        .open(p)

    {

        drop(writeln!(

            f,

            r#"{{"ev":"phase","call":{call_id},"label":"{label}","heap":{heap}}}"#

        ));

    }

}

#[cfg(not(feature = "probe"))]

#[inline]

/// Like [`emit_phase_heap`] but attaches a numeric payload (e.g., a cache

/// size) to the JSONL record under the `"extra"` field.

///

/// Gated behind `AZ_PROFILE=heap,jsonl,detail` — the `detail` token opts

/// in to fine-grained probes that produce extra per-step records (one

/// per intermediate step inside a phase). Without `detail`, only the

/// coarser phase probes from [`emit_phase_heap`] fire.

#[cfg(feature = "probe")]

pub fn emit_phase_heap_extra(label: &str, extra: u64) {

    use std::io::Write;

    if !heap_jsonl_enabled() { return; }

    if !azul_core::profile::detail_enabled() { return; }

    let Some(p) = azul_core::profile::out_path() else { return };

    let heap = malloc_heap_bytes();

    if let Ok(mut f) = std::fs::OpenOptions::new()

        .create(true)

        .append(true)

        .open(p)

    {

        drop(writeln!(

            f,

            r#"{{"ev":"phase","call":0,"label":"{label}","heap":{heap},"extra":{extra}}}"#

        ));

    }

}

#[cfg(not(feature = "probe"))]

#[inline]

/// Both `heap` and `jsonl` tokens active in `AZ_PROFILE` — the combination

/// that enables JSONL heap-probe emission. Either alone is a no-op.

#[cfg(feature = "probe")]

#[inline]

fn heap_jsonl_enabled() -> bool {

    let f = azul_core::profile::flags();

    f.heap && f.jsonl

}

/// Returns true iff `AZ_PROFILE=detail` is active. Kept as a public

/// re-export so downstream crates can write `azul_layout::probe::detail_enabled()`

/// without pulling in `azul_core::profile` directly.

#[cfg(feature = "probe")]

#[inline]

#[must_use] pub fn detail_enabled() -> bool {

    azul_core::profile::detail_enabled()

}

#[cfg(not(feature = "probe"))]

#[inline]

#[cfg(test)]

#[allow(let_underscore_drop, clippy::too_many_lines)]

mod autotest_generated {

    use super::*;

    /// Build a `&'static str` with arbitrary (possibly hostile) contents.

    /// Leaks — fine for a test binary, and the only way to feed adversarial

    /// text into the `&'static str` APIs (`Probe::span`, `sample_rss`, ...).

    fn leak(s: String) -> &'static str {

        Box::leak(s.into_boxed_str())

    }

    /// Clear this thread's event buffer so a test's assertions hold even when

    /// the suite runs with `--test-threads=1` (all tests on one thread share

    /// the same thread-local `EVENTS`). Also force recording ON: these tests

    /// assert on drained events, and without `AZ_PROFILE` in the environment

    /// the lazy gate would otherwise leave every span inert.

    fn reset() {

        Probe::set_recording(true);

        Probe::drop_events();

        assert_eq!(Probe::peek_len(), 0, "drop_events must leave an empty buffer");

    }

    fn span_ns(ev: &Event) -> Option<u64> {

        match ev.kind {

            EventKind::Span { dur_ns } => Some(dur_ns),

            EventKind::Rss { .. } => None,

        }

    }

    fn rss_bytes(ev: &Event) -> Option<u64> {

        match ev.kind {

            EventKind::Rss { bytes } => Some(bytes),

            EventKind::Span { .. } => None,

        }

    }

    // ---------------------------------------------------------------

    // enabled() / cfg invariants

    // ---------------------------------------------------------------

    #[test]

    fn enabled_matches_the_compiled_imp() {

        // `Probe::enabled()` is the single runtime source of truth for

        // "events actually get buffered"; it must track the cfg that selects

        // the real `imp` (probe on, not wasm, not web_lift).

        let expected = cfg!(all(

            feature = "probe",

            not(target_family = "wasm"),

            not(feature = "web_lift")

        ));

        assert_eq!(Probe::enabled(), expected);

        assert_eq!(imp::enabled(), expected);

    }

    #[test]

    fn enabled_is_pure_and_idempotent() {

        let first = Probe::enabled();

        for _ in 0..1000 {

            assert_eq!(Probe::enabled(), first);

        }

    }

    // ---------------------------------------------------------------

    // span / drain round-trips

    // ---------------------------------------------------------------

    #[test]

    fn span_round_trips_name_through_drain() {

        reset();

        {

            let _g = Probe::span("autotest_span_round_trip");

        }

        let events = Probe::drain();

        if Probe::enabled() {

            assert_eq!(events.len(), 1);

            assert_eq!(events[0].name, "autotest_span_round_trip");

            assert!(span_ns(&events[0]).is_some(), "span guard must emit EventKind::Span");

        } else {

            assert!(events.is_empty(), "no-op imp must never buffer events");