Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Attributes

The #[cold] and #[track_caller] attributes

Reference for Rust #[cold] and #[track_caller]: hint that a function is rarely called, and make a function report its caller's file, line and column.

#[cold] tells the compiler that a function is called rarely, such as an error or panic path. The optimizer then keeps that code out of the hot path, treats branches that lead to it as unlikely and may optimize it for size. It never changes what the program prints.

#[track_caller] changes where a function thinks it was called from. Inside such a function, std::panic::Location::caller() returns the file, line and column of the call site instead of a place inside the function. This is how Option::unwrap and slice[i] report the line in your code when they panic.

Rust
#[cold]
fn report_failure(msg: &str) -> ! { panic!("{msg}") }

#[track_caller]
fn whoami() -> u32 { std::panic::Location::caller().line() }

Try it

Rust Where was I called from?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust A cold failure path

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Rust
#[cold]
fn rarely_called() { /* ... */ }

#[track_caller]
fn checked(/* params */) { /* ... */ }
Attribute Applies to Effect
#[cold] functions (including methods) Hint: the function is unlikely to be called.
#[track_caller] functions with the "Rust" ABI, methods, trait methods Location::caller() returns the caller's location.

Location::caller() has the signature pub const fn caller() -> &'static Location<'static>. A Location provides file(), line() and column(), and implements Display as file:line:column.

Errors and edge cases:

  • #[track_caller] is rejected on main and on functions with a non-Rust ABI such as extern "C".
  • Called from a function that is not #[track_caller], Location::caller() returns the location of that call expression.
  • The attribute is on the function, not on a call: a #[track_caller] function that calls another #[track_caller] function passes the original location along the chain.

Usage notes

  • Use #[track_caller] on small helpers that panic on misuse (custom unwrap-like methods, assertion helpers, test utilities) so the message points at the buggy call, not at the helper.
  • The attribute works on trait methods; an implementation overriding a #[track_caller] trait method should repeat it to keep the location through dynamic dispatch.
  • It costs one hidden extra argument (a pointer to a static Location). Avoid it on tiny hot functions that never panic.
  • #[cold] is a hint, not a promise. Marking a frequently called function cold can slow the program down, so measure first.
  • #[cold] is often paired with #[inline(never)] so the failure path is not copied into every caller.
  • Functions returning ! (like panic! wrappers) are good candidates for #[cold]; the standard library marks its own panic helpers this way.
  • Location::caller() is const, but in const code the result is the location of the const evaluation site.
  • Both attributes are stable; #[track_caller] has been stable since Rust 1.46.