stackler 0.1.0

A lightweight, always-on stack telemetry library that requires no instrumentation.
Documentation
//! Tests of the parts that need neither `std` nor an operating system, and so
//! stay available to `no_std` users: the [`Stack`] arithmetic, the stack pointer,
//! and the histogram.

use stackler::Stack;

#[test]
fn stack_arithmetic() {
    let stack = Stack::from_limit_and_size(0x10_000, 0x8_000).unwrap();

    assert_eq!(stack.limit(), 0x10_000);
    assert_eq!(stack.base(), 0x18_000);
    assert_eq!(stack.size(), 0x8_000);

    // The bounds are half-open: the base is one past the last usable byte.
    assert!(stack.contains(0x10_000));
    assert!(stack.contains(0x17_fff));
    assert!(!stack.contains(0x18_000));
    assert!(!stack.contains(0xf_fff));

    // Depth is measured from the base downwards, headroom from the limit up, and
    // the two partition the stack.
    for sp in [0x10_000, 0x14_000, 0x17_ff8] {
        let depth = stack.depth_at(sp).unwrap();
        let headroom = stack.headroom_at(sp).unwrap();
        assert_eq!(depth, stack.base() - sp);
        assert_eq!(headroom, sp - stack.limit());
        assert_eq!(depth + headroom, stack.size());
    }

    // Addresses outside the stack describe nothing.
    assert_eq!(stack.depth_at(0x18_000), None);
    assert_eq!(stack.headroom_at(0xf_fff), None);

    // The two constructors agree.
    assert_eq!(Stack::from_bounds(0x10_000, 0x18_000), Some(stack));
}

#[test]
fn stack_pointer_moves_the_way_stacks_grow() {
    let outer = stackler::sp();

    #[inline(never)]
    fn inner() -> usize {
        let mut frame = [0u8; 4096];
        std::hint::black_box(&mut frame);
        stackler::sp()
    }

    let inner = inner();

    // Stacks grow downwards on every architecture Rust supports.
    assert!(inner < outer, "{inner:#x} !< {outer:#x}");
    assert!(outer - inner >= 4096, "{:#x}", outer - inner);

    // And the reading is stable at a given depth.
    assert!(stackler::sp().abs_diff(outer) < 1024);
}

#[test]
#[cfg(feature = "histograms")]
fn histogram_arithmetic() {
    use stackler::Histogram;

    let mut buckets = [0u64; 64];
    buckets[10] = 5; // [1 KiB, 2 KiB)
    buckets[12] = 2; // [4 KiB, 8 KiB)
    let newer = Histogram::from_buckets(buckets);

    buckets[10] = 3;
    buckets[12] = 2;
    let older = Histogram::from_buckets(buckets);

    let diff = newer - older;
    assert_eq!(diff.buckets()[10], 2);
    assert_eq!(diff.buckets()[12], 0);
    assert_eq!(diff.total(), 2);

    // All four owned/borrowed combinations agree.
    use std::ops::Sub;
    assert_eq!(Sub::sub(&newer, &older).buckets(), diff.buckets());
    assert_eq!(Sub::sub(newer, &older).buckets(), diff.buckets());
    assert_eq!(Sub::sub(&newer, older).buckets(), diff.buckets());

    // Subtracting the other way saturates instead of wrapping.
    let backwards = older - newer;
    assert!(backwards.is_empty());

    // The quantile lands inside the bucket that holds the rank.
    let q50 = newer.quantile(0.5).unwrap();
    assert!((1024..2048).contains(&q50), "{q50}");
    let q100 = newer.quantile(1.0).unwrap();
    assert!((4096..8192).contains(&q100), "{q100}");
}