1 % The Rust Tasks and Communication Guide
5 Rust provides safe concurrent abstractions through a number of core library
6 primitives. This guide will describe the concurrency model in Rust, how it
7 relates to the Rust type system, and introduce the fundamental library
8 abstractions for constructing concurrent programs.
10 Tasks provide failure isolation and recovery. When a fatal error occurs in Rust
11 code as a result of an explicit call to `fail!()`, an assertion failure, or
12 another invalid operation, the runtime system destroys the entire task. Unlike
13 in languages such as Java and C++, there is no way to `catch` an exception.
14 Instead, tasks may monitor each other for failure.
16 Tasks use Rust's type system to provide strong memory safety guarantees. In
17 particular, the type system guarantees that tasks cannot induce a data race
18 from shared mutable state.
22 At its simplest, creating a task is a matter of calling the `spawn` function
23 with a closure argument. `spawn` executes the closure in the new task.
26 # use std::task::spawn;
28 // Print something profound in a different task using a named function
29 fn print_message() { println!("I am running in a different task!"); }
32 // Alternatively, use a `proc` expression instead of a named function.
33 // The `proc` expression evaluates to an (unnamed) proc.
34 // That proc will call `println!(...)` when the spawned task runs.
35 spawn(proc() println!("I am also running in a different task!") );
38 In Rust, a task is not a concept that appears in the language semantics.
39 Instead, Rust's type system provides all the tools necessary to implement safe
40 concurrency: particularly, ownership. The language leaves the implementation
41 details to the standard library.
43 The `spawn` function has a very simple type signature: `fn spawn(f: proc():
44 Send)`. Because it accepts only procs, and procs contain only owned data,
45 `spawn` can safely move the entire proc and all its associated state into an
46 entirely different task for execution. Like any closure, the function passed to
47 `spawn` may capture an environment that it carries across tasks.
50 # use std::task::spawn;
51 # fn generate_task_number() -> int { 0 }
52 // Generate some state locally
53 let child_task_number = generate_task_number();
56 // Capture it in the remote task
57 println!("I am child number {}", child_task_number);
63 Now that we have spawned a new task, it would be nice if we could communicate
64 with it. For this, we use *channels*. A channel is simply a pair of endpoints:
65 one for sending messages and another for receiving messages.
67 The simplest way to create a channel is to use the `channel` function to create a
68 `(Sender, Receiver)` pair. In Rust parlance, a **sender** is a sending endpoint
69 of a channel, and a **receiver** is the receiving endpoint. Consider the following
70 example of calculating two results concurrently:
73 # use std::task::spawn;
75 let (tx, rx): (Sender<int>, Receiver<int>) = channel();
78 let result = some_expensive_computation();
82 some_other_expensive_computation();
83 let result = rx.recv();
84 # fn some_expensive_computation() -> int { 42 }
85 # fn some_other_expensive_computation() {}
88 Let's examine this example in detail. First, the `let` statement creates a
89 stream for sending and receiving integers (the left-hand side of the `let`,
90 `(tx, rx)`, is an example of a destructuring let: the pattern separates a tuple
91 into its component parts).
94 let (tx, rx): (Sender<int>, Receiver<int>) = channel();
97 The child task will use the sender to send data to the parent task, which will
98 wait to receive the data on the receiver. The next statement spawns the child
102 # use std::task::spawn;
103 # fn some_expensive_computation() -> int { 42 }
104 # let (tx, rx) = channel();
106 let result = some_expensive_computation();
111 Notice that the creation of the task closure transfers `tx` to the child task
112 implicitly: the closure captures `tx` in its environment. Both `Sender` and
113 `Receiver` are sendable types and may be captured into tasks or otherwise
114 transferred between them. In the example, the child task runs an expensive
115 computation, then sends the result over the captured channel.
117 Finally, the parent continues with some other expensive computation, then waits
118 for the child's result to arrive on the receiver:
121 # fn some_other_expensive_computation() {}
122 # let (tx, rx) = channel::<int>();
124 some_other_expensive_computation();
125 let result = rx.recv();
128 The `Sender` and `Receiver` pair created by `channel` enables efficient
129 communication between a single sender and a single receiver, but multiple
130 senders cannot use a single `Sender` value, and multiple receivers cannot use a
131 single `Receiver` value. What if our example needed to compute multiple
132 results across a number of tasks? The following program is ill-typed:
135 # fn some_expensive_computation() -> int { 42 }
136 let (tx, rx) = channel();
139 tx.send(some_expensive_computation());
142 // ERROR! The previous spawn statement already owns the sender,
143 // so the compiler will not allow it to be captured again
145 tx.send(some_expensive_computation());
149 Instead we can clone the `tx`, which allows for multiple senders.
152 let (tx, rx) = channel();
154 for init_val in range(0u, 3) {
155 // Create a new channel handle to distribute to the child task
156 let child_tx = tx.clone();
158 child_tx.send(some_expensive_computation(init_val));
162 let result = rx.recv() + rx.recv() + rx.recv();
163 # fn some_expensive_computation(_i: uint) -> int { 42 }
166 Cloning a `Sender` produces a new handle to the same channel, allowing multiple
167 tasks to send data to a single receiver. It upgrades the channel internally in
168 order to allow this functionality, which means that channels that are not
169 cloned can avoid the overhead required to handle multiple senders. But this
170 fact has no bearing on the channel's usage: the upgrade is transparent.
172 Note that the above cloning example is somewhat contrived since you could also
173 simply use three `Sender` pairs, but it serves to illustrate the point. For
174 reference, written with multiple streams, it might look like the example below.
177 # use std::task::spawn;
179 // Create a vector of ports, one for each child task
180 let rxs = Vec::from_fn(3, |init_val| {
181 let (tx, rx) = channel();
183 tx.send(some_expensive_computation(init_val));
188 // Wait on each port, accumulating the results
189 let result = rxs.iter().fold(0, |accum, rx| accum + rx.recv() );
190 # fn some_expensive_computation(_i: uint) -> int { 42 }
193 ## Backgrounding computations: Futures
195 With `sync::Future`, rust has a mechanism for requesting a computation and
196 getting the result later.
198 The basic example below illustrates this.
201 use std::sync::Future;
204 # fn make_a_sandwich() {};
205 fn fib(n: u64) -> u64 {
206 // lengthy computation returning an uint
210 let mut delayed_fib = Future::spawn(proc() fib(50));
212 println!("fib(50) = {}", delayed_fib.get())
216 The call to `future::spawn` returns immediately a `future` object regardless of
217 how long it takes to run `fib(50)`. You can then make yourself a sandwich while
218 the computation of `fib` is running. The result of the execution of the method
219 is obtained by calling `get` on the future. This call will block until the
220 value is available (*i.e.* the computation is complete). Note that the future
221 needs to be mutable so that it can save the result for next time `get` is
224 Here is another example showing how futures allow you to background
225 computations. The workload will be distributed on the available cores.
228 # use std::sync::Future;
229 fn partial_sum(start: uint) -> f64 {
230 let mut local_sum = 0f64;
231 for num in range(start*100000, (start+1)*100000) {
232 local_sum += (num as f64 + 1.0).powf(-2.0);
238 let mut futures = Vec::from_fn(200, |ind| Future::spawn( proc() { partial_sum(ind) }));
240 let mut final_res = 0f64;
241 for ft in futures.iter_mut() {
242 final_res += ft.get();
244 println!("π^2/6 is not far from : {}", final_res);
248 ## Sharing without copying: Arc
250 To share data between tasks, a first approach would be to only use channel as
251 we have seen previously. A copy of the data to share would then be made for
252 each task. In some cases, this would add up to a significant amount of wasted
253 memory and would require copying the same data more than necessary.
255 To tackle this issue, one can use an Atomically Reference Counted wrapper
256 (`Arc`) as implemented in the `sync` library of Rust. With an Arc, the data
257 will no longer be copied for each task. The Arc acts as a reference to the
258 shared data and only this reference is shared and cloned.
260 Here is a small example showing how to use Arcs. We wish to run concurrently
261 several computations on a single large vector of floats. Each task needs the
262 full vector to perform its duty.
268 fn pnorm(nums: &[f64], p: uint) -> f64 {
269 nums.iter().fold(0.0, |a, b| a + b.powf(p as f64)).powf(1.0 / (p as f64))
273 let numbers = Vec::from_fn(1000000, |_| rand::random::<f64>());
274 let numbers_arc = Arc::new(numbers);
276 for num in range(1u, 10) {
277 let task_numbers = numbers_arc.clone();
280 println!("{}-norm = {}", num, pnorm(task_numbers.as_slice(), num));
286 The function `pnorm` performs a simple computation on the vector (it computes
287 the sum of its items at the power given as argument and takes the inverse power
288 of this value). The Arc on the vector is created by the line:
292 # use std::sync::Arc;
294 # let numbers = Vec::from_fn(1000000, |_| rand::random::<f64>());
295 let numbers_arc = Arc::new(numbers);
299 and a clone is captured for each task via a procedure. This only copies
300 the wrapper and not it's contents. Within the task's procedure, the captured
301 Arc reference can be used as a shared reference to the underlying vector as
306 # use std::sync::Arc;
307 # fn pnorm(nums: &[f64], p: uint) -> f64 { 4.0 }
309 # let numbers=Vec::from_fn(1000000, |_| rand::random::<f64>());
310 # let numbers_arc = Arc::new(numbers);
312 let task_numbers = numbers_arc.clone();
314 // Capture task_numbers and use it as if it was the underlying vector
315 println!("{}-norm = {}", num, pnorm(task_numbers.as_slice(), num));
320 # Handling task failure
322 Rust has a built-in mechanism for raising exceptions. The `fail!()` macro
323 (which can also be written with an error string as an argument: `fail!(
324 ~reason)`) and the `assert!` construct (which effectively calls `fail!()` if a
325 boolean expression is false) are both ways to raise exceptions. When a task
326 raises an exception the task unwinds its stack---running destructors and
327 freeing memory along the way---and then exits. Unlike exceptions in C++,
328 exceptions in Rust are unrecoverable within a single task: once a task fails,
329 there is no way to "catch" the exception.
331 While it isn't possible for a task to recover from failure, tasks may notify
332 each other of failure. The simplest way of handling task failure is with the
333 `try` function, which is similar to `spawn`, but immediately blocks waiting for
334 the child task to finish. `try` returns a value of type `Result<T, Box<Any +
335 Send>>`. `Result` is an `enum` type with two variants: `Ok` and `Err`. In this
336 case, because the type arguments to `Result` are `int` and `()`, callers can
337 pattern-match on a result to check whether it's an `Ok` result with an `int`
338 field (representing a successful result) or an `Err` result (representing
339 termination with an error).
343 # fn some_condition() -> bool { false }
344 # fn calculate_result() -> int { 0 }
345 let result: Result<int, Box<std::any::Any + Send>> = task::try(proc() {
346 if some_condition() {
352 assert!(result.is_err());
355 Unlike `spawn`, the function spawned using `try` may return a value, which
356 `try` will dutifully propagate back to the caller in a [`Result`] enum. If the
357 child task terminates successfully, `try` will return an `Ok` result; if the
358 child task fails, `try` will return an `Error` result.
360 [`Result`]: std/result/index.html
362 > *Note:* A failed task does not currently produce a useful error
363 > value (`try` always returns `Err(())`). In the
364 > future, it may be possible for tasks to intercept the value passed to
367 But not all failures are created equal. In some cases you might need to abort
368 the entire program (perhaps you're writing an assert which, if it trips,
369 indicates an unrecoverable logic error); in other cases you might want to
370 contain the failure at a certain boundary (perhaps a small piece of input from
371 the outside world, which you happen to be processing in parallel, is malformed
372 and its processing task can't proceed).