Skip to content

Commit cb90723

Browse files
committed
Explain motivation behind lifetimes
Start the lifetime section with an explanation of the issues that lack of explicit lifetimes cause and how lifetimes alleviate these.
1 parent acb50e3 commit cb90723

File tree

1 file changed

+76
-14
lines changed

1 file changed

+76
-14
lines changed

src/doc/book/lifetimes.md

+76-14
Original file line numberDiff line numberDiff line change
@@ -50,11 +50,78 @@ complicated. For example, imagine this set of operations:
5050
4. You decide to use the resource.
5151

5252
Uh oh! Your reference is pointing to an invalid resource. This is called a
53-
dangling pointer or ‘use after free’, when the resource is memory.
53+
dangling pointer or ‘use after free’, when the resource is memory. A small
54+
example of such a situation would be:
55+
56+
```rust,compile_fail
57+
let r; // Introduce reference: r
58+
{
59+
let i = 1; // Introduce scoped value: i
60+
r = &i; // Store reference of i in r
61+
} // i goes out of scope and is dropped.
62+
63+
println!("{}", r); // r still refers to i
64+
```
5465

5566
To fix this, we have to make sure that step four never happens after step
56-
three. The ownership system in Rust does this through a concept called
57-
lifetimes, which describe the scope that a reference is valid for.
67+
three. In the small example above the Rust compiler is able to report the issue
68+
as it can see the lifetimes of the various values in the function.
69+
70+
When we have a function that takes arguments by reference the situation becomes
71+
more complex. Consider the following example:
72+
73+
```rust,compile_fail,E0106
74+
fn skip_prefix(line: &str, prefix: &str) -> &str {
75+
// ...
76+
# line
77+
}
78+
79+
let line = "lang:en=Hello World!";
80+
let lang = "en";
81+
82+
let v;
83+
{
84+
let p = format!("lang:{}=", lang); // -+ p goes into scope
85+
v = skip_prefix(line, p.as_str()); // |
86+
} // -+ p goes out of scope
87+
println!("{}", v);
88+
```
89+
90+
Here we have a function `skip_prefix` which takes two `&str` references
91+
as parameters and returns a single `&str` reference. We call it
92+
by passing in references to `line` and `p`: Two variables with different
93+
lifetimes. Now the safety of the `println!`-line depends on whether the
94+
reference returned by `skip_prefix` function references the still living
95+
`line` or the already dropped `p` string.
96+
97+
Because of the above ambiguity, Rust will refuse to compile the example
98+
code. To get it to compile we need to tell the compiler more about the
99+
lifetimes of the references. This can be done by making the lifetimes
100+
explicit in the function declaration:
101+
102+
```rust
103+
fn skip_prefix<'a, 'b>(line: &'a str, prefix: &'b str) -> &'a str {
104+
// ...
105+
# line
106+
}
107+
```
108+
109+
Let's examine the changes without going too deep into the syntax for now -
110+
we'll get to that later. The first change was adding the `<'a, 'b>` after the
111+
method name. This introduces two lifetime parameters: `'a` and `'b`. Next each
112+
reference in the function signature was associated with one of the lifetime
113+
parameters by adding the lifetime name after the `&`. This tells the compiler
114+
how the lifetimes between different references are related.
115+
116+
As a result the compiler is now able to deduce that the return value of
117+
`skip_prefix` has the same lifetime as the `line` parameter, which makes the `v`
118+
reference safe to use even after the `p` goes out of scope in the original
119+
example.
120+
121+
In addition to the compiler being able to validate the usage of `skip_prefix`
122+
return value, it can also ensure that the implementation follows the contract
123+
established by the function declaration. This is useful especially when you are
124+
implementing traits that are introduced [later in the book][traits].
58125

59126
**Note** It's important to understand that lifetime annotations are
60127
_descriptive_, not _prescriptive_. This means that how long a reference is valid
@@ -63,20 +130,14 @@ give information about lifetimes to the compiler that uses them to check the
63130
validity of references. The compiler can do so without annotations in simple
64131
cases, but needs the programmers support in complex scenarios.
65132

66-
```rust
67-
// implicit
68-
fn foo(x: &i32) {
69-
}
133+
[traits]: traits.html
70134

71-
// explicit
72-
fn bar<'a>(x: &'a i32) {
73-
}
74-
```
135+
# Syntax
75136

76137
The `'a` reads ‘the lifetime a’. Technically, every reference has some lifetime
77138
associated with it, but the compiler lets you elide (i.e. omit, see
78-
["Lifetime Elision"][lifetime-elision] below) them in common cases.
79-
Before we get to that, though, let’s break the explicit example down:
139+
["Lifetime Elision"][lifetime-elision] below) them in common cases. Before we
140+
get to that, though, let’s look at a short example with explicit lifetimes:
80141

81142
[lifetime-elision]: #lifetime-elision
82143

@@ -94,7 +155,8 @@ focus on the lifetimes aspect.
94155
[generics]: generics.html
95156

96157
We use `<>` to declare our lifetimes. This says that `bar` has one lifetime,
97-
`'a`. If we had two reference parameters, it would look like this:
158+
`'a`. If we had two reference parameters with different lifetimes, it would
159+
look like this:
98160

99161

100162
```rust,ignore

0 commit comments

Comments
 (0)