Lifetimes are one of Rust’s most distinctive and initially challenging features. While other aspects of Rust’s ownership system deal with who owns a value, lifetimes address how long references to that value remain valid. This mechanism ensures memory safety without a garbage collector by validating at compile time that no reference outlives the data it points to—a common source of bugs in languages like C and C++.
In this comprehensive guide, we’ll explore Rust’s lifetime system in depth, from basic concepts to advanced patterns. You’ll learn how lifetimes work, when and how to use lifetime annotations, and techniques for handling complex borrowing scenarios. By the end, you’ll have a solid understanding of how lifetimes contribute to Rust’s memory safety guarantees and how to leverage them effectively in your code.
Understanding Lifetimes: The Basics
At their core, lifetimes are about ensuring that references are valid for as long as they’re used. Let’s start with the fundamental concepts:
What Are Lifetimes?
A lifetime is a construct the Rust compiler uses to track how long references are valid. Every reference in Rust has a lifetime, which is the scope for which that reference is valid.
fn main() {
let x = 5; // ----------+-- 'b
// |
let r = &x; // --+-- 'a |
// | |
println!("r: {}", r); // | |
// --+ |
} // ----------+
In this example, the reference r has a lifetime 'a that is shorter than the lifetime 'b of the value x. This is safe because the reference doesn’t outlive the value it points to.
Preventing Dangling References
The primary purpose of lifetimes is to prevent dangling references—references that point to memory that has been freed:
fn main() {
let r; // ---------+-- 'a
// |
{ // |
let x = 5; // -+-- 'b |
r = &x; // | |
} // -+ |
// |
println!("r: {}", r); // |
} // ---------+
This code won’t compile because the reference r would outlive the value x it points to. The Rust compiler prevents this at compile time, avoiding a potential use-after-free bug.
Lifetime Annotations in Function Signatures
While the Rust compiler can infer lifetimes in many cases, sometimes you need to explicitly annotate them, particularly in function signatures:
Basic Lifetime Annotations
// Without lifetime annotations (won't compile)
fn longest(x: &str, y: &str) -> &str {
if x.len() > y.len() {
x
} else {
y
}
}
// With lifetime annotations
fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
if x.len() > y.len() {
x
} else {
y
}
}
fn main() {
let string1 = String::from("long string is long");
let string2 = String::from("xyz");
let result = longest(string1.as_str(), string2.as_str());
println!("The longest string is {}", result);
}
The lifetime annotation 'a in the function signature tells the compiler that all the references share the same lifetime, and the returned reference will be valid for at least as long as the shorter of the two input references.
Multiple Lifetime Parameters
Functions can have multiple lifetime parameters:
fn longest_with_announcement<'a, 'b>(
x: &'a str,
y: &'a str,
announcement: &'b str,
) -> &'a str {
println!("Announcement: {}", announcement);
if x.len() > y.len() {
x
} else {
y
}
}
fn main() {
let string1 = String::from("long string is long");
let string2 = String::from("xyz");
let announcement = String::from("Today's winner is...");
let result = longest_with_announcement(
string1.as_str(),
string2.as_str(),
announcement.as_str(),
);
println!("The longest string is {}", result);
}
Here, 'a and 'b are different lifetime parameters. The returned reference has the lifetime 'a, which is independent of the lifetime 'b of the announcement parameter.
Lifetime Elision Rules
To reduce boilerplate, Rust has lifetime elision rules that allow the compiler to infer lifetimes in common patterns:
The Three Rules
- Each parameter that is a reference gets its own lifetime parameter.
- If there is exactly one input lifetime parameter, that lifetime is assigned to all output lifetime parameters.
- If there are multiple input lifetime parameters, but one of them is
&selfor&mut self, the lifetime ofselfis assigned to all output lifetime parameters.
// These function signatures are equivalent
fn first_word(s: &str) -> &str;
fn first_word<'a>(s: &'a str) -> &'a str;
// These are also equivalent
fn longest(x: &str, y: &str) -> &str; // Won't compile without annotations
fn longest<'a, 'b>(x: &'a str, y: &'b str) -> &str; // Still won't compile
fn longest<'a>(x: &'a str, y: &'a str) -> &'a str; // Correct annotation
The first function compiles without explicit lifetime annotations because of the elision rules, but the second function requires annotations because the compiler can’t determine which input lifetime should be assigned to the output.
Lifetimes in Structs and Implementations
Structs and implementations can also have lifetime parameters:
Structs with References
struct ImportantExcerpt<'a> {
part: &'a str,
}
fn main() {
let novel = String::from("Call me Ishmael. Some years ago...");
let first_sentence = novel.split('.').next().unwrap();
let excerpt = ImportantExcerpt {
part: first_sentence,
};
println!("Excerpt: {}", excerpt.part);
}
The struct ImportantExcerpt holds a reference to a string, so it needs a lifetime parameter to ensure that the reference doesn’t outlive the string it points to.
Implementations with Lifetimes
struct ImportantExcerpt<'a> {
part: &'a str,
}
impl<'a> ImportantExcerpt<'a> {
fn level(&self) -> i32 {
3
}
fn announce_and_return_part(&self, announcement: &str) -> &str {
println!("Attention please: {}", announcement);
self.part
}
}
fn main() {
let novel = String::from("Call me Ishmael. Some years ago...");
let first_sentence = novel.split('.').next().unwrap();
let excerpt = ImportantExcerpt {
part: first_sentence,
};
println!("Excerpt level: {}", excerpt.level());
println!("Excerpt part: {}", excerpt.announce_and_return_part("Important news!"));
}
The implementation block needs the lifetime parameter 'a to match the struct definition. The level method doesn’t need to specify the lifetime because of the third elision rule (the lifetime of self is assigned to all output lifetime parameters). The announce_and_return_part method also benefits from this rule.
The Static Lifetime
The 'static lifetime is special—it means the reference can live for the entire duration of the program:
let s: &'static str = "I have a static lifetime.";
String literals have a 'static lifetime because they’re stored in the program’s binary and are always available.
When to Use ‘static
The 'static lifetime should be used sparingly. It’s often a sign that you’re trying to force the compiler to accept code that has lifetime issues:
// Avoid this pattern
fn return_static_str() -> &'static str {
"This is a static string"
}
// This is fine because string literals are 'static
fn return_static_str_good() -> &'static str {
"This is a static string"
}
// But this would be a mistake
fn return_static_str_bad() -> &'static str {
let s = String::from("This is not static");
&s[..] // This would cause a dangling reference
}
Advanced Lifetime Patterns
As you work with more complex Rust code, you’ll encounter more advanced lifetime patterns:
Lifetime Bounds
Just as you can constrain generic types with trait bounds, you can constrain lifetime parameters:
use std::fmt::Display;
fn longest_with_an_announcement<'a, T>(
x: &'a str,
y: &'a str,
announcement: T,
) -> &'a str
where
T: Display,
{
println!("Announcement: {}", announcement);
if x.len() > y.len() {
x
} else {
y
}
}
fn main() {
let string1 = String::from("long string is long");
let string2 = String::from("xyz");
let result = longest_with_an_announcement(
string1.as_str(),
string2.as_str(),
"Today's winner is...",
);
println!("The longest string is {}", result);
}
Higher-Ranked Trait Bounds (HRTB)
Sometimes you need to express that a function works with any lifetime, not just a specific one:
fn call_with_ref<F>(f: F)
where
F: for<'a> Fn(&'a str) -> bool,
{
let result = f("hello");
println!("Result: {}", result);
}
fn main() {
let check_len = |s: &str| s.len() > 3;
call_with_ref(check_len);
}
The for<'a> syntax is a higher-ranked trait bound, indicating that F must implement Fn(&'a str) -> bool for any lifetime 'a, not just a specific one.
Variance
Variance determines how subtyping relationships between types are affected by lifetimes:
struct Immutable<'a> {
x: &'a i32,
}
struct Mutable<'a> {
x: &'a mut i32,
}
fn main() {
let mut data = 10;
// Covariance: 'longer can be used where 'shorter is expected
{
let longer = &data; // 'longer
let immutable = Immutable { x: longer };
{
let shorter = &data; // 'shorter
process_immutable(immutable); // This works
}
}
// Invariance: 'longer cannot be used where 'shorter is expected for mutable references
{
let mut longer_data = 20;
let longer = &mut longer_data; // 'longer
let mutable = Mutable { x: longer };
{
let mut shorter_data = 30;
let shorter = &mut shorter_data; // 'shorter
// process_mutable(mutable); // This would not compile
}
}
}
fn process_immutable(immutable: Immutable) {
println!("Processing immutable: {}", immutable.x);
}
fn process_mutable(mutable: Mutable) {
println!("Processing mutable: {}", mutable.x);
}
Immutable references are covariant, meaning a longer lifetime can be used where a shorter one is expected. Mutable references are invariant, meaning the lifetimes must match exactly.
Lifetime Challenges and Solutions
Let’s explore some common lifetime challenges and their solutions:
Returning References from Functions
One common challenge is returning references from functions when the data is created within the function:
// This won't compile
fn create_and_return_reference() -> &str {
let s = String::from("hello");
&s[..] // Error: returns a reference to data owned by the current function
}
Solutions:
- Return an owned value instead of a reference:
fn create_and_return_owned() -> String {
String::from("hello")
}
- Take a mutable reference as a parameter:
fn create_and_store_reference(output: &mut String) {
output.clear();
output.push_str("hello");
}
fn main() {
let mut result = String::new();
create_and_store_reference(&mut result);
println!("Result: {}", result);
}
Self-Referential Structs
Creating structs that contain references to their own fields is challenging:
struct SelfReferential {
value: String,
pointer: &String, // Error: needs a lifetime parameter
}
Solutions:
- Use indices instead of references:
struct NotSelfReferential {
values: Vec<String>,
index: usize,
}
impl NotSelfReferential {
fn new(value: String) -> Self {
let mut values = Vec::new();
values.push(value);
NotSelfReferential {
values,
index: 0,
}
}
fn value(&self) -> &str {
&self.values[self.index]
}
}
- Use the
ouroboroscrate:
use ouroboros::self_referencing;
#[self_referencing]
struct SelfReferential {
value: String,
#[borrows(value)]
pointer: &'this String,
}
fn main() {
let sr = SelfReferentialBuilder {
value: String::from("hello"),
pointer_builder: |value| value,
}.build();
sr.with_pointer(|pointer| {
println!("Pointer: {}", pointer);
});
}
Mixing Lifetimes and Generic Types
Combining lifetimes with generic types can lead to complex signatures:
struct Wrapper<'a, T> {
value: &'a T,
}
impl<'a, T> Wrapper<'a, T> {
fn new(value: &'a T) -> Self {
Wrapper { value }
}
}
trait Processor {
fn process(&self) -> String;
}
impl<'a, T> Processor for Wrapper<'a, T>
where
T: std::fmt::Display,
{
fn process(&self) -> String {
format!("Processed: {}", self.value)
}
}
fn main() {
let value = 42;
let wrapper = Wrapper::new(&value);
println!("{}", wrapper.process());
}
Lifetime Annotations in Closures
Closures can capture references with specific lifetimes:
fn create_closure<'a>(s: &'a str) -> impl Fn() -> &'a str {
move || s
}
fn main() {
let s = String::from("hello");
let closure = create_closure(&s);
println!("Closure returns: {}", closure());
}
The closure returned by create_closure captures a reference to s with the lifetime 'a, and the closure itself is annotated to return a reference with the same lifetime.
Lifetime Subtyping
Lifetime subtyping allows you to express that one lifetime is at least as long as another:
struct Context<'s>(&'s str);
struct Parser<'c, 's: 'c> {
context: &'c Context<'s>,
}
impl<'c, 's> Parser<'c, 's> {
fn parse(&self) -> Result<(), &'s str> {
Err(&self.context.0[1..])
}
}
fn parse_context(context: Context) -> Result<(), &str> {
Parser { context: &context }.parse()
}
fn main() {
let s = String::from("context string");
let context = Context(&s);
let result = parse_context(context);
match result {
Ok(()) => println!("Parsing succeeded"),
Err(err) => println!("Parsing failed: {}", err),
}
}
The notation 's: 'c means that the lifetime 's outlives the lifetime 'c—in other words, 's is at least as long as 'c.
Reborrowing
Reborrowing occurs when you borrow a reference that was itself borrowed:
fn main() {
let mut data = 10;
let ref1 = &mut data; // Mutable borrow
let ref2 = &*ref1; // Reborrow as immutable
println!("ref2: {}", ref2);
// Now we can use ref1 again because ref2 is no longer used
*ref1 += 1;
println!("ref1: {}", ref1);
}
Reborrowing is useful when you need to temporarily convert a mutable reference to an immutable one, or when you need to pass a reference to a function that expects a shorter lifetime.
Non-Lexical Lifetimes (NLL)
Rust’s borrow checker has been improved with non-lexical lifetimes, which end the lifetime of a borrow at the last use of the borrowed value, rather than at the end of the lexical scope:
fn main() {
let mut data = vec![1, 2, 3];
// Before NLL, this would not compile
let slice = &data[..];
println!("Slice: {:?}", slice);
// Now this works because the borrow ends after the last use of 'slice'
data.push(4);
println!("Data: {:?}", data);
}
Best Practices for Working with Lifetimes
Based on experience from large Rust projects, here are some best practices:
1. Minimize Lifetime Annotations
Let the compiler infer lifetimes when possible:
// Prefer this
fn first_word(s: &str) -> &str {
// ...
}
// Over this
fn first_word<'a>(s: &'a str) -> &'a str {
// ...
}
2. Use Owned Types When References Are Too Complex
If you find yourself fighting with the borrow checker, consider using owned types:
// Instead of complex lifetime annotations
fn complex_function<'a, 'b>(x: &'a str, y: &'b str) -> Result<&'a str, &'b str> {
// ...
}
// Consider using owned types
fn simpler_function(x: String, y: String) -> Result<String, String> {
// ...
}
3. Prefer Passing References to Taking Ownership
When a function doesn’t need to own a value, prefer passing references:
// Prefer this
fn process(data: &[i32]) {
// ...
}
// Over this
fn process(data: Vec<i32>) {
// ...
}
4. Use Scopes to Control Lifetimes
You can use blocks to create scopes that limit the lifetime of references:
fn main() {
let mut data = vec![1, 2, 3];
{
let slice = &data[..];
println!("Slice: {:?}", slice);
} // slice's lifetime ends here
// Now we can mutate data
data.push(4);
println!("Data: {:?}", data);
}
5. Understand the Relationship Between Lifetimes and Ownership
Lifetimes are about references, not about the values themselves:
fn main() {
let s1 = String::from("hello");
{
let s2 = String::from("world");
let result = longest(s1.as_str(), s2.as_str());
println!("The longest string is {}", result);
} // s2 is dropped here, but s1 is still valid
// We can still use s1
println!("s1: {}", s1);
}
fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
if x.len() > y.len() {
x
} else {
y
}
}
Real-World Examples
Let’s look at some real-world examples of lifetimes in action:
A Simple Parser
struct Parser<'a> {
input: &'a str,
position: usize,
}
impl<'a> Parser<'a> {
fn new(input: &'a str) -> Self {
Parser {
input,
position: 0,
}
}
fn peek(&self) -> Option<char> {
self.input[self.position..].chars().next()
}
fn consume(&mut self) -> Option<char> {
let c = self.peek()?;
self.position += c.len_utf8();
Some(c)
}
fn parse_word(&mut self) -> Option<&'a str> {
let start = self.position;
while let Some(c) = self.peek() {
if c.is_alphabetic() {
self.consume();
} else {
break;
}
}
if start == self.position {
None
} else {
Some(&self.input[start..self.position])
}
}
}
fn main() {
let input = "Hello, world!";
let mut parser = Parser::new(input);
if let Some(word) = parser.parse_word() {
println!("Parsed word: {}", word);
}
}
A Configuration Manager
struct Config<'a> {
database_url: &'a str,
api_key: &'a str,
timeout: u32,
}
struct ConfigBuilder<'a> {
database_url: Option<&'a str>,
api_key: Option<&'a str>,
timeout: Option<u32>,
}
impl<'a> ConfigBuilder<'a> {
fn new() -> Self {
ConfigBuilder {
database_url: None,
api_key: None,
timeout: None,
}
}
fn database_url(mut self, url: &'a str) -> Self {
self.database_url = Some(url);
self
}
fn api_key(mut self, key: &'a str) -> Self {
self.api_key = Some(key);
self
}
fn timeout(mut self, timeout: u32) -> Self {
self.timeout = Some(timeout);
self
}
fn build(self) -> Result<Config<'a>, &'static str> {
let database_url = self.database_url.ok_or("database_url is required")?;
let api_key = self.api_key.ok_or("api_key is required")?;
let timeout = self.timeout.unwrap_or(30);
Ok(Config {
database_url,
api_key,
timeout,
})
}
}
fn main() {
let database_url = String::from("postgres://localhost/mydb");
let api_key = String::from("secret-key");
let config = ConfigBuilder::new()
.database_url(&database_url)
.api_key(&api_key)
.timeout(60)
.build()
.expect("Failed to build config");
println!("Database URL: {}", config.database_url);
println!("API Key: {}", config.api_key);
println!("Timeout: {}", config.timeout);
}
Conclusion
Rust’s lifetime system is a powerful tool for ensuring memory safety without a garbage collector. By tracking the validity of references at compile time, Rust prevents common bugs like use-after-free and dangling pointers that plague languages with manual memory management.
While lifetimes can be challenging to understand at first, they become more intuitive with practice. The key insights to remember are:
- Lifetimes ensure references don’t outlive the data they point to
- Most lifetimes are inferred by the compiler, but sometimes you need to annotate them explicitly
- Lifetime annotations don’t change how long values live; they just describe the relationships between the lifetimes of multiple references
- The borrow checker enforces these relationships to prevent memory safety violations
By mastering lifetimes, you gain the ability to write code that is both safe and efficient, leveraging Rust’s unique approach to memory management. This understanding is essential for building complex Rust applications that maintain the language’s guarantees of memory safety without sacrificing performance.
