src/doc/rustc-dev-guide/src/backend/implicit-caller-location.md

   1 # Implicit Caller Location
   2
   3 <!-- toc -->
   4
   5 Approved in [RFC 2091], this feature enables the accurate reporting of caller location during panics
   6 initiated from functions like `Option::unwrap`, `Result::expect`, and `Index::index`. This feature
   7 adds the [`#[track_caller]`][attr-reference] attribute for functions, the
   8 [`caller_location`][intrinsic] intrinsic, and the stabilization-friendly
   9 [`core::panic::Location::caller`][wrapper] wrapper.
  10
  11 ## Motivating Example
  12
  13 Take this example program:
  14
  15 ```rust
  16 fn main() {
  17     let foo: Option<()> = None;
  18     foo.unwrap(); // this should produce a useful panic message!
  19 }
  20 ```
  21
  22 Prior to Rust 1.42, panics like this `unwrap()` printed a location in core:
  23
  24 ```
  25 $ rustc +1.41.0 example.rs; example.exe
  26 thread 'main' panicked at 'called `Option::unwrap()` on a `None` value',...core\macros\mod.rs:15:40
  27 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace.
  28 ```
  29
  30 As of 1.42, we get a much more helpful message:
  31
  32 ```
  33 $ rustc +1.42.0 example.rs; example.exe
  34 thread 'main' panicked at 'called `Option::unwrap()` on a `None` value', example.rs:3:5
  35 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
  36 ```
  37
  38 These error messages are achieved through a combination of changes to `panic!` internals to make use
  39 of `core::panic::Location::caller` and a number of `#[track_caller]` annotations in the standard
  40 library which propagate caller information.
  41
  42 ## Reading Caller Location
  43
  44 Previously, `panic!` made use of the `file!()`, `line!()`, and `column!()` macros to construct a
  45 [`Location`] pointing to where the panic occurred. These macros couldn't be given an overridden
  46 location, so functions which intentionally invoked `panic!` couldn't provide their own location,
  47 hiding the actual source of error.
  48
  49 Internally, `panic!()` now calls [`core::panic::Location::caller()`][wrapper] to find out where it
  50 was expanded. This function is itself annotated with `#[track_caller]` and wraps the
  51 [`caller_location`][intrinsic] compiler intrinsic implemented by rustc. This intrinsic is easiest
  52 explained in terms of how it works in a `const` context.
  53
  54 ## Caller Location in `const`
  55
  56 There are two main phases to returning the caller location in a const context: walking up the stack
  57 to find the right location and allocating a const value to return.
  58
  59 ### Finding the right `Location`
  60
  61 In a const context we "walk up the stack" from where the intrinsic is invoked, stopping when we
  62 reach the first function call in the stack which does *not* have the attribute. This walk is in
  63 [`InterpCx::find_closest_untracked_caller_location()`][const-find-closest].
  64
  65 Starting at the bottom, we iterate up over stack [`Frame`][const-frame]s in the
  66 [`InterpCx::stack`][const-stack], calling
  67 [`InstanceDef::requires_caller_location`][requires-location] on the
  68 [`Instance`s from each `Frame`][frame-instance]. We stop once we find one that returns `false` and
  69 return the span of the *previous* frame which was the "topmost" tracked function.
  70
  71 ### Allocating a static `Location`
  72
  73 Once we have a `Span`, we need to allocate static memory for the `Location`, which is performed by
  74 the [`TyCtxt::const_caller_location()`][const-location-query] query. Internally this calls
  75 [`InterpCx::alloc_caller_location()`][alloc-location] and results in a unique
  76 [memory kind][location-memory-kind] (`MemoryKind::CallerLocation`). The SSA codegen backend is able
  77 to emit code for these same values, and we use this code there as well.
  78
  79 Once our `Location` has been allocated in static memory, our intrinsic returns a reference to it.
  80
  81 ## Generating code for `#[track_caller]` callees
  82
  83 To generate efficient code for a tracked function and its callers, we need to provide the same
  84 behavior from the intrinsic's point of view without having a stack to walk up at runtime. We invert
  85 the approach: as we grow the stack down we pass an additional argument to calls of tracked functions
  86 rather than walking up the stack when the intrinsic is called. That additional argument can be
  87 returned wherever the caller location is queried.
  88
  89 The argument we append is of type `&'static core::panic::Location<'static>`. A reference was chosen
  90 to avoid unnecessary copying because a pointer is a third the size of
  91 `std::mem::size_of::<core::panic::Location>() == 24` at time of writing.
  92
  93 When generating a call to a function which is tracked, we pass the location argument the value of
  94 [`FunctionCx::get_caller_location`][fcx-get].
  95
  96 If the calling function is tracked, `get_caller_location` returns the local in
  97 [`FunctionCx::caller_location`][fcx-location] which was populated by the current caller's caller.
  98 In these cases the intrinsic "returns" a reference which was actually provided in an argument to its
  99 caller.
 100
 101 If the calling function is not tracked, `get_caller_location` allocates a `Location` static from
 102 the current `Span` and returns a reference to that.
 103
 104 We more efficiently achieve the same behavior as a loop starting from the bottom by passing a single
 105 `&Location` value through the `caller_location` fields of multiple `FunctionCx`s as we grow the
 106 stack downward.
 107
 108 ### Codegen examples
 109
 110 What does this transformation look like in practice? Take this example which uses the new feature:
 111
 112 ```rust
 113 #![feature(track_caller)]
 114 use std::panic::Location;
 115
 116 #[track_caller]
 117 fn print_caller() {
 118     println!("called from {}", Location::caller());
 119 }
 120
 121 fn main() {
 122     print_caller();
 123 }
 124 ```
 125
 126 Here `print_caller()` appears to take no arguments, but we compile it to something like this:
 127
 128 ```rust
 129 #![feature(panic_internals)]
 130 use std::panic::Location;
 131
 132 fn print_caller(caller: &Location) {
 133     println!("called from {}", caller);
 134 }
 135
 136 fn main() {
 137     print_caller(&Location::internal_constructor(file!(), line!(), column!()));
 138 }
 139 ```
 140
 141 ### Dynamic Dispatch
 142
 143 In codegen contexts we have to modify the callee ABI to pass this information down the stack, but
 144 the attribute expressly does *not* modify the type of the function. The ABI change must be
 145 transparent to type checking and remain sound in all uses.
 146
 147 Direct calls to tracked functions will always know the full codegen flags for the callee and can
 148 generate appropriate code. Indirect callers won't have this information and it's not encoded in
 149 the type of the function pointer they call, so we generate a [`ReifyShim`] around the function
 150 whenever taking a pointer to it. This shim isn't able to report the actual location of the indirect
 151 call (the function's definition site is reported instead), but it prevents miscompilation and is
 152 probably the best we can do without modifying fully-stabilized type signatures.
 153
 154 > *Note:* We always emit a [`ReifyShim`] when taking a pointer to a tracked function. While the
 155 > constraint here is imposed by codegen contexts, we don't know during MIR construction of the shim
 156 > whether we'll be called in a const context (safe to ignore shim) or in a codegen context (unsafe
 157 > to ignore shim). Even if we did know, the results from const and codegen contexts must agree.
 158
 159 ## The Attribute
 160
 161 The `#[track_caller]` attribute is checked alongside other codegen attributes to ensure the
 162 function:
 163
 164 * has the `"Rust"` ABI (as opposed to e.g., `"C"`)
 165 * is not a closure
 166 * is not `#[naked]`
 167
 168 If the use is valid, we set [`CodegenFnAttrsFlags::TRACK_CALLER`][attrs-flags]. This flag influences
 169 the return value of [`InstanceDef::requires_caller_location`][requires-location] which is in turn
 170 used in both const and codegen contexts to ensure correct propagation.
 171
 172 ### Traits
 173
 174 When applied to trait method implementations, the attribute works as it does for regular functions.
 175
 176 When applied to a trait method prototype, the attribute applies to all implementations of the
 177 method. When applied to a default trait method implementation, the attribute takes effect on
 178 that implementation *and* any overrides.
 179
 180 Examples:
 181
 182 ```rust
 183 #![feature(track_caller)]
 184
 185 macro_rules! assert_tracked {
 186     () => {{
 187         let location = std::panic::Location::caller();
 188         assert_eq!(location.file(), file!());
 189         assert_ne!(location.line(), line!(), "line should be outside this fn");
 190         println!("called at {}", location);
 191     }};
 192 }
 193
 194 trait TrackedFourWays {
 195     /// All implementations inherit `#[track_caller]`.
 196     #[track_caller]
 197     fn blanket_tracked();
 198
 199     /// Implementors can annotate themselves.
 200     fn local_tracked();
 201
 202     /// This implementation is tracked (overrides are too).
 203     #[track_caller]
 204     fn default_tracked() {
 205         assert_tracked!();
 206     }
 207
 208     /// Overrides of this implementation are tracked (it is too).
 209     #[track_caller]
 210     fn default_tracked_to_override() {
 211         assert_tracked!();
 212     }
 213 }
 214
 215 /// This impl uses the default impl for `default_tracked` and provides its own for
 216 /// `default_tracked_to_override`.
 217 impl TrackedFourWays for () {
 218     fn blanket_tracked() {
 219         assert_tracked!();
 220     }
 221
 222     #[track_caller]
 223     fn local_tracked() {
 224         assert_tracked!();
 225     }
 226
 227     fn default_tracked_to_override() {
 228         assert_tracked!();
 229     }
 230 }
 231
 232 fn main() {
 233     <() as TrackedFourWays>::blanket_tracked();
 234     <() as TrackedFourWays>::default_tracked();
 235     <() as TrackedFourWays>::default_tracked_to_override();
 236     <() as TrackedFourWays>::local_tracked();
 237 }
 238 ```
 239
 240 ## Background/History
 241
 242 Broadly speaking, this feature's goal is to improve common Rust error messages without breaking
 243 stability guarantees, requiring modifications to end-user source, relying on platform-specific
 244 debug-info, or preventing user-defined types from having the same error-reporting benefits.
 245
 246 Improving the output of these panics has been a goal of proposals since at least mid-2016 (see
 247 [non-viable alternatives] in the approved RFC for details). It took two more years until RFC 2091
 248 was approved, much of its [rationale] for this feature's design having been discovered through the
 249 discussion around several earlier proposals.
 250
 251 The design in the original RFC limited itself to implementations that could be done inside the
 252 compiler at the time without significant refactoring. However in the year and a half between the
 253 approval of the RFC and the actual implementation work, a [revised design] was proposed and written
 254 up on the tracking issue. During the course of implementing that, it was also discovered that an
 255 implementation was possible without modifying the number of arguments in a function's MIR, which
 256 would simplify later stages and unlock use in traits.
 257
 258 Because the RFC's implementation strategy could not readily support traits, the semantics were not
 259 originally specified. They have since been implemented following the path which seemed most correct
 260 to the author and reviewers.
 261
 262 [RFC 2091]: https://github.com/rust-lang/rfcs/blob/master/text/2091-inline-semantic.md
 263 [attr-reference]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-track_caller-attribute
 264 [intrinsic]: https://doc.rust-lang.org/nightly/core/intrinsics/fn.caller_location.html
 265 [wrapper]: https://doc.rust-lang.org/nightly/core/panic/struct.Location.html#method.caller
 266 [non-viable alternatives]: https://github.com/rust-lang/rfcs/blob/master/text/2091-inline-semantic.md#non-viable-alternatives
 267 [rationale]: https://github.com/rust-lang/rfcs/blob/master/text/2091-inline-semantic.md#rationale
 268 [revised design]: https://github.com/rust-lang/rust/issues/47809#issuecomment-443538059
 269 [attrs-flags]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/middle/codegen_fn_attrs/struct.CodegenFnAttrFlags.html#associatedconstant.TRACK_CALLER
 270 [`ReifyShim`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/enum.InstanceDef.html#variant.ReifyShim
 271 [`Location`]: https://doc.rust-lang.org/core/panic/struct.Location.html
 272 [const-find-closest]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir/interpret/struct.InterpCx.html#method.find_closest_untracked_caller_location
 273 [requires-location]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/enum.InstanceDef.html#method.requires_caller_location
 274 [alloc-location]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir/interpret/struct.InterpCx.html#method.alloc_caller_location
 275 [fcx-location]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/mir/struct.FunctionCx.html#structfield.caller_location
 276 [const-location-query]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html#method.const_caller_location
 277 [location-memory-kind]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir/interpret/enum.MemoryKind.html#variant.CallerLocation
 278 [const-frame]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir/interpret/struct.Frame.html
 279 [const-stack]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir/interpret/struct.InterpCx.html#structfield.stack
 280 [fcx-get]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/mir/struct.FunctionCx.html#method.get_caller_location
 281 [frame-instance]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir/interpret/struct.Frame.html#structfield.instance