1 % The Rust Threads and Communication Guide
3 **NOTE** This guide is badly out of date and needs to be rewritten.
7 Rust provides safe concurrent abstractions through a number of core library
8 primitives. This guide will describe the concurrency model in Rust, how it
9 relates to the Rust type system, and introduce the fundamental library
10 abstractions for constructing concurrent programs.
12 Threads provide failure isolation and recovery. When a fatal error occurs in Rust
13 code as a result of an explicit call to `panic!()`, an assertion failure, or
14 another invalid operation, the runtime system destroys the entire thread. Unlike
15 in languages such as Java and C++, there is no way to `catch` an exception.
16 Instead, threads may monitor each other to see if they panic.
18 Threads use Rust's type system to provide strong memory safety guarantees. In
19 particular, the type system guarantees that threads cannot induce a data race
20 from shared mutable state.
24 At its simplest, creating a thread is a matter of calling the `spawn` function
25 with a closure argument. `spawn` executes the closure in the new thread.
28 # use std::thread::spawn;
30 // Print something profound in a different thread using a named function
31 fn print_message() { println!("I am running in a different thread!"); }
34 // Alternatively, use a `move ||` expression instead of a named function.
35 // `||` expressions evaluate to an unnamed closure. The `move` keyword
36 // indicates that the closure should take ownership of any variables it
38 spawn(move || println!("I am also running in a different thread!"));
41 In Rust, a thread is not a concept that appears in the language semantics.
42 Instead, Rust's type system provides all the tools necessary to implement safe
43 concurrency: particularly, ownership. The language leaves the implementation
44 details to the standard library.
46 The `spawn` function has the type signature: `fn
47 spawn<F:FnOnce()+Send>(f: F)`. This indicates that it takes as
48 argument a closure (of type `F`) that it will run exactly once. This
49 closure is limited to capturing `Send`-able data from its environment
50 (that is, data which is deeply owned). Limiting the closure to `Send`
51 ensures that `spawn` can safely move the entire closure and all its
52 associated state into an entirely different thread for execution.
55 use std::thread::Thread;
57 fn generate_thread_number() -> i32 { 4 } // a very simple generation
59 // Generate some state locally
60 let child_thread_number = generate_thread_number();
62 Thread::spawn(move || {
63 // Capture it in the remote thread. The `move` keyword indicates
64 // that this closure should move `child_thread_number` into its
65 // environment, rather than capturing a reference into the
66 // enclosing stack frame.
67 println!("I am child number {}", child_thread_number);
73 Now that we have spawned a new thread, it would be nice if we could communicate
74 with it. For this, we use *channels*. A channel is simply a pair of endpoints:
75 one for sending messages and another for receiving messages.
77 The simplest way to create a channel is to use the `channel` function to create a
78 `(Sender, Receiver)` pair. In Rust parlance, a *sender* is a sending endpoint
79 of a channel, and a *receiver* is the receiving endpoint. Consider the following
80 example of calculating two results concurrently:
83 use std::thread::Thread;
86 let (tx, rx): (mpsc::Sender<u32>, mpsc::Receiver<u32>) = mpsc::channel();
88 Thread::spawn(move || {
89 let result = some_expensive_computation();
93 some_other_expensive_computation();
94 let result = rx.recv();
96 fn some_expensive_computation() -> u32 { 42 } // very expensive ;)
97 fn some_other_expensive_computation() {} // even more so
100 Let's examine this example in detail. First, the `let` statement creates a
101 stream for sending and receiving integers (the left-hand side of the `let`,
102 `(tx, rx)`, is an example of a destructuring let: the pattern separates a tuple
103 into its component parts).
106 # use std::sync::mpsc;
107 let (tx, rx): (mpsc::Sender<u32>, mpsc::Receiver<u32>) = mpsc::channel();
110 The child thread will use the sender to send data to the parent thread, which will
111 wait to receive the data on the receiver. The next statement spawns the child
115 # use std::thread::Thread;
116 # use std::sync::mpsc;
117 # fn some_expensive_computation() -> u32 { 42 }
118 # let (tx, rx) = mpsc::channel();
119 Thread::spawn(move || {
120 let result = some_expensive_computation();
125 Notice that the creation of the thread closure transfers `tx` to the child thread
126 implicitly: the closure captures `tx` in its environment. Both `Sender` and
127 `Receiver` are sendable types and may be captured into threads or otherwise
128 transferred between them. In the example, the child thread runs an expensive
129 computation, then sends the result over the captured channel.
131 Finally, the parent continues with some other expensive computation, then waits
132 for the child's result to arrive on the receiver:
135 # use std::sync::mpsc;
136 # fn some_other_expensive_computation() {}
137 # let (tx, rx) = mpsc::channel::<u32>();
139 some_other_expensive_computation();
140 let result = rx.recv();
143 The `Sender` and `Receiver` pair created by `channel` enables efficient
144 communication between a single sender and a single receiver, but multiple
145 senders cannot use a single `Sender` value, and multiple receivers cannot use a
146 single `Receiver` value. What if our example needed to compute multiple
147 results across a number of threads? The following program is ill-typed:
150 # use std::sync::mpsc;
151 # fn some_expensive_computation() -> u32 { 42 }
152 let (tx, rx) = mpsc::channel();
155 tx.send(some_expensive_computation());
158 // ERROR! The previous spawn statement already owns the sender,
159 // so the compiler will not allow it to be captured again
161 tx.send(some_expensive_computation());
165 Instead we can clone the `tx`, which allows for multiple senders.
168 use std::thread::Thread;
171 let (tx, rx) = mpsc::channel();
173 for init_val in 0 .. 3 {
174 // Create a new channel handle to distribute to the child thread
175 let child_tx = tx.clone();
176 Thread::spawn(move || {
177 child_tx.send(some_expensive_computation(init_val));
181 let result = rx.recv().unwrap() + rx.recv().unwrap() + rx.recv().unwrap();
182 # fn some_expensive_computation(_i: u32) -> u32 { 42 }
185 Cloning a `Sender` produces a new handle to the same channel, allowing multiple
186 threads to send data to a single receiver. It upgrades the channel internally in
187 order to allow this functionality, which means that channels that are not
188 cloned can avoid the overhead required to handle multiple senders. But this
189 fact has no bearing on the channel's usage: the upgrade is transparent.
191 Note that the above cloning example is somewhat contrived since you could also
192 simply use three `Sender` pairs, but it serves to illustrate the point. For
193 reference, written with multiple streams, it might look like the example below.
196 use std::thread::Thread;
199 // Create a vector of ports, one for each child thread
200 let rxs = (0 .. 3).map(|&:init_val| {
201 let (tx, rx) = mpsc::channel();
202 Thread::spawn(move || {
203 tx.send(some_expensive_computation(init_val));
206 }).collect::<Vec<_>>();
208 // Wait on each port, accumulating the results
209 let result = rxs.iter().fold(0, |&:accum, rx| accum + rx.recv().unwrap() );
210 # fn some_expensive_computation(_i: u32) -> u32 { 42 }
213 ## Backgrounding computations: Futures
215 With `sync::Future`, rust has a mechanism for requesting a computation and
216 getting the result later.
218 The basic example below illustrates this.
221 # #![allow(deprecated)]
222 use std::sync::Future;
225 # fn make_a_sandwich() {};
226 fn fib(n: u64) -> u64 {
227 // lengthy computation returning an 64
231 let mut delayed_fib = Future::spawn(move || fib(50));
233 println!("fib(50) = {}", delayed_fib.get())
237 The call to `future::spawn` immediately returns a `future` object regardless of
238 how long it takes to run `fib(50)`. You can then make yourself a sandwich while
239 the computation of `fib` is running. The result of the execution of the method
240 is obtained by calling `get` on the future. This call will block until the
241 value is available (*i.e.* the computation is complete). Note that the future
242 needs to be mutable so that it can save the result for next time `get` is
245 Here is another example showing how futures allow you to background
246 computations. The workload will be distributed on the available cores.
249 # #![allow(deprecated)]
250 # use std::num::Float;
251 # use std::sync::Future;
252 fn partial_sum(start: u64) -> f64 {
253 let mut local_sum = 0f64;
254 for num in range(start*100000, (start+1)*100000) {
255 local_sum += (num as f64 + 1.0).powf(-2.0);
261 let mut futures = Vec::from_fn(200, |ind| Future::spawn(move || partial_sum(ind)));
263 let mut final_res = 0f64;
264 for ft in futures.iter_mut() {
265 final_res += ft.get();
267 println!("π^2/6 is not far from : {}", final_res);
271 ## Sharing without copying: Arc
273 To share data between threads, a first approach would be to only use channel as
274 we have seen previously. A copy of the data to share would then be made for
275 each thread. In some cases, this would add up to a significant amount of wasted
276 memory and would require copying the same data more than necessary.
278 To tackle this issue, one can use an Atomically Reference Counted wrapper
279 (`Arc`) as implemented in the `sync` library of Rust. With an Arc, the data
280 will no longer be copied for each thread. The Arc acts as a reference to the
281 shared data and only this reference is shared and cloned.
283 Here is a small example showing how to use Arcs. We wish to run concurrently
284 several computations on a single large vector of floats. Each thread needs the
285 full vector to perform its duty.
292 fn pnorm(nums: &[f64], p: u64) -> f64 {
293 nums.iter().fold(0.0, |a, b| a + b.powf(p as f64)).powf(1.0 / (p as f64))
297 let numbers = Vec::from_fn(1000000, |_| rand::random::<f64>());
298 let numbers_arc = Arc::new(numbers);
300 for num in range(1, 10) {
301 let thread_numbers = numbers_arc.clone();
304 println!("{}-norm = {}", num, pnorm(thread_numbers.as_slice(), num));
310 The function `pnorm` performs a simple computation on the vector (it computes
311 the sum of its items at the power given as argument and takes the inverse power
312 of this value). The Arc on the vector is created by the line:
316 # use std::sync::Arc;
318 # let numbers = Vec::from_fn(1000000, |_| rand::random::<f64>());
319 let numbers_arc = Arc::new(numbers);
323 and a clone is captured for each thread via a procedure. This only copies
324 the wrapper and not its contents. Within the thread's procedure, the captured
325 Arc reference can be used as a shared reference to the underlying vector as
330 # use std::sync::Arc;
331 # fn pnorm(nums: &[f64], p: u64) -> f64 { 4.0 }
333 # let numbers=Vec::from_fn(1000000, |_| rand::random::<f64>());
334 # let numbers_arc = Arc::new(numbers);
336 let thread_numbers = numbers_arc.clone();
338 // Capture thread_numbers and use it as if it was the underlying vector
339 println!("{}-norm = {}", num, pnorm(thread_numbers.as_slice(), num));
344 # Handling thread panics
346 Rust has a built-in mechanism for raising exceptions. The `panic!()` macro
347 (which can also be written with an error string as an argument: `panic!(
348 ~reason)`) and the `assert!` construct (which effectively calls `panic!()` if a
349 boolean expression is false) are both ways to raise exceptions. When a thread
350 raises an exception, the thread unwinds its stack—running destructors and
351 freeing memory along the way—and then exits. Unlike exceptions in C++,
352 exceptions in Rust are unrecoverable within a single thread: once a thread panics,
353 there is no way to "catch" the exception.
355 While it isn't possible for a thread to recover from panicking, threads may notify
356 each other if they panic. The simplest way of handling a panic is with the
357 `try` function, which is similar to `spawn`, but immediately blocks and waits
358 for the child thread to finish. `try` returns a value of type
359 `Result<T, Box<Any + Send>>`. `Result` is an `enum` type with two variants:
360 `Ok` and `Err`. In this case, because the type arguments to `Result` are `i32`
361 and `()`, callers can pattern-match on a result to check whether it's an `Ok`
362 result with an `i32` field (representing a successful result) or an `Err` result
363 (representing termination with an error).
366 # use std::thread::Thread;
367 # fn some_condition() -> bool { false }
368 # fn calculate_result() -> i32 { 0 }
369 let result: Result<i32, Box<std::any::Any + Send>> = Thread::spawn(move || {
370 if some_condition() {
376 assert!(result.is_err());
379 Unlike `spawn`, the function spawned using `try` may return a value, which
380 `try` will dutifully propagate back to the caller in a [`Result`] enum. If the
381 child thread terminates successfully, `try` will return an `Ok` result; if the
382 child thread panics, `try` will return an `Error` result.
384 [`Result`]: ../std/result/index.html
386 > *Note:* A panicked thread does not currently produce a useful error
387 > value (`try` always returns `Err(())`). In the
388 > future, it may be possible for threads to intercept the value passed to
391 But not all panics are created equal. In some cases you might need to abort
392 the entire program (perhaps you're writing an assert which, if it trips,
393 indicates an unrecoverable logic error); in other cases you might want to
394 contain the panic at a certain boundary (perhaps a small piece of input from
395 the outside world, which you happen to be processing in parallel, is malformed
396 such that the processing thread cannot proceed).