Not long ago, when I first started working with Rust, lifetime parameters were one of the trickiest aspects to wrap my head around. What was this strange <'a> thing I saw at the beginning of some function and struct definitions, and what was it for?
I’m writing this post to solidify my own understanding of this unfamiliar feature, and hopefully it helps you, too. In it, I’ll cover:
- the problem lifetime parameters solve
- the places in Rust where lifetime parameters can be used, and what each location represents
- the use of lifetimes as bounds on both generic type parameters and other lifetime parameters
- the 'static lifetime
- lifetime elision (a set of rules that allow you to omit explicit lifetime parameters in all but the most ambiguous cases)
I assume the reader is familiar with the basics of ownership, borrowing, and references in Rust, as well as generic types; if not, the book is an excellent reference.
Let’s get started!
The Problem
Imagine that we have a hypothetical version of Rust without lifetimes on reference types, and we try to run this program:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
struct Coordinate { x: i32, y: i32 } fn get_x(c: &Coordinate) -> &i32 { &c.x } fn main() { let x; { let c = Coordinate { x: 1, y: 2 }; x = get_x(&c); } println!("{}", x); } |
At line 15, x would be assigned a reference to memory owned by the coordinate c (through the call to get_x). But at line 16, c would go out of scope, so its memory would be freed. That means that at line 18, x would point to invalid memory—a classic use-after-free error.
So why didn’t the compiler catch this? The problem is that without any extra information on the type signature for get_x, the compiler doesn’t know that the returned reference’s lifetime should be the same as the input reference’s. We could have, say, written a version of get_x that returns a reference with a completely different lifetime, like a reference to a constant.
A similar issue can occur with references stored inside structs. Consider if a similar struct that instead stored references to its x and y fields and we tried the following:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
struct RefCoordinate { x: &i32, y: &i32 } fn main() { let c; { let example_x = 1; let example_y = 2; c = RefCoordinate { x: &example_x, y: &example_y }; } println!("{}", c.x); } |
Again, running this program would cause a use-after-free error. In this case, example_x and example_y are freed when the block ends at line 13, so c.x at line 15 would reference a freed location in memory. For the compiler to catch this error before we run the program, we need to establish some sort of relationship between the lifetime of a RefCoordinate and of the references it contains.
As you’ve probably already guessed, lifetime parameters solve both problems.
The Basics of Explicit Lifetimes and Lifetime Parameters
Although they are not always made explicit, every reference type in Rust has an associated lifetime describing the scope in which the reference can be used.
In cases like the above, we do want to make the lifetimes explicit so that we can express, for example, that the reference returned by get_x has the same lifetime as the input argument, c . That would give the compiler enough information to know that the use of x at line 18 is invalid.
Rust does not provide a way to write down concrete lifetimes (e.g. there’s no way to express “the lifetime starting at line 13 and ending at line 16”), but typically that’s not what we want, anyway. Instead, we want to abstract over all possible lifetimes; this is what lifetime parameters provide.
Lifetime parameters are special generic parameters on items like functions and structs, much like generic type parameters. The parameters provide names for our lifetimes that can be used as explicit lifetimes in our reference types. To make this concrete, here is the program after adding the proper lifetime parameters to get_x:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
struct Coordinate { x: i32, y: i32 } fn get_x<'a>(c: &'a Coordinate) -> &'a i32 { &c.x } fn main() { let x; { let c = Coordinate { x: 1, y: 2 }; x = get_x(&c); } println!("{}", x); } |
Let’s break this down one step at a time. In general, 'a means “the lifetime a”, and &'a T is the type for a reference of type T with lifetime 'a (or &'a mut T for a mutable reference).
get_x has a single lifetime parameter, 'a, declared immediately after the name. c’s declared type says that it is a reference whose lifetime is 'a. This declaration does not change c’s lifetime; it only gives it a name so we can refer to it later. Finally, the return type &'a i32 says that get_x returns a reference to an i32, whose lifetime is the same as the input argument’s lifetime. In other words, from the caller’s perspective the returned reference is only usable as long as the input c is still in scope. With this information (and replacing our hypothetical, lifetime-ignoring Rust with the real thing), the compiler is able to report that our use of get_x is invalid, because c does not live long enough.
We could write the code like this instead to get a working program:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
struct Coordinate { x: i32, y: i32 } fn get_x<'a>(c: &'a Coordinate) -> &'a i32 { &c.x } fn main() { let c = Coordinate { x: 1, y: 2 }; let x = get_x(&c); println!("{}", x); } |
Structs work similarly, as seen in this lifetime-ified example of RefCoordinate :
|
1 2 3 4 |
struct RefCoordinate<'a> { x: &'a i32, y: &'a i32 } |
The struct Coordinate is now parameterized over a lifetime 'a, and its references are each declared to have that same lifetime 'a. In effect, this expresses the constraint that any reference to the struct may not outlive its contained references.
Lifetimes on Other Items
Traits can also have lifetime parameters, with the same syntax and meaning as structs:
|
1 2 3 |
trait GetXRef<'a> { fn get_x(&'a self) -> &'a i32; } |
Finally, when implementing methods in an impl block, the block itself can declare lifetime parameters to be used in the named struct or trait:
|
1 2 3 4 5 |
impl<'a> GetXRef<'a> for RefCoordinate<'a> { fn get_x(&self) -> &'a i32 { &self.x } } |
In general, lifetime parameters are declared as generic parameters on items like functions, structs, traits, and impls, and they are used both in reference types and as arguments to items that take generic parameters (as with GetXRef and RefCoordinate in the above example).
Bounded Lifetimes, Lifetimes as Bounds
If you’re familiar with advanced uses of generic types, you know that they can have bounds, as in fn foo<T: S>(x: T). Here the provided T must be a type that implements S.
Similarly, lifetimes can act as bounds to other lifetimes. A parameter like <'a: 'b> means “I expect some lifetime 'a that is at least as long as 'b”.
Addtionally, lifetimes can act as bounds on types. A type parameter such as <T: 'a> means “I expect some type T such that all references in T have a lifetime at least as long as 'a”.
Bounds in both cases can be combined using the + operator just as with normal type bounds.
The ‘static Lifetime
There is one particular lifetime in Rust that can be named without abstracting over it: the static lifetime, 'static. This is the lifetime for references that are alive throughout the entire execution of a program, such as references to string literals and global constants.
|
1 2 3 4 |
const A: i32 = 1; static B: i32 = 2; static C: &'static i32 = &A; static D: &'static i32 = &B; |
Lifetime Elision
Lifetime parameters provide the compiler with the extra information it requires to prevent use-after-free issues, but writing explicit lifetimes for every single reference type can be cumbersome, especially for obvious cases like this:
|
1 2 3 |
fn return_ref<'a>(s: &'a str) -> &'a str { s } |
We would rather write the following and have the compiler figure out where to insert the lifetime annotations:
|
1 2 3 |
fn return_ref(s: &str) -> &str { s } |
Fortunately, Rust has a simple set of rules, called the elision rules, that allow the programmer to elide (leave out) lifetime parameters in functions in the obvious cases (structs, however, must always use explicit lifetimes for their fields). The rules refer to input and output lifetimes, which simply refer to the lifetimes used in input types or return types, respectively. The rules are (as quoted from the book):
- Each elided lifetime in a function’s arguments becomes a distinct lifetime parameter.
- If there is exactly one input lifetime, elided or not, that lifetime is assigned to all elided lifetimes in the return values of that function.
- If there are multiple input lifetimes, but one of them is &self or &mut self, the lifetime of self is assigned to all elided output lifetimes.
Eliding any other output lifetimes is a compile-time error. The book has many more examples to help you understand the elision rules.
Summary
- Lifetime parameters abstract over the lifetimes used in type annotations and allow the programmer to express relationships between lifetimes.
- Lifetime parameters are declared as generic type parameters to functions, structs, traits, and impl blocks and can be used in reference types, struct types, and trait uses. They can also act as bounds on type and lifetime parameters.
- The 'static lifetime extends over the whole program and is used for constants and string literals.
- A simple set of lifetime elision rules allows programmers to omit explicit lifetimes in most cases.
Hopefully this has helped clear up one of the more confusing aspects of Rust’s type system. If you have questions I didn’t answer, please sound off in the comments. Happy hacking!