stackler 0.1.0

A lightweight, always-on stack telemetry library that requires no instrumentation.
Documentation
//! The stack introspection primitive.

#[cfg(feature = "watermark")]
use core::cmp;

use crate::platform;

/// The size of a machine word, in bytes.
#[cfg(feature = "watermark")]
const WORD: usize = size_of::<usize>();

/// The byte written into unused stack space by [`Stack::paint`]. Its value is
/// arbitrary; what matters is that a full word of it is unlikely to occur in
/// real data.
#[cfg(feature = "watermark")]
const MARKER_BYTE: u8 = 0xA5;

/// [`MARKER_BYTE`] splatted across a machine word.
#[cfg(feature = "watermark")]
const MARKER_WORD: usize = usize::from_ne_bytes([MARKER_BYTE; WORD]);

/// Bytes left unpainted directly below the stack pointer, so that painting
/// cannot touch the frames of the routine doing the painting (or of the routine
/// doing a later scan). It is also the resolution of a watermark reading.
#[cfg(feature = "watermark")]
const TOP_MARGIN: usize = 512;

/// Bytes left unpainted at the very bottom of the stack. Nothing should be
/// mapped there but a guard page, and platforms disagree on whether the guard
/// page is included in the reported bounds; skipping a page is cheap insurance
/// against painting into it and taking a fault.
#[cfg(feature = "watermark")]
const BOTTOM_MARGIN: usize = 4096;

/// The address range of a single thread's stack.
///
/// Stacks are assumed to grow downwards (true on every architecture Rust
/// currently supports), so [`Stack::base`] is where the thread started and
/// [`Stack::limit`] is as deep as it can ever go.
///
/// A `Stack` is a plain pair of addresses: it carries no lifetime relationship
/// to the thread it describes, which is why the painting and scanning
/// operations are `unsafe`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Stack {
    base: usize,
    limit: usize,
}

impl Stack {
    /// Creates a stack from its bounds: `limit` is its lowest usable address and
    /// `base` is one past its highest.
    ///
    /// Returns `None` unless `base > limit`.
    pub const fn from_bounds(limit: usize, base: usize) -> Option<Self> {
        if base > limit {
            Some(Self { base, limit })
        } else {
            None
        }
    }

    /// Creates a stack from its lowest usable address and its size in bytes.
    ///
    /// Returns `None` if `size` is zero or the range would wrap.
    pub const fn from_limit_and_size(limit: usize, size: usize) -> Option<Self> {
        if size == 0 {
            return None;
        }
        match limit.checked_add(size) {
            Some(base) => Some(Self { base, limit }),
            None => None,
        }
    }

    /// Returns the calling thread's own stack, as reported by the OS, or `None`
    /// on platforms that cannot report it.
    ///
    /// This is a syscall-grade operation rather than a cheap one — on glibc the
    /// bounds of the main thread are recovered by reading `/proc/self/maps` —
    /// so the result is worth holding on to. [`crate::attach`] does exactly
    /// that, once per thread.
    #[cfg(feature = "std")]
    pub fn current() -> Option<Self> {
        let (base, limit) = platform::current_bounds()?;
        Self::from_bounds(limit, base)
    }

    /// Returns the address one past the highest byte of the stack; the deepest
    /// point of the thread's very first frame.
    pub const fn base(&self) -> usize {
        self.base
    }

    /// Returns the lowest usable address of the stack. Growing past it is a
    /// stack overflow.
    pub const fn limit(&self) -> usize {
        self.limit
    }

    /// Returns the size of the stack in bytes.
    pub const fn size(&self) -> usize {
        self.base - self.limit
    }

    /// Returns `true` if `addr` lies within the stack.
    pub const fn contains(&self, addr: usize) -> bool {
        addr >= self.limit && addr < self.base
    }

    /// Returns how many bytes of the stack are in use at this very moment, or
    /// `None` if the caller is not running on this stack.
    #[inline]
    pub fn depth(&self) -> Option<usize> {
        self.depth_at(platform::sp())
    }

    /// Returns the depth a given stack pointer corresponds to, or `None` if it
    /// does not point into this stack.
    pub const fn depth_at(&self, sp: usize) -> Option<usize> {
        if self.contains(sp) {
            Some(self.base - sp)
        } else {
            None
        }
    }

    /// Returns how many bytes remain before the stack overflows, or `None` if
    /// the caller is not running on this stack.
    #[inline]
    pub fn headroom(&self) -> Option<usize> {
        self.headroom_at(platform::sp())
    }

    /// Returns the headroom a given stack pointer corresponds to, or `None` if it
    /// does not point into this stack.
    ///
    /// Together with [`Stack::depth_at`] this partitions the stack exactly:
    /// `depth_at(sp) + headroom_at(sp) == size()`. The same does not hold for
    /// [`Stack::depth`] and [`Stack::headroom`], which read the stack pointer at
    /// two different moments — and therefore from two different frames.
    pub const fn headroom_at(&self, sp: usize) -> Option<usize> {
        if self.contains(sp) {
            Some(sp - self.limit)
        } else {
            None
        }
    }

    /// Fills up to `max_depth` bytes of the unused part of the stack with a
    /// marker pattern, so that a later [`Stack::peak`] can tell how deep
    /// execution got in the meantime.
    ///
    /// Returns the region that was painted, or `None` if there was no room to
    /// paint anything.
    ///
    /// Painting is what makes the high-water mark free to *maintain*: the code
    /// being measured pays nothing at all, and the entire cost of the technique
    /// is one `memset` here and one scan in [`Stack::peak`]. It is also what
    /// makes it approximate — see the documentation of [`Peak`].
    ///
    /// The painted region ends a little below the current stack pointer and
    /// begins a page above [`Stack::limit`] at the deepest, so `max_depth` is an
    /// upper bound rather than a promise.
    ///
    /// # Safety
    ///
    /// - The caller must be running on this very stack.
    /// - Nothing may be relying on the contents of the stack below the current
    ///   stack pointer. This holds for ordinary Rust code, which never reads
    ///   abandoned frames, but is not something the compiler can check.
    ///
    /// # Cost
    ///
    /// One `memset` of the returned size, plus the resident memory to back it:
    /// painting forces every page it touches to be committed. That is the price
    /// of the technique, and the reason `max_depth` exists.
    #[cfg(feature = "watermark")]
    pub unsafe fn paint(&self, max_depth: usize) -> Option<Paint> {
        let sp = platform::sp();
        if !self.contains(sp) {
            return None;
        }

        let hi = align_down(sp.checked_sub(TOP_MARGIN)?);
        let floor = self.limit.saturating_add(BOTTOM_MARGIN);
        let lo = align_up(cmp::max(floor, hi.saturating_sub(max_depth)));

        if hi < lo.saturating_add(WORD) {
            return None;
        }

        // SAFETY: `[lo, hi)` is a subrange of this stack that lies entirely
        // below the current stack pointer, so it is mapped, writable, and not
        // aliased by any live frame; the caller guarantees no one is relying on
        // its contents. The pointer is laundered through `black_box` so that the
        // stores cannot be reasoned about as dead.
        unsafe {
            core::ptr::write_bytes(core::hint::black_box(lo as *mut u8), MARKER_BYTE, hi - lo);
        }

        Some(Paint { lo, hi })
    }

    /// Returns the deepest point execution reached since `paint` was applied.
    ///
    /// # Safety
    ///
    /// - `paint` must have been produced by [`Stack::paint`] on this same stack.
    /// - The thread owning the stack must still be alive, or the caller must be
    ///   that thread.
    ///
    /// Reading the stack of *another* live thread is racy by nature: the values
    /// observed may be torn. It stays useful because the only question asked of
    /// each word is whether it still holds the marker, and a torn word is a
    /// written word.
    ///
    /// # Cost
    ///
    /// One pass over the untouched part of the painted region, which is the
    /// common case: a scan is roughly as expensive as the painting it measures.
    #[cfg(feature = "watermark")]
    pub unsafe fn peak(&self, paint: &Paint) -> Peak {
        // The subtractions saturate rather than assume: a measurement is never
        // worth a panic, least of all one taken from a thread-local destructor.
        // SAFETY: forwarded to the caller.
        match unsafe { deepest_touched(paint) } {
            // The marker is gone all the way down: execution may well have gone
            // deeper than the region can show.
            Some(addr) if addr == paint.lo => Peak::AtLeast(self.base.saturating_sub(addr)),
            Some(addr) => Peak::Exact(self.base.saturating_sub(addr)),
            // Nothing below the painted ceiling was ever touched.
            None => Peak::Exact(self.base.saturating_sub(paint.hi)),
        }
    }
}

/// Returns the lowest address in the painted region that no longer holds the
/// marker, or `None` if the whole region is still pristine.
///
/// # Safety
///
/// `paint` must describe a painted region of a stack that is still mapped.
#[cfg(feature = "watermark")]
pub(crate) unsafe fn deepest_touched(paint: &Paint) -> Option<usize> {
    let mut addr = paint.lo;
    while addr < paint.hi {
        // SAFETY: the region is word-aligned, mapped, and readable; volatile
        // reads keep the compiler from assuming anything about memory it
        // considers dead.
        let word = unsafe { (addr as *const usize).read_volatile() };
        if word != MARKER_WORD {
            return Some(addr);
        }
        addr += WORD;
    }
    None
}

/// A painted region of a stack, produced by [`Stack::paint`].
#[cfg(feature = "watermark")]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Paint {
    lo: usize,
    hi: usize,
}

#[cfg(feature = "watermark")]
impl Paint {
    /// Reconstructs a painted region from its bounds.
    ///
    /// Returns `None` unless the bounds are word-aligned and enclose at least
    /// one word.
    pub const fn from_bounds(lo: usize, hi: usize) -> Option<Self> {
        if lo % WORD != 0 || hi % WORD != 0 {
            return None;
        }
        match lo.checked_add(WORD) {
            Some(min_hi) if hi >= min_hi => Some(Self { lo, hi }),
            _ => None,
        }
    }

    /// Returns the lowest painted address.
    pub const fn lo(&self) -> usize {
        self.lo
    }

    /// Returns the address one past the highest painted byte.
    pub const fn hi(&self) -> usize {
        self.hi
    }

    /// Returns the size of the painted region in bytes.
    pub const fn bytes(&self) -> usize {
        self.hi - self.lo
    }
}

/// A high-water mark measurement.
///
/// The distinction between the two variants is the honest part of the watermark
/// technique: a painted region can only report what fits inside it.
///
/// Readings are approximate in two further ways, both of which err on the low
/// side:
///
/// - resolution is a few hundred bytes, because the region starts slightly below
///   the stack pointer of whoever painted it;
/// - a frame that reserves space without writing to all of it leaves the marker
///   intact in the gap, and the deepest *written* word is what gets reported.
#[cfg(feature = "watermark")]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
pub enum Peak {
    /// The watermark was found inside the painted region.
    Exact(usize),
    /// The painted region was consumed entirely; the true peak is at least this
    /// deep, and the region should be enlarged to find out by how much.
    AtLeast(usize),
}

#[cfg(feature = "watermark")]
impl Peak {
    /// Returns the measured depth in bytes.
    pub const fn bytes(&self) -> usize {
        match self {
            Self::Exact(bytes) | Self::AtLeast(bytes) => *bytes,
        }
    }

    /// Returns `true` if the measurement is a lower bound rather than a reading.
    pub const fn is_saturated(&self) -> bool {
        matches!(self, Self::AtLeast(_))
    }
}

#[cfg(feature = "watermark")]
const fn align_down(addr: usize) -> usize {
    addr & !(WORD - 1)
}

/// Rounds up to a word boundary, saturating rather than wrapping past the top of
/// the address space.
#[cfg(feature = "watermark")]
const fn align_up(addr: usize) -> usize {
    align_down(addr.saturating_add(WORD - 1))
}