stackler 0.1.0

A lightweight, always-on stack telemetry library that requires no instrumentation.
Documentation
#![cfg(all(feature = "std", feature = "watermark"))]

//! A workload of known stack depth, checked against what `stackler` says about
//! it from the outside.
//!
//! NOTE: these tests share the process-wide registry and reset it, so they MUST
//! run single-threaded (`-- --test-threads 1`); parallel runs are flaky.

use std::{
    collections::HashMap,
    hint::black_box,
    sync::{Arc, Barrier, mpsc},
    thread,
};

/// How many worker threads to run.
const THREADS: usize = 8;
/// How much stack each level of recursion uses, at the very least.
const FRAME: usize = 8 * 1024;
/// The stack size the workers are given, comfortably more than they need.
const STACK_SIZE: usize = 4 * 1024 * 1024;

/// Recurses `levels` deep, using at least `FRAME` bytes per level.
///
/// `#[inline(never)]` keeps every level in a frame of its own; an inlined
/// recursion would reserve its stack up front, where no watermark can see it
/// happen.
#[inline(never)]
fn recurse(levels: usize) {
    let mut frame = [0u8; FRAME];
    black_box(&mut frame);

    if levels > 0 {
        recurse(levels - 1);
    }
}

#[test]
fn threads_of_known_depth() {
    // A megabyte is deep enough for the deepest worker below.
    stackler::Stackler::new().paint_depth(1024 * 1024).install();
    stackler::reset();

    let baseline = stackler::stats();
    let barrier = Arc::new(Barrier::new(THREADS + 1));
    let (tx, rx) = mpsc::channel();

    let workers: Vec<_> = (0..THREADS)
        .map(|i| {
            let barrier = Arc::clone(&barrier);
            let tx = tx.clone();

            thread::Builder::new()
                .stack_size(STACK_SIZE)
                .spawn(move || {
                    // Each worker goes to a different depth.
                    let levels = i + 1;
                    let expected = levels * FRAME;

                    assert!(stackler::attach());
                    let base = stackler::current_stack().unwrap().base();

                    // What the thread measures about itself...
                    let (_, peak) = stackler::measure_peak(|| recurse(levels));
                    let peak = peak.unwrap();
                    assert!(peak.bytes() >= expected, "{i}: {peak:?} < {expected}");
                    assert!(!peak.is_saturated(), "{i}: {peak:?}");

                    tx.send((base, expected)).unwrap();

                    // ... is also visible from outside, from here on. The thread
                    // does not report anything else.
                    barrier.wait();
                })
                .unwrap()
        })
        .collect();
    drop(tx);

    let expectations: HashMap<usize, usize> = rx.iter().take(THREADS).collect();
    assert_eq!(expectations.len(), THREADS);

    // Read every worker's watermark without their cooperation.
    stackler::poll_all();

    let threads = stackler::threads();
    let stats = stackler::stats();

    let mut matched = 0;
    let mut peak_max = 0;
    let mut reserved_sum = 0;
    for thread in &threads {
        reserved_sum += thread.size as u64;
        peak_max = peak_max.max(thread.peak);

        if let Some(expected) = expectations.get(&thread.base) {
            matched += 1;
            assert!(
                thread.peak >= *expected,
                "{thread:?}: peak below the {expected} bytes it recursed through"
            );
            // The recursion is bounded, and so is the reading.
            assert!(thread.peak < *expected + 64 * 1024, "{thread:?}");
            // A worker reserves what it was given, give or take the guard page.
            assert!(thread.size.abs_diff(STACK_SIZE) <= 4096, "{thread:?}");
            assert!(!thread.saturated, "{thread:?}");
        }
    }
    assert_eq!(matched, THREADS, "every worker is in the registry");

    // The aggregates agree with the per-thread snapshots they are built from.
    assert_eq!(stats.threads_live, threads.len() as u64);
    assert_eq!(stats.threads_live, baseline.threads_live + THREADS as u64);
    assert_eq!(stats.threads_seen, baseline.threads_seen + THREADS as u64);
    assert_eq!(stats.reserved_sum, reserved_sum);
    assert_eq!(stats.peak_max, peak_max);
    assert_eq!(stats.untracked, 0);
    assert_eq!(stats.saturated_count, 0);

    // The deepest worker recursed through THREADS levels.
    assert!(stats.peak_max >= THREADS * FRAME);
    // Reserved space dwarfs what is used, which is the point of measuring it.
    assert!(stats.reserved_sum > stats.peak_sum);
    assert_eq!(stats.waste(), stats.reserved_sum - stats.peak_sum);
    assert!(stats.utilization().unwrap() < 0.5);

    barrier.wait();
    for worker in workers {
        worker.join().unwrap();
    }

    // The threads are gone; what they recorded is not.
    let after = stackler::stats();
    assert_eq!(after.threads_live, baseline.threads_live);
    assert_eq!(after.threads_seen, stats.threads_seen);
    assert_eq!(after.peak_max, stats.peak_max);
    assert!(after.reserved_sum < stats.reserved_sum);
}

#[test]
fn slots_are_recycled() {
    stackler::reset();
    let baseline = stackler::stats().threads_live;

    // More threads than there are slots, a few at a time: every one of them has
    // to be tracked, which means slots have to come back.
    for _ in 0..(stackler::MAX_THREADS / 4 + 3) {
        let batch: Vec<_> = (0..4)
            .map(|_| thread::spawn(|| assert!(stackler::attach())))
            .collect();
        for thread in batch {
            thread.join().unwrap();
        }
    }

    let stats = stackler::stats();
    assert_eq!(stats.threads_live, baseline);
    assert!(stats.threads_seen > stackler::MAX_THREADS as u64);
    assert_eq!(stats.untracked, 0, "a recycled slot was not handed back");
}

#[test]
fn registry_reports_what_it_cannot_track() {
    stackler::attach();
    stackler::reset();
    let baseline = stackler::stats().threads_live;

    // Fill every slot, then ask for a few more.
    let overflow = stackler::MAX_THREADS + 8;
    let barrier = Arc::new(Barrier::new(overflow + 1));
    let hold = Arc::new(Barrier::new(overflow + 1));
    let (tx, rx) = mpsc::channel();

    let squatters: Vec<_> = (0..overflow)
        .map(|_| {
            let (barrier, hold, tx) = (Arc::clone(&barrier), Arc::clone(&hold), tx.clone());
            thread::Builder::new()
                .stack_size(128 * 1024)
                .spawn(move || {
                    tx.send(stackler::attach()).unwrap();
                    // Hold the slot until everyone has tried.
                    barrier.wait();
                    hold.wait();
                })
                .unwrap()
        })
        .collect();
    drop(tx);

    let attached = rx.iter().take(overflow).filter(|ok| *ok).count();
    barrier.wait();

    let stats = stackler::stats();
    assert_eq!(attached as u64 + baseline, stats.threads_live);
    assert!(
        attached < overflow,
        "the registry is not supposed to be unbounded"
    );
    assert_eq!(
        stats.untracked,
        (overflow - attached) as u64,
        "threads that missed out are counted"
    );

    hold.wait();
    for squatter in squatters {
        squatter.join().unwrap();
    }
}

/// Slots being recycled while another thread reads snapshots of them is the one
/// place where the registry's state machine has to be right, so it gets hammered:
/// threads appearing and exiting, a sampler reading their painted stacks, and a
/// reader checking that nothing it sees is impossible.
///
/// This is a short version of a test that has already earned its keep — it is what
/// found a snapshot reporting a peak shallower than a depth the same thread had
/// just recorded, and a `reset` erasing a peak recorded while it ran.
#[test]
#[cfg(feature = "sampler")]
fn churn_under_a_sampler() {
    use std::sync::atomic::{AtomicBool, Ordering};

    const CHURNERS: usize = 6;
    const RUN: std::time::Duration = std::time::Duration::from_millis(750);

    stackler::Stackler::new().paint_depth(64 * 1024).install();
    let sampler = stackler::sampler::spawn(std::time::Duration::from_micros(500)).unwrap();

    let stop = Arc::new(AtomicBool::new(false));

    let churners: Vec<_> = (0..CHURNERS)
        .map(|i| {
            let stop = Arc::clone(&stop);
            thread::spawn(move || {
                let mut spawned = 0u64;
                while !stop.load(Ordering::Relaxed) {
                    thread::Builder::new()
                        .stack_size(256 * 1024)
                        .spawn(move || {
                            recurse(i);
                            stackler::sample();
                            if i % 2 == 0 {
                                stackler::peak();
                            }
                        })
                        .unwrap()
                        .join()
                        .unwrap();
                    spawned += 1;
                }
                spawned
            })
        })
        .collect();

    let reader = {
        let stop = Arc::clone(&stop);
        thread::spawn(move || {
            let mut snapshots = 0u64;
            while !stop.load(Ordering::Relaxed) {
                let threads = stackler::threads();
                let stats = stackler::stats();

                for thread in &threads {
                    // A slot recycled mid-read must never be reported as a mix of
                    // the two threads that owned it.
                    assert_eq!(thread.size, thread.base - thread.limit, "{thread:?}");
                    assert!(
                        thread.size >= 4096 && thread.size <= 1024 * 1024 * 1024,
                        "implausible stack: {thread:?}"
                    );
                    assert!(thread.peak <= thread.size, "peak past the end: {thread:?}");
                    assert!(
                        thread.peak >= thread.depth_last,
                        "peak below a depth it recorded: {thread:?}"
                    );
                }

                // `threads()` and `stats()` are two separate walks of the
                // registry, so their counts describe two different moments and
                // need not agree; both must be sane, and neither may be empty
                // while this thread itself is tracked.
                assert!(stats.threads_live <= stackler::MAX_THREADS as u64);
                assert!(threads.len() <= stackler::MAX_THREADS);
                assert!(stats.threads_live >= 1 && !threads.is_empty());
                assert!(stats.threads_seen >= stats.threads_live);
                assert!(stats.reserved_sum >= stats.peak_sum);
                assert_eq!(stats.untracked, 0, "a thread went untracked");
                if let Some(avg) = stats.sample_avg {
                    assert!(
                        avg <= stats.peak_max,
                        "avg {avg} over max {}",
                        stats.peak_max
                    );
                }

                snapshots += 1;
            }
            snapshots
        })
    };

    thread::sleep(RUN);
    stop.store(true, Ordering::Relaxed);

    let spawned: u64 = churners.into_iter().map(|c| c.join().unwrap()).sum();
    let snapshots = reader.join().unwrap();
    sampler.stop();

    // The test is only worth anything if slots were actually recycled and read.
    assert!(spawned > 100, "only {spawned} threads came and went");
    assert!(snapshots > 100, "only {snapshots} snapshots were taken");
}