1 % A 30-minute Introduction to Rust
3 Rust is a modern systems programming language focusing on safety and speed. It
4 accomplishes these goals by being memory safe without using garbage collection.
6 This introduction will give you a rough idea of what Rust is like, eliding many
7 details. It does not require prior experience with systems programming, but you
8 may find the syntax easier if you've used a "curly brace" programming language
9 before, like C or JavaScript. The concepts are more important than the syntax,
10 so don't worry if you don't get every last detail: you can read [The
11 Rust Programming Language](book/index.html) to get a more complete explanation.
13 Because this is about high-level concepts, you don't need to actually install
14 Rust to follow along. If you'd like to anyway, check out [the
15 homepage](http://rust-lang.org) for explanation.
17 To show off Rust, let's talk about how easy it is to get started with Rust.
18 Then, we'll talk about Rust's most interesting feature, *ownership*, and
19 then discuss how it makes concurrency easier to reason about. Finally,
20 we'll talk about how Rust breaks down the perceived dichotomy between speed
25 Getting started on a new Rust project is incredibly easy, thanks to Rust's
26 package manager, [Cargo](http://crates.io).
28 To start a new project with Cargo, use `cargo new`:
31 $ cargo new hello_world --bin
34 We're passing `--bin` because we're making a binary program: if we
35 were making a library, we'd leave it off.
37 Let's check out what Cargo has generated for us:
50 This is all we need to get started. First, let's check out `Cargo.toml`:
57 authors = ["Your Name <you@example.com>"]
60 This is called a *manifest*, and it contains all of the metadata that Cargo
61 needs to compile your project.
63 Here's what's in `src/main.rs`:
67 println!("Hello, world!");
71 Cargo generated a "Hello World" for us. We'll talk more about the syntax here
72 later, but that's what Rust code looks like! Let's compile and run it:
76 Compiling hello_world v0.0.1 (file:///Users/you/src/hello_world)
77 Running `target/hello_world`
81 Using an external dependency in Rust is incredibly easy. You add a line to
89 authors = ["Your Name <someone@example.com>"]
93 git = "https://github.com/rust-lang/semver.git"
96 You added the `semver` library, which parses version numbers and compares them
97 according to the [SemVer specification](http://semver.org/).
99 Now, you can pull in that library using `extern crate` in
108 assert!(Version::parse("1.2.3") == Ok(Version {
116 println!("Versions compared successfully!");
120 Again, we'll discuss the exact details of all of this syntax soon. For now,
121 let's compile and run it:
125 Updating git repository `https://github.com/rust-lang/semver.git`
126 Compiling semver v0.0.1 (https://github.com/rust-lang/semver.git#bf739419)
127 Compiling hello_world v0.0.1 (file:///home/you/projects/hello_world)
128 Running `target/hello_world`
129 Versions compared successfully!
132 Because we only specified a repository without a version, if someone else were
133 to try out our project at a later date, when `semver` was updated, they would
134 get a different, possibly incompatible version. To solve this problem, Cargo
135 produces a file, `Cargo.lock`, which records the versions of any dependencies.
136 This gives us repeatable builds.
138 There is a lot more here, and this is a whirlwind tour, but you should feel
139 right at home if you've used tools like [Bundler](http://bundler.io/),
140 [npm](https://www.npmjs.org/), or [pip](https://pip.pypa.io/en/latest/).
141 There's no `Makefile`s or endless `autotools` output here. (Rust's tooling does
142 [play nice with external libraries written in those
143 tools](http://crates.io/native-build.html), if you need to.)
145 Enough about tools, let's talk code!
149 Rust's defining feature is "memory safety without garbage collection". Let's
150 take a moment to talk about what that means. *Memory safety* means that the
151 programming language eliminates certain kinds of bugs, such as [buffer
152 overflows](http://en.wikipedia.org/wiki/Buffer_overflow) and [dangling
153 pointers](http://en.wikipedia.org/wiki/Dangling_pointer). These problems occur
154 when you have unrestricted access to memory. As an example, here's some Ruby
169 We make an array, `v`, and then call `push` on it. `push` is a method which
170 adds an element to the end of an array.
172 Next, we make a new variable, `x`, that's equal to the first element of
173 the array. Simple, but this is where the "bug" will appear.
175 Let's keep going. We then call `push` again, pushing "world" onto the
176 end of the array. `v` now is `["Hello", "world"]`.
178 Finally, we print `x` with the `puts` method. This prints "Hello."
180 All good? Let's go over a similar, but subtly different example, in C++:
188 std::vector<std::string> v;
190 v.push_back("Hello");
192 std::string& x = v[0];
194 v.push_back("world");
200 It's a little more verbose due to the static typing, but it's almost the same
201 thing. We make a `std::vector` of `std::string`s, we call `push_back` (same as
202 `push`) on it, take a reference to the first element of the vector, call
203 `push_back` again, and then print out the reference.
205 There's two big differences here: one, they're not _exactly_ the same thing,
209 $ g++ hello.cpp -Wall -Werror
211 Segmentation fault (core dumped)
214 A crash! (Note that this is actually system-dependent. Because referring to an
215 invalid reference is undefined behavior, the compiler can do anything,
216 including the right thing!) Even though we compiled with flags to give us as
217 many warnings as possible, and to treat those warnings as errors, we got no
218 errors. When we ran the program, it crashed.
220 Why does this happen? When we append to an array, its length changes. Since
221 its length changes, we may need to allocate more memory. In Ruby, this happens
222 as well, we just don't think about it very often. So why does the C++ version
223 segfault when we allocate more memory?
225 The answer is that in the C++ version, `x` is a *reference* to the memory
226 location where the first element of the array is stored. But in Ruby, `x` is a
227 standalone value, not connected to the underyling array at all. Let's dig into
228 the details for a moment. Your program has access to memory, provided to it by
229 the operating system. Each location in memory has an address. So when we make
230 our vector, `v`, it's stored in a memory location somewhere:
232 | location | name | value |
233 |----------|------|-------|
236 (Address numbers made up, and in hexadecimal. Those of you with deep C++
237 knowledge, there are some simplifications going on here, like the lack of an
238 allocated length for the vector. This is an introduction.)
240 When we push our first string onto the array, we allocate some memory,
241 and `v` refers to it:
243 | location | name | value |
244 |----------|------|----------|
248 We then make a reference to that first element. A reference is a variable
249 that points to a memory location, so its value is the memory location of
250 the `"Hello"` string:
252 | location | name | value |
253 |----------|------|----------|
258 When we push `"world"` onto the vector with `push_back`, there's no room:
259 we only allocated one element. So, we need to allocate two elements,
260 copy the `"Hello"` string over, and update the reference. Like this:
262 | location | name | value |
263 |----------|------|----------|
270 Note that `v` now refers to the new list, which has two elements. It's all
271 good. But our `x` didn't get updated! It still points at the old location,
272 which isn't valid anymore. In fact, [the documentation for `push_back` mentions
273 this](http://en.cppreference.com/w/cpp/container/vector/push_back):
275 > If the new `size()` is greater than `capacity()` then all iterators and
276 > references (including the past-the-end iterator) are invalidated.
278 Finding where these iterators and references are is a difficult problem, and
279 even in this simple case, `g++` can't help us here. While the bug is obvious in
280 this case, in real code, it can be difficult to track down the source of the
283 Before we talk about this solution, why didn't our Ruby code have this problem?
284 The semantics are a little more complicated, and explaining Ruby's internals is
285 out of the scope of a guide to Rust. But in a nutshell, Ruby's garbage
286 collector keeps track of references, and makes sure that everything works as
287 you might expect. This comes at an efficiency cost, and the internals are more
288 complex. If you'd really like to dig into the details, [this
289 article](http://patshaughnessy.net/2012/1/18/seeing-double-how-ruby-shares-string-values)
290 can give you more information.
292 Garbage collection is a valid approach to memory safety, but Rust chooses a
293 different path. Let's examine what the Rust version of this looks like:
309 This looks like a bit of both: fewer type annotations, but we do create new
310 variables with `let`. The method name is `push`, some other stuff is different,
311 but it's pretty close. So what happens when we compile this code? Does Rust
312 print `"Hello"`, or does Rust crash?
314 Neither. It refuses to compile:
318 Compiling hello_world v0.0.1 (file:///Users/you/src/hello_world)
319 main.rs:8:5: 8:6 error: cannot borrow `v` as mutable because it is also borrowed as immutable
320 main.rs:8 v.push("world");
322 main.rs:6:14: 6:15 note: previous borrow of `v` occurs here; the immutable borrow prevents subsequent moves or mutable borrows of `v` until the borrow ends
323 main.rs:6 let x = &v[0];
325 main.rs:11:2: 11:2 note: previous borrow ends here
326 main.rs:1 fn main() {
330 error: aborting due to previous error
333 When we try to mutate the array by `push`ing it the second time, Rust throws
334 an error. It says that we "cannot borrow v as mutable because it is also
335 borrowed as immutable." What does it mean by "borrowed"?
337 In Rust, the type system encodes the notion of *ownership*. The variable `v`
338 is an *owner* of the vector. When we make a reference to `v`, we let that
339 variable (in this case, `x`) *borrow* it for a while. Just like if you own a
340 book, and you lend it to me, I'm borrowing the book.
342 So, when I try to modify the vector with the second call to `push`, I need
343 to be owning it. But `x` is borrowing it. You can't modify something that
344 you've lent to someone. And so Rust throws an error.
346 So how do we fix this problem? Well, we can make a copy of the element:
355 let x = v[0].clone();
363 Note the addition of `clone()`. This creates a copy of the element, leaving
364 the original untouched. Now, we no longer have two references to the same
365 memory, and so the compiler is happy. Let's give that a try:
369 Compiling hello_world v0.0.1 (file:///Users/you/src/hello_world)
370 Running `target/hello_world`
374 Same result. Now, making a copy can be inefficient, so this solution may not be
375 acceptable. There are other ways to get around this problem, but this is a toy
376 example, and because we're in an introduction, we'll leave that for later.
378 The point is, the Rust compiler and its notion of ownership has saved us from a
379 bug that would crash the program. We've achieved safety, at compile time,
380 without needing to rely on a garbage collector to handle our memory.
384 Rust's ownership model can help in other ways, as well. For example, take
385 concurrency. Concurrency is a big topic, and an important one for any modern
386 programming language. Let's take a look at how ownership can help you write
387 safe concurrent programs.
389 Here's an example of a concurrent Rust program:
392 use std::thread::Thread;
395 let guards: Vec<_> = (0..10).map(|_| {
397 println!("Hello, world!");
403 This program creates ten threads, which all print `Hello, world!`. The `scoped`
404 function takes one argument, a closure, indicated by the double bars `||`. This
405 closure is executed in a new thread created by `scoped`. The method is called
406 `scoped` because it returns a 'join guard', which will automatically join the
407 child thread when it goes out of scope. Because we `collect` these guards into
408 a `Vec<T>`, and that vector goes out of scope at the end of our program, our
409 program will wait for every thread to finish before finishing.
411 One common form of problem in concurrent programs is a *data race*.
412 This occurs when two different threads attempt to access the same
413 location in memory in a non-synchronized way, where at least one of
414 them is a write. If one thread is attempting to read, and one thread
415 is attempting to write, you cannot be sure that your data will not be
416 corrupted. Note the first half of that requirement: two threads that
417 attempt to access the same location in memory. Rust's ownership model
418 can track which pointers own which memory locations, which solves this
421 Let's see an example. This Rust code will not compile:
424 use std::thread::Thread;
427 let mut numbers = vec![1is, 2is, 3is];
430 Thread::spawn(move || {
431 for j in 0..3 { numbers[j] += 1 }
437 It gives us this error:
440 6:71 error: capture of moved value: `numbers`
441 for j in range(0, 3) { numbers[j] += 1 }
443 7:50 note: `numbers` moved into closure environment here
445 for j in range(0, 3) { numbers[j] += 1 }
447 6:79 error: cannot assign to immutable dereference (dereference is implicit, due to indexing)
448 for j in range(0, 3) { numbers[j] += 1 }
452 It mentions that "numbers moved into closure environment". Because we
453 declared the closure as a moving closure, and it referred to
454 `numbers`, the closure will try to take ownership of the vector. But
455 the closure itself is created in a loop, and hence we will actually
456 create three closures, one for every iteration of the loop. This means
457 that all three of those closures would try to own `numbers`, which is
458 impossible -- `numbers` must have just one owner. Rust detects this
459 and gives us the error: we claim that `numbers` has ownership, but our
460 code tries to make three owners. This may cause a safety problem, so
463 What to do here? Rust has two types that helps us: `Arc<T>` and `Mutex<T>`.
464 *Arc* stands for "atomically reference counted". In other words, an Arc will
465 keep track of the number of references to something, and not free the
466 associated resource until the count is zero. The *atomic* portion refers to an
467 Arc's usage of concurrency primitives to atomically update the count, making it
468 safe across threads. If we use an Arc, we can have our three references. But,
469 an Arc does not allow mutable borrows of the data it holds, and we want to
470 modify what we're sharing. In this case, we can use a `Mutex<T>` inside of our
471 Arc. A Mutex will synchronize our accesses, so that we can ensure that our
472 mutation doesn't cause a data race.
474 Here's what using an Arc with a Mutex looks like:
477 use std::thread::Thread;
478 use std::sync::{Arc,Mutex};
481 let numbers = Arc::new(Mutex::new(vec![1is, 2is, 3is]));
484 let number = numbers.clone();
485 Thread::spawn(move || {
486 let mut array = number.lock().unwrap();
490 println!("numbers[{}] is {}", i, (*array)[i]);
496 We first have to `use` the appropriate library, and then we wrap our vector in
497 an Arc with the call to `Arc::new()`. Inside of the loop, we make a new
498 reference to the Arc with the `clone()` method. This will increment the
499 reference count. When each new `numbers` variable binding goes out of scope, it
500 will decrement the count. The `lock()` call will return us a reference to the
501 value inside the Mutex, and block any other calls to `lock()` until said
502 reference goes out of scope.
504 We can compile and run this program without error, and in fact, see the
505 non-deterministic aspect:
509 Compiling hello_world v0.0.1 (file:///Users/you/src/hello_world)
510 Running `target/hello_world`
515 Running `target/hello_world`
521 Each time, we get a slightly different output, because each thread works in a
522 different order. You may not get the same output as this sample, even.
524 The important part here is that the Rust compiler was able to use ownership to
525 give us assurance _at compile time_ that we weren't doing something incorrect
526 with regards to concurrency. In order to share ownership, we were forced to be
527 explicit and use a mechanism to ensure that it would be properly handled.
531 Safety and speed are always presented as a continuum. At one end of the spectrum,
532 you have maximum speed, but no safety. On the other end, you have absolute safety
533 with no speed. Rust seeks to break out of this paradigm by introducing safety at
534 compile time, ensuring that you haven't done anything wrong, while compiling to
535 the same low-level code you'd expect without the safety.
537 As an example, Rust's ownership system is _entirely_ at compile time. The
538 safety check that makes this an error about moved values:
541 use std::thread::Thread;
544 let vec = vec![1i, 2, 3];
546 for i in range(0u, 3) {
547 Thread::spawn(move || {
548 println!("{}", vec[i]);
554 carries no runtime penalty. And while some of Rust's safety features do have
555 a run-time cost, there's often a way to write your code in such a way that
556 you can remove it. As an example, this is a poor way to iterate through
560 let vec = vec![1i, 2, 3];
562 for i in range(0u, vec.len()) {
563 println!("{}", vec[i]);
567 The reason is that the access of `vec[i]` does bounds checking, to ensure
568 that we don't try to access an invalid index. However, we can remove this
569 while retaining safety. The answer is iterators:
572 let vec = vec![1i, 2, 3];
574 for x in vec.iter() {
579 This version uses an iterator that yields each element of the vector in turn.
580 Because we have a reference to the element, rather than the whole vector itself,
581 there's no array access bounds to check.
585 I hope that this taste of Rust has given you an idea if Rust is the right
586 language for you. We talked about Rust's tooling, how encoding ownership into
587 the type system helps you find bugs, how Rust can help you write correct
588 concurrent code, and how you don't have to pay a speed cost for much of this
591 To continue your Rustic education, read [The Rust Programming
592 Language](book/index.html) for a more in-depth exploration of Rust's syntax and