1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
//! **Always-on stack telemetry for Rust, with nothing to instrument.**
//!
//! `stackler` answers the questions a program cannot normally answer about its
//! own stacks: how deep is this thread right now, how deep has it *ever* been,
//! how much of the stack space it reserves does it actually use, and how close is
//! it to running out. It answers them at runtime, in production, without a
//! debugger, without a rebuild, and — this is the point — without touching the
//! code being measured.
//!
//! ## why stackler?
//!
//! Stack use is normally observed either not at all or all at once: a crash. The
//! tools in between are heavyweight — a debugger, a sampling profiler with
//! symbolication, `RUST_MIN_STACK` guesswork after the fact. `stackler` occupies
//! a lighter tier: a handful of numbers per thread, cheap enough to leave on.
//!
//! - **nothing to annotate**: no macros on functions, no wrappers around
//! recursion, no rebuild of the code under observation. Depth is read from the
//! stack pointer, and peaks are read from the stack itself.
//! - **free while running**: with the `watermark` feature the measured code pays
//! *nothing at all* — the unused stack is filled with a marker and later
//! inspected to see how far it was overwritten. All the cost is at the
//! painting and the scan.
//! - **contention-free**: every observation writes only to the recording
//! thread's own cache-aligned slot — depth, peak, counters and depth histogram
//! alike. Nothing on that path is shared, so concurrent sampling scales with the
//! cores doing it; the aggregates are computed when a snapshot is taken.
//! - **overflow guard**: `has_headroom` lets input-driven recursion return an
//! error instead of dying on a guard page, and counts how often it came close.
//! - **reserved vs. used**: `Stats::utilization` and `Stats::waste` put a
//! number on the address space a thread pool spends on stacks nobody descends
//! into.
//! - **`no_std` friendly**: the [`Stack`] primitives — the same painting and
//! scanning an RTOS uses to report a task's high-water mark — need neither
//! `std` nor an allocator.
//!
//! ## quickstart
//!
//! ```rust
//! # #[cfg(feature = "std")] {
//! // In `main`: configures the crate and registers this thread. Optional — any
//! // call into `stackler` attaches the calling thread on its own.
//! stackler::Stackler::new().install();
//!
//! // ... do some deeply nested work ...
//!
//! let stats = stackler::stats();
//! println!("deepest stack use so far: {} bytes", stats.peak_max);
//! # }
//! ```
//!
//! ## measuring specific operations
//!
//! With the `watermark` feature, the stack cost of an operation can be measured
//! exactly the way a heap profiler measures allocations — which makes it an
//! assertion, and an assertion makes it a regression test:
//!
//! ```rust
//! # fn parse(input: &str) -> usize { input.len() }
//! # #[cfg(all(feature = "std", feature = "watermark"))] {
//! let (result, peak) = stackler::measure_peak(|| parse("[[[[nested]]]]"));
//!
//! let peak = peak.expect("this thread's stack is known");
//! assert!(peak.bytes() < 64 * 1024, "regression: the parser got too deep!");
//! # }
//! ```
//!
//! ## guarding recursion
//!
//! Code whose depth depends on its input can ask whether it can afford to go
//! deeper, and turn what would have been a fatal overflow into an ordinary error:
//!
//! ```rust
//! # struct Node { children: Vec<Node> }
//! # struct TooDeep;
//! # #[cfg(feature = "std")]
//! fn walk(node: &Node) -> Result<(), TooDeep> {
//! if !stackler::has_headroom(32 * 1024) {
//! return Err(TooDeep);
//! }
//! for child in &node.children {
//! walk(child)?;
//! }
//! Ok(())
//! }
//! ```
//!
//! ## how much is automatic
//!
//! The features form a ladder, and each rung asks less of the program:
//!
//! | build | what the program does | what it gets |
//! | :--- | :--- | :--- |
//! | default | calls `sample` wherever it has a natural tick | depth distribution, per-thread peaks, guard |
//! | `watermark` | calls `Stackler::install` once | true high-water marks, for code that never calls in |
//! | `sampler` | keeps a `Sampler` alive | those marks kept fresh for every thread, continuously |
//! | `hook_pthread` | nothing | every thread in the process, including those it did not create |
//!
//! ## accuracy
//!
//! Depth and headroom are exact on architectures whose stack pointer can be read
//! directly, which is all of the mainstream ones; elsewhere they are off by at
//! most one frame.
//!
//! Watermarks are approximate, and always in the same direction — they can
//! understate depth, never overstate it. See `Peak` for the specifics: the
//! resolution is a few hundred bytes, a frame that reserves stack without writing
//! to all of it leaves part of the marker intact, and a peak deeper than the
//! painted region can only be reported as a lower bound.
//!
//! ## caveats
//!
//! - Painting commits the memory it touches, so a painted thread's resident set
//! grows by up to `Stackler::paint_depth` bytes. That is the entire cost
//! model of the technique, and the reason the depth is a knob.
//! - Only the thread that owns a stack may paint it. Anyone may *read* a
//! watermark, which is what makes the background `sampler` possible, but such
//! a read races with the owner by construction: the values it sees may be torn.
//! It stays sound in practice because the only question asked of each word is
//! whether the marker is still there, and a torn word is a written word.
//! - On Linux, painting the main thread's stack relies on the kernel growing the
//! main stack mapping on demand. This is how every kernel since 4.13 behaves;
//! on much older ones, prefer to leave the main thread unpainted.
//! - The registry tracks `MAX_THREADS` threads at a time. Threads beyond that
//! are counted in `Stats::untracked` rather than silently dropped.
//! - The first call on a thread is not reentrant: it asks the OS for the thread's
//! bounds, and on glibc's main thread that reads `/proc/self/maps` and
//! allocates. Calling `stackler` from inside a global allocator is therefore a
//! bad idea unless the thread has been `attach`ed beforehand.
// A dangling link is a documentation bug, and it only shows up in the feature
// combinations that lack the item being linked to — which is why this is denied
// rather than left to a warning nobody builds often enough to see.
// Interposing `pthread_create` needs a `pthread_create` to interpose; enabling the
// feature anywhere else is inert rather than a compile error, so that a workspace
// which turns on every feature still builds on every platform.
pub use ;
pub use Histogram;
pub use sp;
pub use ;
pub use ;
pub use Stack;
pub use ;
pub use ;
/// Configures process-wide stack telemetry.
///
/// Everything here has a working default, so the only reason to build one of
/// these is to pick a different trade-off — and to decide *when* the calling
/// thread pays for attaching, which is what [`Stackler::install`] does on the
/// side.
///
/// ```rust
/// stackler::Stackler::new()
/// .paint_depth(1024 * 1024) // look a megabyte deep
/// .reserve(128 * 1024) // treat the last 128 KiB as the danger zone
/// .install();
/// ```
/// Measures the stack telemetry of an operation, returning its result alongside
/// the [`Stats`] delta.
///
/// The counters describe what happened during the call; the gauges describe the
/// process as it was when the call returned. [`Stats`] says which is which.
///
/// This is the whole-process view, and it only sees what threads report about
/// themselves. To measure how deep *this* closure got, reach for
/// Measures how much stack an operation uses, returning its result alongside the
/// deepest point it reached.
///
/// The stack is painted afresh before the call and read back afterwards, so the
/// answer covers everything the closure did — including code that has never heard
/// of `stackler` — and is expressed relative to the depth at the call site.
///
/// Returns `None` for the peak if the calling thread's stack could not be
/// painted: its bounds are unknown, the registry is full, or the configured
/// [paint depth](Stackler::paint_depth) is zero.
///
/// ```rust
/// let (_, peak) = stackler::measure_peak(|| {
/// let big = [0u8; 32 * 1024];
/// std::hint::black_box(&big);
/// });
///
/// assert!(peak.unwrap().bytes() >= 32 * 1024);
/// ```
///
/// # Accuracy
///
/// Painting describes the stack *below* the frame that painted it, so a closure
/// shallower than a kilobyte or so cannot be resolved and reads as
/// [`Peak::Exact(0)`](Peak::Exact). See [`Peak`] for the rest of the caveats.
///
/// Repainting discards the marks left by earlier excursions, so the thread's
/// watermark starts over from here. Its recorded peak does not: the reading is
/// folded into it, and [`Stats::peak_max`] stays monotonic.