1 % The Rust Pointer Guide
3 Rust's pointers are one of its more unique and compelling features. Pointers
4 are also one of the more confusing topics for newcomers to Rust. They can also
5 be confusing for people coming from other languages that support pointers, such
6 as C++. This guide will help you understand this important topic.
8 Be sceptical of non-reference pointers in Rust: use them for a deliberate
9 purpose, not just to make the compiler happy. Each pointer type comes with an
10 explanation about when they are appropriate to use. Default to references
11 unless you're in one of those specific situations.
13 You may be interested in the [cheat sheet](#cheat-sheet), which gives a quick
14 overview of the types, names, and purpose of the various pointers.
18 If you aren't familiar with the concept of pointers, here's a short
19 introduction. Pointers are a very fundamental concept in systems programming
20 languages, so it's important to understand them.
24 When you create a new variable binding, you're giving a name to a value that's
25 stored at a particular location on the stack. (If you're not familiar with the
26 "heap" vs. "stack", please check out [this Stack Overflow
27 question](http://stackoverflow.com/questions/79923/what-and-where-are-the-stack-and-heap),
28 as the rest of this guide assumes you know the difference.) Like this:
39 We're making up memory locations here, they're just sample values. Anyway, the
40 point is that `x`, the name we're using for our variable, corresponds to the
41 memory location `0xd3e030`, and the value at that location is `5`. When we
42 refer to `x`, we get the corresponding value. Hence, `x` is `5`.
44 Let's introduce a pointer. In some languages, there is just one type of
45 'pointer,' but in Rust, we have many types. In this case, we'll use a Rust
46 **reference**, which is the simplest kind of pointer.
54 |-------- |----------|
57 |0xd3e020 | 0xd3e028 |
59 See the difference? Rather than contain a value, the value of a pointer is a
60 location in memory. In this case, the location of `y`. `x` and `y` have the
61 type `int`, but `z` has the type `&int`. We can print this location using the
72 This would print `0xd3e028`, with our fictional memory addresses.
74 Because `int` and `&int` are different types, we can't, for example, add them
82 println!("{}", x + z);
85 This gives us an error:
88 hello.rs:6:24: 6:25 error: mismatched types: expected `int` but found `&int` (expected int but found &-ptr)
89 hello.rs:6 println!("{}", x + z);
93 We can **dereference** the pointer by using the `*` operator. Dereferencing a
94 pointer means accessing the value at the location stored in the pointer. This
102 println!("{}", x + *z);
107 That's it! That's all pointers are: they point to some memory location. Not
108 much else to them. Now that we've discussed the 'what' of pointers, let's
109 talk about the 'why.'
113 Rust's pointers are quite useful, but in different ways than in other systems
114 languages. We'll talk about best practices for Rust pointers later in
115 the guide, but here are some ways that pointers are useful in other languages:
117 In C, strings are a pointer to a list of `char`s, ending with a null byte.
118 The only way to use strings is to get quite familiar with pointers.
120 Pointers are useful to point to memory locations that are not on the stack. For
121 example, our example used two stack variables, so we were able to give them
122 names. But if we allocated some heap memory, we wouldn't have that name
123 available. In C, `malloc` is used to allocate heap memory, and it returns a
126 As a more general variant of the previous two points, any time you have a
127 structure that can change in size, you need a pointer. You can't tell at
128 compile time how much memory to allocate, so you've gotta use a pointer to
129 point at the memory where it will be allocated, and deal with it at run time.
131 Pointers are useful in languages that are pass-by-value, rather than
132 pass-by-reference. Basically, languages can make two choices (this is made
133 up syntax, it's not Rust):
143 // what is the value of i here?
147 In languages that are pass-by-value, `foo` will get a copy of `i`, and so
148 the original version of `i` is not modified. At the comment, `i` will still be
149 `1`. In a language that is pass-by-reference, `foo` will get a reference to `i`,
150 and therefore, can change its value. At the comment, `i` will be `5`.
152 So what do pointers have to do with this? Well, since pointers point to a
153 location in memory...
163 // what is the value of i here?
167 Even in a language which is pass by value, `i` will be `5` at the comment. You
168 see, because the argument `x` is a pointer, we do send a copy over to `foo`,
169 but because it points at a memory location, which we then assign to, the
170 original value is still changed. This pattern is called
171 'pass-reference-by-value.' Tricky!
173 ## Common pointer problems
175 We've talked about pointers, and we've sung their praises. So what's the
176 downside? Well, Rust attempts to mitigate each of these kinds of problems,
177 but here are problems with pointers in other languages:
179 Uninitialized pointers can cause a problem. For example, what does this program
187 Who knows? We just declare a pointer, but don't point it at anything, and then
188 set the memory location that it points at to be `5`. But which location? Nobody
189 knows. This might be harmless, and it might be catastrophic.
191 When you combine pointers and functions, it's easy to accidentally invalidate
192 the memory the pointer is pointing to. For example:
195 func make_pointer(): &int {
202 &int i = make_pointer();
207 `x` is local to the `make_pointer` function, and therefore, is invalid as soon
208 as `make_pointer` returns. But we return a pointer to its memory location, and
209 so back in `main`, we try to use that pointer, and it's a very similar
210 situation to our first one. Setting invalid memory locations is bad.
212 As one last example of a big problem with pointers, **aliasing** can be an
213 issue. Two pointers are said to alias when they point at the same location
214 in memory. Like this:
217 func mutate(&int i, int j) {
224 z = &x; //y and z are aliased
227 run_in_new_thread(mutate, y, 1);
228 run_in_new_thread(mutate, z, 100);
230 // what is the value of x here?
234 In this made-up example, `run_in_new_thread` spins up a new thread, and calls
235 the given function name with its arguments. Since we have two threads, and
236 they're both operating on aliases to `x`, we can't tell which one finishes
237 first, and therefore, the value of `x` is actually non-deterministic. Worse,
238 what if one of them had invalidated the memory location they pointed to? We'd
239 have the same problem as before, where we'd be setting an invalid location.
243 That's a basic overview of pointers as a general concept. As we alluded to
244 before, Rust has different kinds of pointers, rather than just one, and
245 mitigates all of the problems that we talked about, too. This does mean that
246 Rust pointers are slightly more complicated than in other languages, but
247 it's worth it to not have the problems that simple pointers have.
251 The most basic type of pointer that Rust has is called a 'reference.' Rust
252 references look like this:
263 We'd say "`y` is a reference to `x`." The first `println!` prints out the
264 value of `y`'s referent by using the dereference operator, `*`. The second
265 one prints out the memory location that `y` points to, by using the pointer
266 format string. The third `println!` *also* prints out the value of `y`'s
267 referent, because `println!` will automatically dereference it for us.
269 Here's a function that takes a reference:
272 fn succ(x: &int) -> int { *x + 1 }
275 You can also use `&` as an operator to create a reference, so we can
276 call this function in two different ways:
279 fn succ(x: &int) -> int { *x + 1 }
286 println!("{}", succ(y));
287 println!("{}", succ(&x));
291 Both of these `println!`s will print out `6`.
293 Of course, if this were real code, we wouldn't bother with the reference, and
297 fn succ(x: int) -> int { x + 1 }
300 References are immutable by default:
306 *y = 5; // error: cannot assign to immutable dereference of `&`-pointer `*y`
309 They can be made mutable with `mut`, but only if its referent is also mutable.
321 let y = &mut x; // error: cannot borrow immutable local variable `x` as mutable
324 Immutable pointers are allowed to alias:
332 Mutable ones, however, are not:
337 let z = &mut x; // error: cannot borrow `x` as mutable more than once at a time
340 Despite their complete safety, a reference's representation at runtime is the
341 same as that of an ordinary pointer in a C program. They introduce zero
342 overhead. The compiler does all safety checks at compile time. The theory that
343 allows for this was originally called **region pointers**. Region pointers
344 evolved into what we know today as **lifetimes**.
346 Here's the simple explanation: would you expect this code to compile?
355 Probably not. That's because you know that the name `x` is valid from where
356 it's declared to when it goes out of scope. In this case, that's the end of
357 the `main` function. So you know this code will cause an error. We call this
358 duration a 'lifetime'. Let's try a more complex example:
367 println!("Oh no: {}", y);
373 println!("Oh no: {}", x);
377 Here, we're borrowing a pointer to `x` inside of the `if`. The compiler, however,
378 is able to determine that that pointer will go out of scope without `x` being
379 mutated, and therefore, lets us pass. This wouldn't work:
389 println!("Oh no: {}", y);
395 println!("Oh no: {}", x);
402 test.rs:5:8: 5:10 error: cannot assign to `*x` because it is borrowed
405 test.rs:4:16: 4:18 note: borrow of `*x` occurs here
406 test.rs:4 let y = &x;
410 As you might guess, this kind of analysis is complex for a human, and therefore
411 hard for a computer, too! There is an entire [guide devoted to references, ownership,
412 and lifetimes](guide-ownership.html) that goes into this topic in
413 great detail, so if you want the full details, check that out.
417 In general, prefer stack allocation over heap allocation. Using references to
418 stack allocated information is preferred whenever possible. Therefore,
419 references are the default pointer type you should use, unless you have a
420 specific reason to use a different type. The other types of pointers cover when
421 they're appropriate to use in their own best practices sections.
423 Use references when you want to use a pointer, but do not want to take ownership.
424 References just borrow ownership, which is more polite if you don't need the
425 ownership. In other words, prefer:
428 fn succ(x: &int) -> int { *x + 1 }
434 fn succ(x: Box<int>) -> int { *x + 1 }
437 As a corollary to that rule, references allow you to accept a wide variety of
438 other pointers, and so are useful so that you don't have to write a number
439 of variants per pointer. In other words, prefer:
442 fn succ(x: &int) -> int { *x + 1 }
450 fn box_succ(x: Box<int>) -> int { *x + 1 }
452 fn rc_succ(x: Rc<int>) -> int { *x + 1 }
455 Note that the caller of your function will have to modify their calls slightly:
460 fn succ(x: &int) -> int { *x + 1 }
464 let rc_x = Rc::new(5i);
471 The initial `*` dereferences the pointer, and then `&` takes a reference to
476 `Box<T>` is Rust's 'boxed pointer' type. Boxes provide the simplest form of
477 heap allocation in Rust. Creating a box looks like this:
480 let x = box(std::boxed::HEAP) 5i;
483 `box` is a keyword that does 'placement new,' which we'll talk about in a bit.
484 `box` will be useful for creating a number of heap-allocated types, but is not
485 quite finished yet. In the meantime, `box`'s type defaults to
486 `std::boxed::HEAP`, and so you can leave it off:
492 As you might assume from the `HEAP`, boxes are heap allocated. They are
493 deallocated automatically by Rust when they go out of scope:
501 } // x is destructed and its memory is free'd here
504 However, boxes do _not_ use reference counting or garbage collection. Boxes are
505 what's called an **affine type**. This means that the Rust compiler, at compile
506 time, determines when the box comes into and goes out of scope, and inserts the
507 appropriate calls there. Furthermore, boxes are a specific kind of affine type,
508 known as a **region**. You can read more about regions [in this paper on the
510 language](http://www.cs.umd.edu/projects/cyclone/papers/cyclone-regions.pdf).
512 You don't need to fully grok the theory of affine types or regions to grok
513 boxes, though. As a rough approximation, you can treat this Rust code:
523 As being similar to this C code:
528 x = (int *)malloc(sizeof(int));
537 Of course, this is a 10,000 foot view. It leaves out destructors, for example.
538 But the general idea is correct: you get the semantics of `malloc`/`free`, but
539 with some improvements:
541 1. It's impossible to allocate the incorrect amount of memory, because Rust
542 figures it out from the types.
543 2. You cannot forget to `free` memory you've allocated, because Rust does it
545 3. Rust ensures that this `free` happens at the right time, when it is truly
546 not used. Use-after-free is not possible.
547 4. Rust enforces that no other writeable pointers alias to this heap memory,
548 which means writing to an invalid pointer is not possible.
550 See the section on references or the [ownership guide](guide-ownership.html)
551 for more detail on how lifetimes work.
553 Using boxes and references together is very common. For example:
556 fn add_one(x: &int) -> int {
563 println!("{}", add_one(&*x));
567 In this case, Rust knows that `x` is being 'borrowed' by the `add_one()`
568 function, and since it's only reading the value, allows it.
570 We can borrow `x` multiple times, as long as it's not simultaneous:
573 fn add_one(x: &int) -> int {
580 println!("{}", add_one(&*x));
581 println!("{}", add_one(&*x));
582 println!("{}", add_one(&*x));
586 Or as long as it's not a mutable borrow. This will error:
589 fn add_one(x: &mut int) -> int {
596 println!("{}", add_one(&*x)); // error: cannot borrow immutable dereference
597 // of `&`-pointer as mutable
601 Notice we changed the signature of `add_one()` to request a mutable reference.
605 Boxes are appropriate to use in two situations: Recursive data structures,
606 and occasionally, when returning data.
608 ### Recursive data structures
610 Sometimes, you need a recursive data structure. The simplest is known as a
617 Cons(T, Box<List<T>>),
622 let list: List<int> = List::Cons(1, box List::Cons(2, box List::Cons(3, box List::Nil)));
623 println!("{}", list);
630 Cons(1, box Cons(2, box Cons(3, box Nil)))
633 The reference to another `List` inside of the `Cons` enum variant must be a box,
634 because we don't know the length of the list. Because we don't know the length,
635 we don't know the size, and therefore, we need to heap allocate our list.
637 Working with recursive or other unknown-sized data structures is the primary
642 This is important enough to have its own section entirely. The TL;DR is this:
643 you don't generally want to return pointers, even when you might in a language
646 See [Returning Pointers](#returning-pointers) below for more.
650 This part is coming soon.
654 This part is coming soon.
658 This part is coming soon.
662 This part is coming soon.
666 In many languages with pointers, you'd return a pointer from a function
667 so as to avoid copying a large data structure. For example:
677 fn foo(x: Box<BigStruct>) -> Box<BigStruct> {
682 let x = box BigStruct {
692 The idea is that by passing around a box, you're only copying a pointer, rather
693 than the hundred `int`s that make up the `BigStruct`.
695 This is an antipattern in Rust. Instead, write this:
705 fn foo(x: Box<BigStruct>) -> BigStruct {
710 let x = box BigStruct {
720 This gives you flexibility without sacrificing performance.
722 You may think that this gives us terrible performance: return a value and then
723 immediately box it up ?! Isn't that the worst of both worlds? Rust is smarter
724 than that. There is no copy in this code. `main` allocates enough room for the
725 `box`, passes a pointer to that memory into `foo` as `x`, and then `foo` writes
726 the value straight into that pointer. This writes the return value directly into
729 This is important enough that it bears repeating: pointers are not for
730 optimizing returning values from your code. Allow the caller to choose how they
731 want to use your output.
733 # Creating your own Pointers
735 This part is coming soon.
739 This part is coming soon.
743 When you're trying to match something that's stored in a pointer, there may be
744 a situation where matching directly isn't the best option available. Let's see
745 how to properly handle this:
748 fn possibly_print(x: &Option<String>) {
750 // BAD: cannot move out of a `&`
751 Some(s) => println!("{}", s)
753 // GOOD: instead take a reference into the memory of the `Option`
754 Some(ref s) => println!("{}", *s),
760 The `ref s` here means that `s` will be of type `&String`, rather than type
763 This is important when the type you're trying to get access to has a destructor
764 and you don't want to move it, you just want a reference to it.
768 Here's a quick rundown of Rust's pointer types:
770 | Type | Name | Summary |
771 |--------------|---------------------|---------------------------------------------------------------------|
772 | `&T` | Reference | Allows one or more references to read `T` |
773 | `&mut T` | Mutable Reference | Allows a single reference to read and write `T` |
774 | `Box<T>` | Box | Heap allocated `T` with a single owner that may read and write `T`. |
775 | `Rc<T>` | "arr cee" pointer | Heap allocated `T` with many readers |
776 | `Arc<T>` | Arc pointer | Same as above, but safe sharing across threads |
777 | `*const T` | Raw pointer | Unsafe read access to `T` |
778 | `*mut T` | Mutable raw pointer | Unsafe read and write access to `T` |
782 * [API documentation for Box](std/boxed/index.html)
783 * [Ownership guide](guide-ownership.html)
784 * [Cyclone paper on regions](http://www.cs.umd.edu/projects/cyclone/papers/cyclone-regions.pdf), which inspired Rust's lifetime system