stackler 0.1.0

A lightweight, always-on stack telemetry library that requires no instrumentation.
Documentation
//! Benchmarks of the paths a program is expected to leave on, and of the ones it
//! pays for only when it asks a question.
//!
//! The observation paths are deliberately uninteresting under contention: every
//! counter they touch belongs to the thread doing the touching, so scaling the
//! thread count should not change them. That is what the `threads` axis is here
//! to demonstrate.

#[cfg(feature = "std")]
use std::hint::black_box;

fn main() {
    #[cfg(feature = "std")]
    stackler::Stackler::new().install();

    divan::main();
}

#[cfg(feature = "std")]
const THREADS: &[usize] = &[1, 2, 4, 8, 16];
#[cfg(feature = "std")]
const SAMPLE_COUNT: u32 = 200;

/// Reading the stack pointer: the floor everything else is built on.
#[cfg(feature = "std")]
#[divan::bench(sample_count = SAMPLE_COUNT)]
fn sp() -> usize {
    stackler::sp()
}

/// Asking how deep this thread is: a thread-local lookup and two loads.
#[cfg(feature = "std")]
#[divan::bench(threads = THREADS, sample_count = SAMPLE_COUNT)]
fn depth() -> Option<usize> {
    stackler::depth()
}

/// The guard, which is what recursive code calls on every level.
#[cfg(feature = "std")]
#[divan::bench(threads = THREADS, sample_count = SAMPLE_COUNT)]
fn has_headroom() -> bool {
    stackler::has_headroom(black_box(64 * 1024))
}

/// The recording path: the same lookup plus a handful of relaxed atomics, all of
/// them on this thread's own cache lines.
#[cfg(feature = "std")]
#[divan::bench(threads = THREADS, sample_count = SAMPLE_COUNT)]
fn sample() -> Option<usize> {
    stackler::sample()
}

/// Taking a snapshot walks the whole registry, so it scales with slots rather
/// than with threads. This is the one thing a metrics endpoint does.
#[cfg(feature = "std")]
#[divan::bench(threads = THREADS, sample_count = SAMPLE_COUNT)]
fn stats() -> stackler::Stats {
    stackler::stats()
}

#[cfg(all(feature = "std", feature = "watermark"))]
mod watermark {
    use super::*;

    use stackler::{Paint, Peak, Stack};

    /// The depths worth comparing: painting and scanning both scale linearly with
    /// the size of the region.
    const DEPTHS: &[usize] = &[16 * 1024, 256 * 1024, 1024 * 1024];

    fn stack() -> Stack {
        stackler::current_stack().expect("the benchmark thread is tracked")
    }

    /// Painting alone: one `memset` over the region.
    #[divan::bench(args = DEPTHS)]
    fn paint(depth: usize) -> Option<Paint> {
        // SAFETY: this is the calling thread's own stack, and nothing below the
        // stack pointer of ordinary Rust code is live.
        unsafe { stack().paint(depth) }
    }

    /// Painting and then scanning, which is the worst case for the scan: a region
    /// that is entirely pristine has to be walked to the end. Subtract [`paint`]
    /// to get the cost of the scan on its own.
    #[divan::bench(args = DEPTHS)]
    fn paint_and_scan(depth: usize) -> Peak {
        let stack = stack();
        // SAFETY: as above; the paint describes this stack, and this thread is
        // still running on it.
        unsafe {
            let paint = stack.paint(depth).expect("there is room to paint");
            stack.peak(&paint)
        }
    }

    /// The round trip a regression test pays for.
    #[divan::bench(sample_count = SAMPLE_COUNT)]
    fn measure_peak() -> Option<Peak> {
        stackler::measure_peak(|| black_box(())).1
    }

    /// What the background sampler does on every tick, for however many threads
    /// happen to be registered.
    #[divan::bench(sample_count = SAMPLE_COUNT)]
    fn poll_all() {
        stackler::poll_all();
    }
}