From 147f53e4479270e5e21fbbd2c4990fb159705dda Mon Sep 17 00:00:00 2001 From: Adam Perry Date: Tue, 14 Jan 2020 21:39:16 -0800 Subject: [PATCH] Document #[track_caller]. --- src/attributes.md | 2 ++ src/attributes/codegen.md | 22 ++++++++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/src/attributes.md b/src/attributes.md index dfffe5ca0..1dab24038 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -219,6 +219,7 @@ The following is an index of all built-in attributes. - [`cold`] — Hint that a function is unlikely to be called. - [`no_builtins`] — Disables use of certain built-in functions. - [`target_feature`] — Configure platform-specific code generation. + - [`track_caller`] - Pass the parent call location to `std::panic::Location::caller()`. - Documentation - `doc` — Specifies documentation. See [The Rustdoc Book] for more information. [Doc comments] are transformed into `doc` attributes. @@ -291,6 +292,7 @@ The following is an index of all built-in attributes. [`should_panic`]: attributes/testing.md#the-should_panic-attribute [`target_feature`]: attributes/codegen.md#the-target_feature-attribute [`test`]: attributes/testing.md#the-test-attribute +[`track_caller`]: attributes/codegen.md#the-track_caller-attribute [`type_length_limit`]: attributes/limits.md#the-type_length_limit-attribute [`used`]: abi.md#the-used-attribute [`warn`]: attributes/diagnostics.md#lint-check-attributes diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 5b504c13a..267949466 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -140,6 +140,28 @@ feature detection on the x86 platforms. > may be enabled or disabled for an entire crate with the > [`-C target-feature`] flag. +## The `track_caller` attribute + +The `track_caller` attribute applies to function declarations, allowing code within the function to +observe the callsite of the topmost `track_caller`-attributed function in the attributed function's +callers. If the attributed function itself is called by an unattributed function, then the +attributed function observes its own callsite. If the attributed function is called by another +attributed function, then code within the callee observes the callsite of the caller, and so on. + +> Note: `rustc` implements the `core::intrinsics::caller_location` intrinsic for observing the +> callsite of a function with `#[track_caller]`, wrapped by `core::panic::Location::caller` for +> general use. + +Coercing a function with `#[track_caller]` to a function pointer creates a shim which appears to +observers to have been called at the attributed function's definition site. + +> Note: Rules around shims for function pointers are necessary because `rustc` implements +> `track_caller` in a codegen context by appending an implicit parameter to the function ABI, but +> this would be unsound for an indirect call because the parameter is not a part of the function's +> type and a given function pointer type may or may not refer to a function with the attribute. The +> creation of a shim hides the implicit parameter from callers of the function pointer, preserving +> soundness. + [_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax [`-C target-cpu`]: ../../rustc/codegen-options/index.html#target-cpu [`-C target-feature`]: ../../rustc/codegen-options/index.html#target-feature