stackler 0.1.0

A lightweight, always-on stack telemetry library that requires no instrumentation.
Documentation
//! `pthread_create` interposition: the last step to telemetry a program does not
//! have to know about.
//!
//! A thread has to be seen once before it can be described, and everything else
//! in this crate arranges for that to happen on the first call into it. This
//! module removes even that requirement by defining `pthread_create` itself.
//! Because a symbol in the executable takes precedence over the one in the C
//! library, every thread the process creates — including those created by
//! libraries that have never heard of `stackler`, and by `std::thread::spawn`,
//! which goes through the same call — runs a small trampoline that attaches the
//! thread first.
//!
//! Unix only: on other platforms the feature compiles to nothing at all, so that
//! enabling every feature of every crate in a workspace still builds.
//!
//! ## What this costs, and when not to do it
//!
//! - The crate defines a public `pthread_create` symbol. That is a process-wide
//!   decision, which is why the feature is off by default and why it belongs in a
//!   binary rather than in a library that others depend on.
//! - The real `pthread_create` is resolved with `dlsym(RTLD_NEXT, ..)` on first
//!   use. This needs a dynamically linked libc; a fully static link will instead
//!   fail at link time with a duplicate symbol, which is a better outcome than
//!   failing at runtime.
//! - Each intercepted thread costs one small allocation for the trampoline's
//!   payload, plus whatever attaching costs — with the `watermark` feature, that
//!   includes painting the new thread's stack.

use core::{
    ffi::{c_int, c_void},
    ptr,
    sync::atomic::Ordering,
};

use portable_atomic::AtomicPtr;

/// The signature of a thread's entry point.
type StartRoutine = unsafe extern "C" fn(*mut c_void) -> *mut c_void;

/// The signature of `pthread_create` itself.
type PthreadCreate = unsafe extern "C" fn(
    *mut libc::pthread_t,
    *const libc::pthread_attr_t,
    StartRoutine,
    *mut c_void,
) -> c_int;

/// The libc `pthread_create`, cached after the first lookup.
static REAL: AtomicPtr<c_void> = AtomicPtr::new(ptr::null_mut());

/// What the trampoline needs to know to call the thread's real entry point.
struct Payload {
    start: StartRoutine,
    arg: *mut c_void,
}

/// Resolves the `pthread_create` that would have been called if this module did
/// not exist.
fn real_pthread_create() -> Option<PthreadCreate> {
    let cached = REAL.load(Ordering::Relaxed);
    let found = if cached.is_null() {
        // SAFETY: the name is a valid NUL-terminated C string, and `RTLD_NEXT`
        // asks the loader for the next definition after this one.
        let found = unsafe { libc::dlsym(libc::RTLD_NEXT, c"pthread_create".as_ptr()) };
        REAL.store(found, Ordering::Relaxed);
        found
    } else {
        cached
    };

    if found.is_null() {
        return None;
    }

    // SAFETY: `dlsym` returned the address of a function with this signature.
    Some(unsafe { core::mem::transmute::<*mut c_void, PthreadCreate>(found) })
}

/// Attaches the new thread, then hands control to the entry point the caller of
/// `pthread_create` asked for.
unsafe extern "C" fn trampoline(arg: *mut c_void) -> *mut c_void {
    // SAFETY: the pointer is the payload leaked by `pthread_create` below, and
    // this is the only place that reclaims it.
    let payload = unsafe { Box::from_raw(arg.cast::<Payload>()) };

    crate::attach();

    // SAFETY: the entry point and its argument are exactly what the caller of
    // `pthread_create` provided.
    unsafe { (payload.start)(payload.arg) }
}

/// Creates a thread, registering it with `stackler` before it runs.
///
/// This replaces the C library's `pthread_create` for the whole process; it
/// forwards every argument unchanged and returns what the real implementation
/// returns, except that it fails with `EAGAIN` if the real implementation could
/// not be found at all.
///
/// # Safety
///
/// Same contract as the `pthread_create` it replaces.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pthread_create(
    thread: *mut libc::pthread_t,
    attr: *const libc::pthread_attr_t,
    start: StartRoutine,
    arg: *mut c_void,
) -> c_int {
    let Some(real) = real_pthread_create() else {
        return libc::EAGAIN;
    };

    let payload = Box::into_raw(Box::new(Payload { start, arg }));

    // SAFETY: `thread` and `attr` are forwarded untouched, and the trampoline is
    // a valid entry point for the payload it is given.
    let rc = unsafe { real(thread, attr, trampoline, payload.cast()) };

    if rc != 0 {
        // The thread never started, so nothing will ever reclaim the payload.
        // SAFETY: the pointer came from `Box::into_raw` just above and was not
        // handed to anyone else.
        drop(unsafe { Box::from_raw(payload) });
    }

    rc
}