src/doc/trpl/concurrency.md

   1 % Concurrency
   2
   3 Concurrency and parallelism are incredibly important topics in computer
   4 science, and are also a hot topic in industry today. Computers are gaining more
   5 and more cores, yet many programmers aren't prepared to fully utilize them.
   6
   7 Rust's memory safety features also apply to its concurrency story too. Even
   8 concurrent Rust programs must be memory safe, having no data races. Rust's type
   9 system is up to the task, and gives you powerful ways to reason about
  10 concurrent code at compile time.
  11
  12 Before we talk about the concurrency features that come with Rust, it's important
  13 to understand something: Rust is low-level enough that the vast majority of
  14 this is provided by the standard library, not by the language. This means that
  15 if you don't like some aspect of the way Rust handles concurrency, you can
  16 implement an alternative way of doing things.
  17 [mio](https://github.com/carllerche/mio) is a real-world example of this
  18 principle in action.
  19
  20 ## Background: `Send` and `Sync`
  21
  22 Concurrency is difficult to reason about. In Rust, we have a strong, static
  23 type system to help us reason about our code. As such, Rust gives us two traits
  24 to help us make sense of code that can possibly be concurrent.
  25
  26 ### `Send`
  27
  28 The first trait we're going to talk about is
  29 [`Send`](../std/marker/trait.Send.html). When a type `T` implements `Send`, it indicates
  30 to the compiler that something of this type is able to have ownership transferred
  31 safely between threads.
  32
  33 This is important to enforce certain restrictions. For example, if we have a
  34 channel connecting two threads, we would want to be able to send some data
  35 down the channel and to the other thread. Therefore, we'd ensure that `Send` was
  36 implemented for that type.
  37
  38 In the opposite way, if we were wrapping a library with FFI that isn't
  39 threadsafe, we wouldn't want to implement `Send`, and so the compiler will help
  40 us enforce that it can't leave the current thread.
  41
  42 ### `Sync`
  43
  44 The second of these traits is called [`Sync`](../std/marker/trait.Sync.html).
  45 When a type `T` implements `Sync`, it indicates to the compiler that something
  46 of this type has no possibility of introducing memory unsafety when used from
  47 multiple threads concurrently.
  48
  49 For example, sharing immutable data with an atomic reference count is
  50 threadsafe. Rust provides a type like this, `Arc<T>`, and it implements `Sync`,
  51 so it is safe to share between threads.
  52
  53 These two traits allow you to use the type system to make strong guarantees
  54 about the properties of your code under concurrency. Before we demonstrate
  55 why, we need to learn how to create a concurrent Rust program in the first
  56 place!
  57
  58 ## Threads
  59
  60 Rust's standard library provides a library for threads, which allow you to
  61 run Rust code in parallel. Here's a basic example of using `std::thread`:
  62
  63 ```rust
  64 use std::thread;
  65
  66 fn main() {
  67     thread::spawn(|| {
  68         println!("Hello from a thread!");
  69     });
  70 }
  71 ```
  72
  73 The `thread::spawn()` method accepts a closure, which is executed in a
  74 new thread. It returns a handle to the thread, that can be used to
  75 wait for the child thread to finish and extract its result:
  76
  77 ```rust
  78 use std::thread;
  79
  80 fn main() {
  81     let handle = thread::spawn(|| {
  82         "Hello from a thread!"
  83     });
  84
  85     println!("{}", handle.join().unwrap());
  86 }
  87 ```
  88
  89 Many languages have the ability to execute threads, but it's wildly unsafe.
  90 There are entire books about how to prevent errors that occur from shared
  91 mutable state. Rust helps out with its type system here as well, by preventing
  92 data races at compile time. Let's talk about how you actually share things
  93 between threads.
  94
  95 ## Safe Shared Mutable State
  96
  97 Due to Rust's type system, we have a concept that sounds like a lie: "safe
  98 shared mutable state." Many programmers agree that shared mutable state is
  99 very, very bad.
 100
 101 Someone once said this:
 102
 103 > Shared mutable state is the root of all evil. Most languages attempt to deal
 104 > with this problem through the 'mutable' part, but Rust deals with it by
 105 > solving the 'shared' part.
 106
 107 The same [ownership system](ownership.html) that helps prevent using pointers
 108 incorrectly also helps rule out data races, one of the worst kinds of
 109 concurrency bugs.
 110
 111 As an example, here is a Rust program that would have a data race in many
 112 languages. It will not compile:
 113
 114 ```ignore
 115 use std::thread;
 116
 117 fn main() {
 118     let mut data = vec![1, 2, 3];
 119
 120     for i in 0..3 {
 121         thread::spawn(move || {
 122             data[i] += 1;
 123         });
 124     }
 125
 126     thread::sleep_ms(50);
 127 }
 128 ```
 129
 130 This gives us an error:
 131
 132 ```text
 133 8:17 error: capture of moved value: `data`
 134         data[i] += 1;
 135         ^~~~
 136 ```
 137
 138 Rust knows this wouldn't be safe! If we had a reference to `data` in each
 139 thread, and the thread takes ownership of the reference, we'd have three
 140 owners!
 141
 142 So, we need some type that lets us have more than one reference to a value and
 143 that we can share between threads, that is it must implement `Sync`.
 144
 145 We'll use `Arc<T>`, rust's standard atomic reference count type, which
 146 wraps a value up with some extra runtime bookkeeping which allows us to
 147 share the ownership of the value between multiple references at the same time.
 148
 149 The bookkeeping consists of a count of how many of these references exist to
 150 the value, hence the reference count part of the name.
 151
 152 The Atomic part means `Arc<T>` can safely be accessed from multiple threads.
 153 To do this the compiler guarantees that mutations of the internal count use
 154 indivisible operations which can't have data races.
 155
 156
 157 ```ignore
 158 use std::thread;
 159 use std::sync::Arc;
 160
 161 fn main() {
 162     let mut data = Arc::new(vec![1, 2, 3]);
 163
 164     for i in 0..3 {
 165         let data = data.clone();
 166         thread::spawn(move || {
 167             data[i] += 1;
 168         });
 169     }
 170
 171     thread::sleep_ms(50);
 172 }
 173 ```
 174
 175 We now call `clone()` on our `Arc<T>`, which increases the internal count.
 176 This handle is then moved into the new thread.
 177
 178 And... still gives us an error.
 179
 180 ```text
 181 <anon>:11:24 error: cannot borrow immutable borrowed content as mutable
 182 <anon>:11                    data[i] += 1;
 183                              ^~~~
 184 ```
 185
 186 `Arc<T>` assumes one more property about its contents to ensure that it is safe
 187 to share across threads: it assumes its contents are `Sync`. This is true for
 188 our value if it's immutable, but we want to be able to mutate it, so we need
 189 something else to persuade the borrow checker we know what we're doing.
 190
 191 It looks like we need some type that allows us to safely mutate a shared value,
 192 for example a type that that can ensure only one thread at a time is able to
 193 mutate the value inside it at any one time.
 194
 195 For that, we can use the `Mutex<T>` type!
 196
 197 Here's the working version:
 198
 199 ```rust
 200 use std::sync::{Arc, Mutex};
 201 use std::thread;
 202
 203 fn main() {
 204     let data = Arc::new(Mutex::new(vec![1, 2, 3]));
 205
 206     for i in 0..3 {
 207         let data = data.clone();
 208         thread::spawn(move || {
 209             let mut data = data.lock().unwrap();
 210             data[i] += 1;
 211         });
 212     }
 213
 214     thread::sleep_ms(50);
 215 }
 216 ```
 217
 218
 219 If we'd tried to use `Mutex<T>` without wrapping it in an `Arc<T>` we would have
 220 seen another error like:
 221
 222 ```text
 223 error: the trait `core::marker::Send` is not implemented for the type `std::sync::mutex::MutexGuard<'_, collections::vec::Vec<u32>>` [E0277]
 224  thread::spawn(move || {
 225                   ^~~~~~~~~~~~~
 226 note: `std::sync::mutex::MutexGuard<'_, collections::vec::Vec<u32>>` cannot be sent between threads safely
 227  thread::spawn(move || {
 228                   ^~~~~~~~~~~~~
 229 ```
 230
 231 You see, [`Mutex`](../std/sync/struct.Mutex.html) has a
 232 [`lock`](../std/sync/struct.Mutex.html#method.lock)
 233 method which has this signature:
 234
 235 ```ignore
 236 fn lock(&self) -> LockResult<MutexGuard<T>>
 237 ```
 238
 239 and because `Send` is not implemented for `MutexGuard<T>`, we couldn't have
 240 transferred the guard across thread boundaries on it's own.
 241
 242 Let's examine the body of the thread more closely:
 243
 244 ```rust
 245 # use std::sync::{Arc, Mutex};
 246 # use std::thread;
 247 # fn main() {
 248 #     let data = Arc::new(Mutex::new(vec![1, 2, 3]));
 249 #     for i in 0..3 {
 250 #         let data = data.clone();
 251 thread::spawn(move || {
 252     let mut data = data.lock().unwrap();
 253     data[i] += 1;
 254 });
 255 #     }
 256 #     thread::sleep_ms(50);
 257 # }
 258 ```
 259
 260 First, we call `lock()`, which acquires the mutex's lock. Because this may fail,
 261 it returns an `Result<T, E>`, and because this is just an example, we `unwrap()`
 262 it to get a reference to the data. Real code would have more robust error handling
 263 here. We're then free to mutate it, since we have the lock.
 264
 265 Lastly, while the threads are running, we wait on a short timer. But
 266 this is not ideal: we may have picked a reasonable amount of time to
 267 wait but it's more likely we'll either be waiting longer than
 268 necessary or not long enough, depending on just how much time the
 269 threads actually take to finish computing when the program runs.
 270
 271 A more precise alternative to the timer would be to use one of the
 272 mechanisms provided by the Rust standard library for synchronizing
 273 threads with each other. Let's talk about one of them: channels.
 274
 275 ## Channels
 276
 277 Here's a version of our code that uses channels for synchronization, rather
 278 than waiting for a specific time:
 279
 280 ```rust
 281 use std::sync::{Arc, Mutex};
 282 use std::thread;
 283 use std::sync::mpsc;
 284
 285 fn main() {
 286     let data = Arc::new(Mutex::new(0));
 287
 288     let (tx, rx) = mpsc::channel();
 289
 290     for _ in 0..10 {
 291         let (data, tx) = (data.clone(), tx.clone());
 292
 293         thread::spawn(move || {
 294             let mut data = data.lock().unwrap();
 295             *data += 1;
 296
 297             tx.send(());
 298         });
 299     }
 300
 301     for _ in 0..10 {
 302         rx.recv();
 303     }
 304 }
 305 ```
 306
 307 We use the `mpsc::channel()` method to construct a new channel. We just `send`
 308 a simple `()` down the channel, and then wait for ten of them to come back.
 309
 310 While this channel is just sending a generic signal, we can send any data that
 311 is `Send` over the channel!
 312
 313 ```rust
 314 use std::thread;
 315 use std::sync::mpsc;
 316
 317 fn main() {
 318     let (tx, rx) = mpsc::channel();
 319
 320     for _ in 0..10 {
 321         let tx = tx.clone();
 322
 323         thread::spawn(move || {
 324             let answer = 42;
 325
 326             tx.send(answer);
 327         });
 328     }
 329
 330    rx.recv().ok().expect("Could not receive answer");
 331 }
 332 ```
 333
 334 A `u32` is `Send` because we can make a copy. So we create a thread, ask it to calculate
 335 the answer, and then it `send()`s us the answer over the channel.
 336
 337
 338 ## Panics
 339
 340 A `panic!` will crash the currently executing thread. You can use Rust's
 341 threads as a simple isolation mechanism:
 342
 343 ```rust
 344 use std::thread;
 345
 346 let result = thread::spawn(move || {
 347     panic!("oops!");
 348 }).join();
 349
 350 assert!(result.is_err());
 351 ```
 352
 353 Our `Thread` gives us a `Result` back, which allows us to check if the thread
 354 has panicked or not.