Rust for C-Programmers

11.3 Lifetimes: Ensuring Reference Validity

Lifetimes are Rust’s way of ensuring that references are always valid, preventing dangling pointers and use-after-free bugs at compile time. They are a form of static analysis where the compiler checks that references do not outlive the data they point to. Unlike C, where pointer validity is the programmer’s manual responsibility, Rust automates this verification.

Key Concepts

• Scope: Lifetimes relate to the scopes (regions of code) where references are valid.
• Annotations: Explicit lifetime annotations (e.g., 'a, 'b) connect the lifetimes of different references, often needed in function signatures and struct definitions involving references.
• Compile-Time Only: Lifetime checks happen entirely at compile time and have zero runtime cost. They don’t affect the generated machine code.
• Borrow Checker: Lifetimes are a core part of Rust’s borrow checker, the compiler component that enforces memory safety rules related to borrowing and ownership.

11.3.1 Lifetime Annotations Syntax

Lifetime parameters start with an apostrophe (') followed by a name, typically lowercase and short (e.g., 'a, 'b, 'input). The apostrophe is significant syntax that marks the name as a lifetime parameter, distinguishing it from type or variable names. The standard notation 'a is used consistently in Rust code and documentation.

Lifetime parameters are declared in angle brackets (<>) after function names, or within struct or enum definitions, or after the impl keyword when implementing methods for types with lifetimes.

// Function signature declaring and using explicit lifetime 'a
fn function_name<'a>(param: &'a str) -> &'a str { /* ... */ }

// Struct definition declaring a lifetime parameter 'a
// This indicates the struct holds a reference that must live at least as long as 'a.
struct StructName<'a> {
    // The field holds a reference to an i32 with lifetime 'a.
    field: &'a i32,
}

// Implementation block for a struct with lifetime 'a
// The lifetime must be declared again after 'impl'.
impl<'a> StructName<'a> {
    // Method signature using the struct's lifetime 'a.
    fn method_name(&self) -> &'a i32 { self.field }
}

Why Lifetimes on References to Copy Types (like &'a i32)?

You might wonder why a reference like &'a i32 needs a lifetime, given that i32 is a Copy type. It’s crucial to remember that lifetimes apply to references (borrows), not directly to the underlying data’s type semantics (Copy, Clone, etc.).

A reference (& or &mut) always borrows data from a specific memory location. The lifetime annotation ensures that this reference does not outlive the point where that memory location is no longer valid (e.g., because the variable owning the data went out of scope). Even if the data is simple like an i32, the reference &'a i32 points to a particular i32 instance residing somewhere (on the stack, in another struct, etc.). The lifetime 'a guarantees the reference is only used while that specific instance is validly allocated and accessible. The Copy trait means the i32 value can be easily duplicated, but it doesn’t affect the validity or scope of a borrow of a particular instance of that value in memory.

11.3.2 Lifetimes in Function Signatures

The most common place lifetimes need explicit annotation is in functions that take references as input and return references. The annotations tell the compiler how the lifetimes of the input references relate to the lifetime of the output reference, ensuring the returned reference doesn’t point to data that might go out of scope before the reference does.

Consider this function, which returns the longer of two string slices:

// This version won't compile without lifetimes!
// The compiler doesn't know if the returned reference lives as long as x or y.
// fn longest(x: &str, y: &str) -> &str { ... }

The compiler cannot know if the returned reference (&str) refers to x or y, and thus cannot determine if it will be valid after the function call. We need to add lifetime annotations to create a relationship:

// Correct version with lifetime annotations
fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    // The <'a> declares a lifetime parameter named 'a'.
    // 'x: &'a str' means x is a reference valid for at least the scope 'a'.
    // 'y: &'a str' means y is a reference valid for at least the scope 'a'.
    // '-> &'a str' means the returned reference is also valid for at least scope 'a'.

    if x.len() > y.len() {
        x
    } else {
        y
    }
}

fn main() {
    let string1 = String::from("abc"); // Shorter string in outer scope
    let result;
    { // Inner scope starts
        let string2 = String::from("xyzpdq - longer string"); // Longer string in inner scope
        
        // Call longest using modern &String coercion to &str
        // The compiler infers a concrete lifetime for 'a'. This lifetime cannot
        // be longer than the lifetime of string1 *or* the lifetime of string2.
        // Therefore, 'a' is effectively constrained by the shorter lifetime,
        // which is that of string2 (the inner scope).
        result = longest(&string1, &string2);

        // Inside this inner scope, both string1 and string2 are valid.
        // Since string2 is longer, 'result' now holds a reference to string2's data.
        println!("The longest string is: {}", result); // OK: result is valid here
        
    } // Inner scope ends, string2 is dropped and its memory is potentially deallocated.

    // println!("The longest string is: {}", result); // Compile-time Error!
    // Error: `string2` does not live long enough.
}

Explanation of the Lifetime Constraint:

It’s crucial to understand why the compiler flags the commented-out println! as an error. The longest function’s signature fn longest<'a>(x: &'a str, y: &'a str) -> &'a str tells the compiler: “This function takes two string slices that are both valid for some lifetime 'a, and it returns a string slice that is also valid for that same lifetime 'a.”

At the call site longest(&string1, &string2), the compiler determines the actual scope that 'a represents. It must be a scope for which both &string1 and &string2 are valid. In our example, &string1 is valid for the entire main function, but &string2 is only valid inside the inner {} block. The intersection of these two validity periods is the inner block’s scope. Therefore, the concrete lifetime assigned to 'a for this call is the scope of the inner block.

The signature promises that the returned reference (result) is valid for this lifetime 'a. The compiler enforces this regardless of which string happens to be longer at runtime. It cannot predict whether the if condition x.len() > y.len() will be true or false; that depends on runtime values. Since the function could return a reference tied to x or could return one tied to y, the returned reference must be assumed to potentially come from the input with the shorter lifetime to guarantee safety.

In our example, string2 has the shorter lifetime (the inner scope) and also happens to be the longer string. So, result refers to string2. When the inner scope ends, string2 is dropped. The lifetime 'a associated with result also ends. Attempting to use result after this point would mean accessing memory that is no longer guaranteed to be valid (a use-after-free error), which the borrow checker correctly prevents at compile time.

11.3.3 Lifetime Elision Rules

In many common cases, the compiler can infer lifetimes automatically based on a set of lifetime elision rules, making explicit annotations unnecessary. If your code compiles without explicit lifetimes, it’s because the compiler applied these rules successfully.

The main elision rules are:

1. Input Lifetimes: Each reference parameter in a function’s input gets its own distinct lifetime parameter. fn foo(x: &i32, y: &str) is treated like fn foo<'a, 'b>(x: &'a i32, y: &'b str).
2. Single Input Lifetime: If there is exactly one input lifetime parameter (after applying rule 1), that lifetime is assigned to all output reference parameters. fn bar(x: &i32) -> &i32 is treated like fn bar<'a>(x: &'a i32) -> &'a i32.
3. Method Lifetimes: If there are multiple input lifetime parameters, but one of them is &self or &mut self (i.e., it’s a method on a struct or enum), the lifetime of self is assigned to all output reference parameters. fn baz(&self, x: &str) -> &str is treated like fn baz<'a, 'b>(&'a self, x: &'b str) -> &'a str.

These rules cover many simple patterns. You typically only need explicit annotations when these rules are insufficient for the compiler to determine the lifetime relationships unambiguously (like in the longest example, which has two input references and one output reference, not covered by rule 2 or 3).

11.3.4 Lifetimes in Struct Definitions

If a struct holds references within its fields, you must annotate the struct definition with lifetime parameters. These parameters link the lifetime of the struct instance to the lifetime of the data being referenced by its fields.

// An Excerpt struct holding a reference to a part of a string ('str').
// The lifetime parameter 'a is declared on the struct name.
struct Excerpt<'a> {
    // The 'part' field holds a reference tied to the lifetime 'a.
    // This means the data referenced by 'part' must live at least as long as 'a.
    part: &'a str,
}

// When implementing methods for a struct with lifetimes, declare them after 'impl'.
impl<'a> Excerpt<'a> {
    // Method returning the held reference.
    // Lifetime elision rule #3 applies because of '&self'.
    // The return type implicitly gets the lifetime of '&self', which is 'a.
    fn get_part(&self) -> &str { // Implicitly -> &'a str
        self.part
    }
}

fn main() {
    let novel = String::from("Call me Ishmael. Some years ago...");
    // first_sentence is a reference (&str) borrowing from 'novel'.
    // Its lifetime is tied to the scope of 'novel'.
    let first_sentence = novel.split('.').next().expect("Could not find a '.'");

    // Create an Excerpt instance. 'i' borrows 'first_sentence'.
    // The lifetime 'a for this instance 'i' is inferred by the compiler
    // to be tied to the lifetime of 'first_sentence'.
    let i = Excerpt { part: first_sentence };

    // The Excerpt instance 'i' cannot outlive the data it references ('novel').
    // If 'novel' went out of scope before this line, it would be a compile error.
    println!("Excerpt part: {}", i.get_part());
}

The lifetime parameter 'a on Excerpt ensures that an Excerpt instance cannot be used after the data (novel in this case) it borrows from goes out of scope, preventing dangling references.

11.3.5 The 'static Lifetime

The special lifetime 'static indicates that a reference is valid for the entire duration of the program. All string literals ("hello") have a 'static lifetime because their data is embedded directly into the program’s binary and is always available.

#![allow(unused)]
fn main() {
// 's' is a reference to a string literal, hence its lifetime is 'static.
let s: &'static str = "I live for the entire program execution.";
}

You might also encounter 'static as a trait bound (e.g., T: 'static). This bound means that the type T contains no references except possibly 'static ones. It effectively means the type owns all its data or only holds references that live forever. This is common for types that need to be sent between threads or stored for potentially long durations where shorter borrows wouldn’t be valid. Use 'static judiciously, as requiring it can limit flexibility where shorter-lived references would suffice.

11.3.6 Lifetimes with Generics and Traits

Lifetimes, generics, and traits often work together in function signatures and type definitions. When declaring parameters, lifetime parameters are listed first, followed by generic type parameters.

use std::fmt::Display;

// Function generic over lifetime 'a and type T.
// Requires T to implement Display.
// Takes an announcement of type T and text reference with lifetime 'a.
// Returns a string slice reference, also tied to lifetime 'a.
fn announce_and_return_part<'a, T>(announcement: T, text: &'a str) -> &'a str
where
    T: Display, // Trait bound using 'where' clause
{
    println!("Announcement: {}", announcement);
    // Assume we take the first 5 bytes for simplicity
    if text.len() >= 5 {
        &text[0..5]
    } else {
        text // Return the whole slice if shorter than 5 bytes
    }
}

fn main() {
    let message = String::from("Important News!"); // Owned String
    let content = String::from("Rust 1.80 released today."); // Owned String

    // 'message' is moved into the function.
    // '&content' is passed as a reference. The lifetime 'a is inferred from '&content'.
    let part = announce_and_return_part(message, &content);
    // 'part' is a reference (&str) whose lifetime is tied to that of 'content'.
    // If 'content' were dropped before this line, using 'part' would be an error.
    println!("Returned part: {}", part);

    // Note: 'message' was moved and cannot be used here anymore.
    // println!("{}", message); // Error: value borrowed here after move
}