Attributes and Conditional Compilation

#[cold]

#[cold] is a code-generation hint attribute on a function or method that tells the compiler and LLVM backend that the function is unlikely to be called during normal execution (such as panic handlers, error-formatting routines, or slow reallocation fallback paths).

Three Optimizations Triggered by #[cold]

Marking a function #[cold] changes how the compiler optimizes both the function itself and every caller that branches to it:

  1. Branch prediction layout in callers (unlikely branch hint): Any if or match arm in a caller that leads unconditionally to a #[cold] function is treated as the unlikely branch. The compiler places the fast path as the straight-line fallthrough instruction sequence and moves the jump to the #[cold] branch out of line.
  2. Inlining suppression: LLVM avoids inlining #[cold] functions into hot callers so error-handling instructions do not pollute the L1 instruction cache or consume CPU registers in the fast path.
  3. Code-section placement and size optimization: The body of a #[cold] function is optimized for smaller binary size rather than raw loop unrolling speed, and can be placed into cold code pages so hot code pages pack more densely in RAM.
Hot Caller With Out-of-Line `#[cold]` Error Handler:

  Hot Instruction Cache Line (Fallthrough Fast Path):
    cmp   rdi, rsi          ; check index < len
    jae   .L_cold_oob       ; conditional jump to cold block (predicted NOT taken)
    mov   eax, [rdx + rdi*4]; fast-path load executes immediately!
    ret

  Cold Code Region (Far Away from Hot Loop):
  .L_cold_oob:
    call  handle_out_of_bounds_error   ; #[cold] #[inline(never)]

Pairing #[cold] with #[inline(never)] on Slow Fallback Paths

In performance-critical data structures (for example, Vec::push when len == cap or a parser encountering a syntax error), extracting the slow path into a separate helper annotated with both #[cold] and #[inline(never)] keeps the hot fast-path function tiny enough to be inlined into callers:

#[derive(Debug)]
pub struct ParseError {
    pub message: String,
}

// Extracting the string-formatting error construction into a `#[cold]` helper
// keeps `parse_header_byte` tiny and branch-friendly on the fast path:
#[cold]
#[inline(never)]
fn make_invalid_magic_error(found: u8, offset: usize) -> ParseError {
    ParseError {
        message: format!(
            "invalid magic byte {:#04x} at byte offset {} (expected 0x7F)",
            found, offset
        ),
    }
}

#[inline]
pub fn verify_magic_byte(buf: &[u8], offset: usize) -> Result<u8, ParseError> {
    let byte = buf.get(offset).copied().unwrap_or(0);
    if byte == 0x7F {
        Ok(byte)
    } else {
        // Because `make_invalid_magic_error` is `#[cold]`, LLVM automatically
        // marks this `else` branch as unlikely!
        Err(make_invalid_magic_error(byte, offset))
    }
}

fn main() {
    println!("valid:   {:?}", verify_magic_byte(&[0x7F, 0x01], 0));
    println!("invalid: {:?}", verify_magic_byte(&[0x00, 0x01], 0));
}

valid:   Ok(127)
invalid: Err(ParseError { message: "invalid magic byte 0x00 at byte offset 0 (expected 0x7F)" })