Skip to content

Commit

Permalink
Document #[track_caller].
Browse files Browse the repository at this point in the history
  • Loading branch information
anp committed Feb 8, 2020
1 parent 11e893f commit 147f53e
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 0 deletions.
2 changes: 2 additions & 0 deletions src/attributes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
22 changes: 22 additions & 0 deletions src/attributes/codegen.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 147f53e

Please sign in to comment.