Skip to content

Commit

Permalink
Rollup merge of rust-lang#72445 - anp:stabilize-track-caller, r=oli-obk
Browse files Browse the repository at this point in the history
Stabilize `#[track_caller]`.

# Stabilization Report

RFC: [2091]
Tracking issue: rust-lang#47809

## Summary

From the [rustc-dev-guide chapter][dev-guide]:

> Take this example program:

```rust
fn main() {
    let foo: Option<()> = None;
    foo.unwrap(); // this should produce a useful panic message!
}
```

> Prior to Rust 1.42, panics like this `unwrap()` printed a location in libcore:

```
$ rustc +1.41.0 example.rs; example.exe
thread 'main' panicked at 'called `Option::unwrap()` on a `None` value',...core\macros\mod.rs:15:40
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace.
```

> As of 1.42, we get a much more helpful message:

```
$ rustc +1.42.0 example.rs; example.exe
thread 'main' panicked at 'called `Option::unwrap()` on a `None` value', example.rs:3:5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
```

> These error messages are achieved through a combination of changes to `panic!` internals to make use of `core::panic::Location::caller` and a number of `#[track_caller]` annotations in the standard library which propagate caller information.

The attribute adds an implicit caller location argument to the ABI of annotated functions, but does not affect the type or MIR of the function. We implement the feature entirely in codegen and in the const evaluator.

## Bottom Line

This PR stabilizes the use of `#[track_caller]` everywhere, including traits and extern blocks. It also stabilizes `core::panic::Location::caller`, although the use of that function in a const context remains gated by `#![feature(const_caller_location)]`.

The implementation for the feature already changed the output of panic messages for a number of std functions, as described in the [1.42 release announcement]. The attribute's use in `Index` and `IndexMut` traits is visible to users since 1.44.

## Tests

All of the tests for this feature live under [src/test/ui/rfc-2091-track-caller][tests] in the repo.

Noteworthy cases:

* [use of attr in std]
  * validates user-facing benefit of the feature
* [trait attribute inheritance]
  * covers subtle behavior designed during implementation and not RFC'd
* [const/codegen equivalence]
  * this was the result of a suspected edge case and investigation
* [diverging function support]
  * covers an unresolved question from the RFC
* [fn pointers and shims]
  * covers important potential sources of unsoundness

## Documentation

The rustc-dev-guide now has a chapter on [Implicit Caller Location][dev-guide].

I have an [open PR to the reference][attr-reference-pr] documenting the attribute.

The intrinsic's [wrapper] includes some examples as well.

## Implementation History

* 2019-10-02: [`#[track_caller]` feature gate (RFC 2091 1/N) rust-lang#65037](rust-lang#65037)
  * Picked up the patch that @ayosec had started on the feature gate.
* 2019-10-13: [Add `Instance::resolve_for_fn_ptr` (RFC 2091 rust-lang#2/N) rust-lang#65182](rust-lang#65182)
* 2019-10-20: ~~[WIP Add MIR argument for #[track_caller] (RFC 2091 3/N) rust-lang#65258](rust-lang#65258
  * Abandoned approach to send location as a MIR argument.
* 2019-10-28: [`std::panic::Location` is a lang_item, add `core::intrinsics::caller_location` (RFC 2091 3/N) rust-lang#65664](rust-lang#65664)
* 2019-12-07: [Implement #[track_caller] attribute. (RFC 2091 4/N) rust-lang#65881](rust-lang#65881)
* 2020-01-04: [libstd uses `core::panic::Location` where possible. rust-lang#67137](rust-lang#67137)
* 2020-01-08: [`Option::{expect,unwrap}` and `Result::{expect, expect_err, unwrap, unwrap_err}` have `#[track_caller]` rust-lang#67887](rust-lang#67887)
* 2020-01-20: [Fix #[track_caller] and function pointers rust-lang#68302](rust-lang#68302) (fixed rust-lang#68178)
* 2020-03-23: [#[track_caller] in traits rust-lang#69251](rust-lang#69251)
* 2020-03-24: [#[track_caller] on core::ops::{Index, IndexMut}. rust-lang#70234](rust-lang#70234)
* 2020-04-08 [Support `#[track_caller]` on functions in `extern "Rust" { ... }` rust-lang#70916](rust-lang#70916)

## Unresolveds

### From the RFC

> Currently the RFC simply prohibit applying #[track_caller] to trait methods as a future-proofing
> measure.

**Resolved.** See the dev-guide documentation and the tests section above.

> Diverging functions should be supported.

**Resolved.** See the tests section above.

> The closure foo::{{closure}} should inherit most attributes applied to the function foo, ...

**Resolved.** This unknown was related to specifics of the implementation which were made irrelevant by the final implementation.

### Binary Size

I [instrumented track_caller to use custom sections][measure-size] in a local build and discovered relatively minor binary size usage for the feature overall. I'm leaving the issue open to discuss whether we want to upstream custom section support.

There's an [open issue to discuss mitigation strategies][mitigate-size]. Some decisions remain about the "right" strategies to reduce size without overly constraining the compiler implementation. I'd be excited to see someone carry that work forward but my opinion is that we shouldn't block stabilization on implementing compiler flags for redaction.

### Specialization

There's an [open issue][specialization] on the semantics of the attribute in specialization chains. I'm inclined to move forward with stabilization without an exact resolution here given that specialization is itself unstable, but I also think it should be an easy question to resolve.

### Location only points to the start of a call span

rust-lang#69977 was resolved by rust-lang#73182, and the next step should probably be to [extend `Location` with a notion of the end of a call](rust-lang#73554).

### Regression of std's panic messages

rust-lang#70963 should be resolved by serializing span hygeine to crate metadata: rust-lang#68686.

[2091]: https://github.com/rust-lang/rfcs/blob/master/text/2091-inline-semantic.md
[dev-guide]: https://rustc-dev-guide.rust-lang.org/codegen/implicit-caller-location.html
[specialization]: rust-lang#70293
[measure-size]: rust-lang#70579
[mitigate-size]: rust-lang#70580
[attr-reference-pr]: rust-lang/reference#742
[wrapper]: https://doc.rust-lang.org/nightly/core/panic/struct.Location.html#method.caller
[tests]: https://github.com/rust-lang/rust/tree/master/src/test/ui/rfc-2091-track-caller
[const/codegen equivalence]: https://github.com/rust-lang/rust/blob/master/src/test/ui/rfc-2091-track-caller/caller-location-fnptr-rt-ctfe-equiv.rs
[diverging function support]: https://github.com/rust-lang/rust/blob/master/src/test/ui/rfc-2091-track-caller/diverging-caller-location.rs
[use of attr in std]: https://github.com/rust-lang/rust/blob/master/src/test/ui/rfc-2091-track-caller/std-panic-locations.rs
[fn pointers and shims]: https://github.com/rust-lang/rust/blob/master/src/test/ui/rfc-2091-track-caller/tracked-fn-ptr-with-arg.rs
[trait attribute inheritance]: https://github.com/rust-lang/rust/blob/master/src/test/ui/rfc-2091-track-caller/tracked-trait-impls.rs
[1.42 release announcement]: https://blog.rust-lang.org/2020/03/12/Rust-1.42.html#useful-line-numbers-in-option-and-result-panic-messages
  • Loading branch information
Manishearth committed Jun 30, 2020
2 parents a1528c4 + 135ca38 commit 8e47182
Show file tree
Hide file tree
Showing 37 changed files with 35 additions and 98 deletions.
5 changes: 0 additions & 5 deletions src/doc/unstable-book/src/language-features/track-caller.md

This file was deleted.

2 changes: 1 addition & 1 deletion src/libcore/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@
#![feature(staged_api)]
#![feature(std_internals)]
#![feature(stmt_expr_attributes)]
#![feature(track_caller)]
#![cfg_attr(bootstrap, feature(track_caller))]
#![feature(transparent_unions)]
#![feature(unboxed_closures)]
#![feature(unsized_locals)]
Expand Down
2 changes: 1 addition & 1 deletion src/libcore/macros/mod.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#[doc(include = "panic.md")]
#[macro_export]
#[allow_internal_unstable(core_panic, track_caller)]
#[allow_internal_unstable(core_panic, const_caller_location)]
#[stable(feature = "core", since = "1.6.0")]
macro_rules! panic {
() => (
Expand Down
14 changes: 4 additions & 10 deletions src/libcore/panic.rs
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,6 @@ impl<'a> Location<'a> {
/// # Examples
///
/// ```
/// #![feature(track_caller)]
/// use core::panic::Location;
///
/// /// Returns the [`Location`] at which it is called.
Expand All @@ -206,7 +205,7 @@ impl<'a> Location<'a> {
///
/// let fixed_location = get_just_one_location();
/// assert_eq!(fixed_location.file(), file!());
/// assert_eq!(fixed_location.line(), 15);
/// assert_eq!(fixed_location.line(), 14);
/// assert_eq!(fixed_location.column(), 5);
///
/// // running the same untracked function in a different location gives us the same result
Expand All @@ -217,7 +216,7 @@ impl<'a> Location<'a> {
///
/// let this_location = get_caller_location();
/// assert_eq!(this_location.file(), file!());
/// assert_eq!(this_location.line(), 29);
/// assert_eq!(this_location.line(), 28);
/// assert_eq!(this_location.column(), 21);
///
/// // running the tracked function in a different location produces a different value
Expand All @@ -226,13 +225,8 @@ impl<'a> Location<'a> {
/// assert_ne!(this_location.line(), another_location.line());
/// assert_ne!(this_location.column(), another_location.column());
/// ```
// FIXME: When stabilizing this method, please also update the documentation
// of `intrinsics::caller_location`.
#[unstable(
feature = "track_caller",
reason = "uses #[track_caller] which is not yet stable",
issue = "47809"
)]
#[stable(feature = "track_caller", since = "1.46.0")]
#[rustc_const_unstable(feature = "const_caller_location", issue = "47809")]
#[track_caller]
pub const fn caller() -> &'static Location<'static> {
crate::intrinsics::caller_location()
Expand Down
2 changes: 0 additions & 2 deletions src/librustc_error_codes/error_codes/E0736.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@
Erroneous code example:

```compile_fail,E0736
#![feature(track_caller)]
#[naked]
#[track_caller]
fn foo() {}
Expand Down
2 changes: 0 additions & 2 deletions src/librustc_error_codes/error_codes/E0737.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,6 @@ restrictions.
Erroneous code example:

```compile_fail,E0737
#![feature(track_caller)]
#[track_caller]
extern "C" fn foo() {}
```
Expand Down
1 change: 0 additions & 1 deletion src/librustc_error_codes/error_codes/E0739.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
Erroneous code example:

```compile_fail,E0739
#![feature(track_caller)]
#[track_caller]
struct Bar {
a: u8,
Expand Down
2 changes: 1 addition & 1 deletion src/librustc_errors/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
#![doc(html_root_url = "https://doc.rust-lang.org/nightly/")]
#![feature(crate_visibility_modifier)]
#![feature(nll)]
#![feature(track_caller)]
#![cfg_attr(bootstrap, feature(track_caller))]

pub use emitter::ColorConfig;

Expand Down
3 changes: 3 additions & 0 deletions src/librustc_feature/accepted.rs
Original file line number Diff line number Diff line change
Expand Up @@ -265,6 +265,9 @@ declare_features! (
(accepted, const_if_match, "1.45.0", Some(49146), None),
/// Allows the use of `loop` and `while` in constants.
(accepted, const_loop, "1.45.0", Some(52000), None),
/// Allows `#[track_caller]` to be used which provides
/// accurate caller location reporting during panic (RFC 2091).
(accepted, track_caller, "1.46.0", Some(47809), None),

// -------------------------------------------------------------------------
// feature-group-end: accepted features
Expand Down
4 changes: 0 additions & 4 deletions src/librustc_feature/active.rs
Original file line number Diff line number Diff line change
Expand Up @@ -494,10 +494,6 @@ declare_features! (
/// Allows the use of raw-dylibs (RFC 2627).
(active, raw_dylib, "1.40.0", Some(58713), None),

/// Allows `#[track_caller]` to be used which provides
/// accurate caller location reporting during panic (RFC 2091).
(active, track_caller, "1.40.0", Some(47809), None),

/// Allows making `dyn Trait` well-formed even if `Trait` is not object safe.
/// In that case, `dyn Trait: Trait` does not hold. Moreover, coercions and
/// casts in safe Rust to `dyn Trait` for such a `Trait` is also forbidden.
Expand Down
2 changes: 1 addition & 1 deletion src/librustc_feature/builtin_attrs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -260,6 +260,7 @@ pub const BUILTIN_ATTRIBUTES: &[BuiltinAttribute] = &[
ungated!(cold, Whitelisted, template!(Word)),
ungated!(no_builtins, Whitelisted, template!(Word)),
ungated!(target_feature, Whitelisted, template!(List: r#"enable = "name""#)),
ungated!(track_caller, Whitelisted, template!(Word)),
gated!(
no_sanitize, Whitelisted,
template!(List: "address, memory, thread"),
Expand Down Expand Up @@ -333,7 +334,6 @@ pub const BUILTIN_ATTRIBUTES: &[BuiltinAttribute] = &[
gated!(ffi_returns_twice, Whitelisted, template!(Word), experimental!(ffi_returns_twice)),
gated!(ffi_pure, Whitelisted, template!(Word), experimental!(ffi_pure)),
gated!(ffi_const, Whitelisted, template!(Word), experimental!(ffi_const)),
gated!(track_caller, Whitelisted, template!(Word), experimental!(track_caller)),
gated!(
register_attr, CrateLevel, template!(List: "attr1, attr2, ..."),
experimental!(register_attr),
Expand Down
2 changes: 1 addition & 1 deletion src/librustc_middle/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@
#![feature(or_patterns)]
#![feature(range_is_empty)]
#![feature(min_specialization)]
#![feature(track_caller)]
#![cfg_attr(bootstrap, feature(track_caller))]
#![feature(trusted_len)]
#![feature(stmt_expr_attributes)]
#![feature(test)]
Expand Down
2 changes: 1 addition & 1 deletion src/libstd/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -316,7 +316,7 @@
#![feature(toowned_clone_into)]
#![feature(total_cmp)]
#![feature(trace_macros)]
#![feature(track_caller)]
#![cfg_attr(bootstrap, feature(track_caller))]
#![feature(try_reserve)]
#![feature(unboxed_closures)]
#![feature(untagged_unions)]
Expand Down
5 changes: 0 additions & 5 deletions src/test/ui/feature-gates/feature-gate-track_caller.rs

This file was deleted.

12 changes: 0 additions & 12 deletions src/test/ui/feature-gates/feature-gate-track_caller.stderr

This file was deleted.

2 changes: 0 additions & 2 deletions src/test/ui/macros/issue-68060.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
#![feature(track_caller)]

fn main() {
(0..)
.map(
Expand Down
6 changes: 3 additions & 3 deletions src/test/ui/macros/issue-68060.stderr
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
error[E0658]: `#[target_feature(..)]` can only be applied to `unsafe` functions
--> $DIR/issue-68060.rs:6:13
--> $DIR/issue-68060.rs:4:13
|
LL | #[target_feature(enable = "")]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -11,13 +11,13 @@ LL | |_| (),
= help: add `#![feature(target_feature_11)]` to the crate attributes to enable

error: the feature named `` is not valid for this target
--> $DIR/issue-68060.rs:6:30
--> $DIR/issue-68060.rs:4:30
|
LL | #[target_feature(enable = "")]
| ^^^^^^^^^^^ `` is not valid for this target

error[E0737]: `#[track_caller]` requires Rust ABI
--> $DIR/issue-68060.rs:9:13
--> $DIR/issue-68060.rs:7:13
|
LL | #[track_caller]
| ^^^^^^^^^^^^^^^
Expand Down
1 change: 0 additions & 1 deletion src/test/ui/numbers-arithmetic/saturating-float-casts.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@
// merged.

#![feature(test, stmt_expr_attributes)]
#![feature(track_caller)]
#![deny(overflowing_literals)]
extern crate test;

Expand Down
2 changes: 0 additions & 2 deletions src/test/ui/rfc-2091-track-caller/call-chain.rs
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
// run-pass

#![feature(track_caller)]

use std::panic::Location;

struct Foo;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
// run-pass
// compile-flags: -Z unleash-the-miri-inside-of-you

#![feature(core_intrinsics, const_caller_location, track_caller, const_fn)]
#![feature(core_intrinsics, const_caller_location, const_fn)]

type L = &'static std::panic::Location<'static>;

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
// run-pass

#![feature(track_caller)]

#[inline(never)]
#[track_caller]
fn codegen_caller_loc() -> &'static core::panic::Location<'static> {
Expand All @@ -15,13 +13,13 @@ macro_rules! caller_location_from_macro {
fn main() {
let loc = codegen_caller_loc();
assert_eq!(loc.file(), file!());
assert_eq!(loc.line(), 16);
assert_eq!(loc.line(), 14);
assert_eq!(loc.column(), 15);

// `Location::caller()` in a macro should behave similarly to `file!` and `line!`,
// i.e. point to where the macro was invoked, instead of the macro itself.
let loc2 = caller_location_from_macro!();
assert_eq!(loc2.file(), file!());
assert_eq!(loc2.line(), 23);
assert_eq!(loc2.line(), 21);
assert_eq!(loc2.column(), 16);
}
2 changes: 1 addition & 1 deletion src/test/ui/rfc-2091-track-caller/const-caller-location.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// run-pass

#![feature(const_fn, track_caller)]
#![feature(const_caller_location, const_fn)]

use std::panic::Location;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,6 @@
//! we don't inspect the location returned -- it would be difficult to distinguish between the
//! explicit panic and a failed assertion. That it compiles and runs is enough for this one.

#![feature(track_caller)]

#[track_caller]
fn doesnt_return() -> ! {
let _location = core::panic::Location::caller();
Expand Down
2 changes: 0 additions & 2 deletions src/test/ui/rfc-2091-track-caller/error-odd-syntax.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
#![feature(track_caller)]

#[track_caller(1)]
fn f() {}
//~^^ ERROR malformed `track_caller` attribute input
Expand Down
2 changes: 1 addition & 1 deletion src/test/ui/rfc-2091-track-caller/error-odd-syntax.stderr
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
error: malformed `track_caller` attribute input
--> $DIR/error-odd-syntax.rs:3:1
--> $DIR/error-odd-syntax.rs:1:1
|
LL | #[track_caller(1)]
| ^^^^^^^^^^^^^^^^^^ help: must be of the form: `#[track_caller]`
Expand Down
2 changes: 0 additions & 2 deletions src/test/ui/rfc-2091-track-caller/error-with-invalid-abi.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
#![feature(track_caller)]

#[track_caller]
extern "C" fn f() {}
//~^^ ERROR `#[track_caller]` requires Rust ABI
Expand Down
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
error[E0737]: `#[track_caller]` requires Rust ABI
--> $DIR/error-with-invalid-abi.rs:3:1
--> $DIR/error-with-invalid-abi.rs:1:1
|
LL | #[track_caller]
| ^^^^^^^^^^^^^^^

error[E0737]: `#[track_caller]` requires Rust ABI
--> $DIR/error-with-invalid-abi.rs:8:5
--> $DIR/error-with-invalid-abi.rs:6:5
|
LL | #[track_caller]
| ^^^^^^^^^^^^^^^
Expand Down
2 changes: 1 addition & 1 deletion src/test/ui/rfc-2091-track-caller/error-with-naked.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#![feature(naked_functions, track_caller)]
#![feature(naked_functions)]

#[track_caller] //~ ERROR cannot use `#[track_caller]` with `#[naked]`
#[naked]
Expand Down
6 changes: 2 additions & 4 deletions src/test/ui/rfc-2091-track-caller/intrinsic-wrapper.rs
Original file line number Diff line number Diff line change
@@ -1,21 +1,19 @@
// run-pass

#![feature(track_caller)]

macro_rules! caller_location_from_macro {
() => (core::panic::Location::caller());
}

fn main() {
let loc = core::panic::Location::caller();
assert_eq!(loc.file(), file!());
assert_eq!(loc.line(), 10);
assert_eq!(loc.line(), 8);
assert_eq!(loc.column(), 15);

// `Location::caller()` in a macro should behave similarly to `file!` and `line!`,
// i.e. point to where the macro was invoked, instead of the macro itself.
let loc2 = caller_location_from_macro!();
assert_eq!(loc2.file(), file!());
assert_eq!(loc2.line(), 17);
assert_eq!(loc2.line(), 15);
assert_eq!(loc2.column(), 16);
}
2 changes: 0 additions & 2 deletions src/test/ui/rfc-2091-track-caller/only-for-fns.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
#![feature(track_caller)]

#[track_caller]
struct S;
//~^^ ERROR attribute should be applied to function
Expand Down
2 changes: 1 addition & 1 deletion src/test/ui/rfc-2091-track-caller/only-for-fns.stderr
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
error[E0739]: attribute should be applied to function
--> $DIR/only-for-fns.rs:3:1
--> $DIR/only-for-fns.rs:1:1
|
LL | #[track_caller]
| ^^^^^^^^^^^^^^^
Expand Down
2 changes: 0 additions & 2 deletions src/test/ui/rfc-2091-track-caller/pass.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
// run-pass
#![feature(track_caller)]

#[track_caller]
fn f() {}

Expand Down
10 changes: 4 additions & 6 deletions src/test/ui/rfc-2091-track-caller/track-caller-attribute.rs
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
// run-pass

#![feature(track_caller)]

use std::panic::Location;

#[track_caller]
Expand All @@ -20,21 +18,21 @@ fn nested_tracked() -> &'static Location<'static> {
fn main() {
let location = Location::caller();
assert_eq!(location.file(), file!());
assert_eq!(location.line(), 21);
assert_eq!(location.line(), 19);
assert_eq!(location.column(), 20);

let tracked = tracked();
assert_eq!(tracked.file(), file!());
assert_eq!(tracked.line(), 26);
assert_eq!(tracked.line(), 24);
assert_eq!(tracked.column(), 19);

let nested = nested_intrinsic();
assert_eq!(nested.file(), file!());
assert_eq!(nested.line(), 13);
assert_eq!(nested.line(), 11);
assert_eq!(nested.column(), 5);

let contained = nested_tracked();
assert_eq!(contained.file(), file!());
assert_eq!(contained.line(), 17);
assert_eq!(contained.line(), 15);
assert_eq!(contained.column(), 5);
}
Loading

0 comments on commit 8e47182

Please sign in to comment.