mod_alloc/symbolicate/
mod.rs

1//! Symbolication for the per-call-site report (v0.9.2).
2//!
3//! Behind the `symbolicate` cargo feature. Turns the raw return
4//! addresses captured by v0.9.1's backtrace path into
5//! `(function, file, line)` tuples at *report-generation time*.
6//! Never invoked from the alloc hot path.
7//!
8//! ## Dependencies
9//!
10//! See `.dev/DIRECTIVES.md` section 2.2 for the approved external-
11//! dep exception. Default builds, the `counters` feature, and
12//! the `backtraces` feature remain zero-runtime-dep. The
13//! `symbolicate` feature pulls in:
14//!
15//! - `addr2line` + `object` + `rustc-demangle` (all targets)
16//! - `pdb` (Windows only)
17//!
18//! All are pure-Rust, MSRV 1.75-compatible.
19//!
20//! ## Platform parity
21//!
22//! Linux / macOS produce richer output than Windows (DWARF
23//! inlining info is more complete than PDB's `S_INLINESITE`).
24//! This is accepted; the asymmetry is documented and not gated.
25
26use std::path::PathBuf;
27
28pub(crate) mod self_binary;
29
30#[cfg(unix)]
31pub(crate) mod unix;
32
33#[cfg(windows)]
34pub(crate) mod windows;
35
36pub(crate) mod report;
37
38/// One symbolicated frame within a call site.
39///
40/// `function`, `file`, and `line` are each `None` when the
41/// underlying debug info did not resolve to a name / location
42/// (stripped binaries, FFI frames into system libraries, etc.).
43/// The raw `address` is always preserved.
44///
45/// # Stability
46///
47/// Marked `#[non_exhaustive]` as of v1.0.0. Future minor
48/// versions may add fields (e.g. column number, symbol kind,
49/// crate-of-origin). Read fields by name; iterate via
50/// [`ModAlloc::symbolicated_report`](crate::ModAlloc::symbolicated_report).
51#[derive(Debug, Clone)]
52#[non_exhaustive]
53pub struct SymbolicatedFrame {
54    /// Original raw return address from the capture path.
55    pub address: u64,
56    /// Demangled Rust function name, if resolvable.
57    pub function: Option<String>,
58    /// Source file path, if resolvable.
59    pub file: Option<PathBuf>,
60    /// Source line number, if resolvable.
61    pub line: Option<u32>,
62    /// True if this frame represents an inlined call site that
63    /// expanded from the same return address as a previous frame
64    /// in the parent `SymbolicatedCallSite.frames` vector.
65    pub inlined: bool,
66}
67
68/// One symbolicated call site (counterpart of
69/// [`CallSiteStats`](crate::CallSiteStats)).
70///
71/// Contains the aggregated counters from the raw report plus a
72/// vector of resolved frames in top-of-stack-first order.
73///
74/// # Stability
75///
76/// Marked `#[non_exhaustive]` as of v1.0.0. Future minor
77/// versions may add fields without bumping the major version.
78#[derive(Debug, Clone)]
79#[non_exhaustive]
80pub struct SymbolicatedCallSite {
81    /// Allocations attributed to this site.
82    pub count: u64,
83    /// Total bytes allocated at this site.
84    pub total_bytes: u64,
85    /// Resolved frames, top of stack first. May contain frames
86    /// with `inlined = true` representing inlined call sites
87    /// expanded from a single physical return address.
88    pub frames: Vec<SymbolicatedFrame>,
89}
90
91pub use report::symbolicated_report;
mod_alloc/symbolicate/mod.rs

mod_alloc/symbolicate/
mod.rs
