1 % The Rust Tasks and Communication Guide
5 Rust provides safe concurrency through a combination
6 of lightweight, memory-isolated tasks and message passing.
7 This guide will describe the concurrency model in Rust, how it
8 relates to the Rust type system, and introduce
9 the fundamental library abstractions for constructing concurrent programs.
11 Rust tasks are not the same as traditional threads: rather,
12 they are considered _green threads_, lightweight units of execution that the Rust
13 runtime schedules cooperatively onto a small number of operating system threads.
14 On a multi-core system Rust tasks will be scheduled in parallel by default.
15 Because tasks are significantly
16 cheaper to create than traditional threads, Rust can create hundreds of
17 thousands of concurrent tasks on a typical 32-bit system.
18 In general, all Rust code executes inside a task, including the `main` function.
20 In order to make efficient use of memory Rust tasks have dynamically sized stacks.
21 A task begins its life with a small
22 amount of stack space (currently in the low thousands of bytes, depending on
23 platform), and acquires more stack as needed.
24 Unlike in languages such as C, a Rust task cannot accidentally write to
25 memory beyond the end of the stack, causing crashes or worse.
27 Tasks provide failure isolation and recovery. When a fatal error occurs in Rust
28 code as a result of an explicit call to `fail!()`, an assertion failure, or
29 another invalid operation, the runtime system destroys the entire
30 task. Unlike in languages such as Java and C++, there is no way to `catch` an
31 exception. Instead, tasks may monitor each other for failure.
33 Tasks use Rust's type system to provide strong memory safety guarantees. In
34 particular, the type system guarantees that tasks cannot share mutable state
35 with each other. Tasks communicate with each other by transferring _owned_
36 data through the global _exchange heap_.
38 ## A note about the libraries
40 While Rust's type system provides the building blocks needed for safe
41 and efficient tasks, all of the task functionality itself is implemented
42 in the standard and sync libraries, which are still under development
43 and do not always present a consistent or complete interface.
45 For your reference, these are the standard modules involved in Rust
46 concurrency at this writing:
48 * [`std::task`] - All code relating to tasks and task scheduling,
49 * [`std::comm`] - The message passing interface,
50 * [`sync::DuplexStream`] - An extension of `pipes::stream` that allows both sending and receiving,
51 * [`sync::SyncSender`] - An extension of `pipes::stream` that provides synchronous message sending,
52 * [`sync::SyncReceiver`] - An extension of `pipes::stream` that acknowledges each message received,
53 * [`sync::rendezvous`] - Creates a stream whose channel, upon sending a message, blocks until the
55 * [`sync::Arc`] - The Arc (atomically reference counted) type, for safely sharing immutable data,
56 * [`sync::RWArc`] - A dual-mode Arc protected by a reader-writer lock,
57 * [`sync::MutexArc`] - An Arc with mutable data protected by a blocking mutex,
58 * [`sync::Semaphore`] - A counting, blocking, bounded-waiting semaphore,
59 * [`sync::Mutex`] - A blocking, bounded-waiting, mutual exclusion lock with an associated
60 FIFO condition variable,
61 * [`sync::RWLock`] - A blocking, no-starvation, reader-writer lock with an associated condvar,
62 * [`sync::Barrier`] - A barrier enables multiple tasks to synchronize the beginning
64 * [`sync::TaskPool`] - A task pool abstraction,
65 * [`sync::Future`] - A type encapsulating the result of a computation which may not be complete,
66 * [`sync::one`] - A "once initialization" primitive
67 * [`sync::mutex`] - A proper mutex implementation regardless of the "flavor of task" which is
70 [`std::task`]: std/task/index.html
71 [`std::comm`]: std/comm/index.html
72 [`sync::DuplexStream`]: sync/struct.DuplexStream.html
73 [`sync::SyncSender`]: sync/struct.SyncSender.html
74 [`sync::SyncReceiver`]: sync/struct.SyncReceiver.html
75 [`sync::rendezvous`]: sync/fn.rendezvous.html
76 [`sync::Arc`]: sync/struct.Arc.html
77 [`sync::RWArc`]: sync/struct.RWArc.html
78 [`sync::MutexArc`]: sync/struct.MutexArc.html
79 [`sync::Semaphore`]: sync/struct.Semaphore.html
80 [`sync::Mutex`]: sync/struct.Mutex.html
81 [`sync::RWLock`]: sync/struct.RWLock.html
82 [`sync::Barrier`]: sync/struct.Barrier.html
83 [`sync::TaskPool`]: sync/struct.TaskPool.html
84 [`sync::Future`]: sync/struct.Future.html
85 [`sync::one`]: sync/one/index.html
86 [`sync::mutex`]: sync/mutex/index.html
90 The programming interface for creating and managing tasks lives
91 in the `task` module of the `std` library, and is thus available to all
92 Rust code by default. At its simplest, creating a task is a matter of
93 calling the `spawn` function with a closure argument. `spawn` executes the
94 closure in the new task.
97 # use std::task::spawn;
99 // Print something profound in a different task using a named function
100 fn print_message() { println!("I am running in a different task!"); }
101 spawn(print_message);
103 // Print something more profound in a different task using a lambda expression
104 spawn(proc() println!("I am also running in a different task!") );
107 In Rust, there is nothing special about creating tasks: a task is not a
108 concept that appears in the language semantics. Instead, Rust's type system
109 provides all the tools necessary to implement safe concurrency: particularly,
110 _owned types_. The language leaves the implementation details to the standard
113 The `spawn` function has a very simple type signature: `fn spawn(f:
114 proc())`. Because it accepts only owned closures, and owned closures
115 contain only owned data, `spawn` can safely move the entire closure
116 and all its associated state into an entirely different task for
117 execution. Like any closure, the function passed to `spawn` may capture
118 an environment that it carries across tasks.
121 # use std::task::spawn;
122 # fn generate_task_number() -> int { 0 }
123 // Generate some state locally
124 let child_task_number = generate_task_number();
127 // Capture it in the remote task
128 println!("I am child number {}", child_task_number);
134 Now that we have spawned a new task, it would be nice if we could
135 communicate with it. Recall that Rust does not have shared mutable
136 state, so one task may not manipulate variables owned by another task.
137 Instead we use *pipes*.
139 A pipe is simply a pair of endpoints: one for sending messages and another for
140 receiving messages. Pipes are low-level communication building-blocks and so
141 come in a variety of forms, each one appropriate for a different use case. In
142 what follows, we cover the most commonly used varieties.
144 The simplest way to create a pipe is to use the `channel`
145 function to create a `(Sender, Receiver)` pair. In Rust parlance, a *sender*
146 is a sending endpoint of a pipe, and a *receiver* is the receiving
147 endpoint. Consider the following example of calculating two results
151 # use std::task::spawn;
153 let (tx, rx): (Sender<int>, Receiver<int>) = channel();
156 let result = some_expensive_computation();
160 some_other_expensive_computation();
161 let result = rx.recv();
162 # fn some_expensive_computation() -> int { 42 }
163 # fn some_other_expensive_computation() {}
166 Let's examine this example in detail. First, the `let` statement creates a
167 stream for sending and receiving integers (the left-hand side of the `let`,
168 `(tx, rx)`, is an example of a *destructuring let*: the pattern separates
169 a tuple into its component parts).
172 let (tx, rx): (Sender<int>, Receiver<int>) = channel();
175 The child task will use the sender to send data to the parent task,
176 which will wait to receive the data on the receiver. The next statement
177 spawns the child task.
180 # use std::task::spawn;
181 # fn some_expensive_computation() -> int { 42 }
182 # let (tx, rx) = channel();
184 let result = some_expensive_computation();
189 Notice that the creation of the task closure transfers `tx` to the child
190 task implicitly: the closure captures `tx` in its environment. Both `Sender`
191 and `Receiver` are sendable types and may be captured into tasks or otherwise
192 transferred between them. In the example, the child task runs an expensive
193 computation, then sends the result over the captured channel.
195 Finally, the parent continues with some other expensive
196 computation, then waits for the child's result to arrive on the
200 # fn some_other_expensive_computation() {}
201 # let (tx, rx) = channel::<int>();
203 some_other_expensive_computation();
204 let result = rx.recv();
207 The `Sender` and `Receiver` pair created by `channel` enables efficient
208 communication between a single sender and a single receiver, but multiple
209 senders cannot use a single `Sender` value, and multiple receivers cannot use a
210 single `Receiver` value. What if our example needed to compute multiple
211 results across a number of tasks? The following program is ill-typed:
214 # fn some_expensive_computation() -> int { 42 }
215 let (tx, rx) = channel();
218 tx.send(some_expensive_computation());
221 // ERROR! The previous spawn statement already owns the sender,
222 // so the compiler will not allow it to be captured again
224 tx.send(some_expensive_computation());
228 Instead we can clone the `tx`, which allows for multiple senders.
231 let (tx, rx) = channel();
233 for init_val in range(0u, 3) {
234 // Create a new channel handle to distribute to the child task
235 let child_tx = tx.clone();
237 child_tx.send(some_expensive_computation(init_val));
241 let result = rx.recv() + rx.recv() + rx.recv();
242 # fn some_expensive_computation(_i: uint) -> int { 42 }
245 Cloning a `Sender` produces a new handle to the same channel, allowing multiple
246 tasks to send data to a single receiver. It upgrades the channel internally in
247 order to allow this functionality, which means that channels that are not
248 cloned can avoid the overhead required to handle multiple senders. But this
249 fact has no bearing on the channel's usage: the upgrade is transparent.
251 Note that the above cloning example is somewhat contrived since
252 you could also simply use three `Sender` pairs, but it serves to
253 illustrate the point. For reference, written with multiple streams, it
254 might look like the example below.
257 # use std::task::spawn;
259 // Create a vector of ports, one for each child task
260 let rxs = Vec::from_fn(3, |init_val| {
261 let (tx, rx) = channel();
263 tx.send(some_expensive_computation(init_val));
268 // Wait on each port, accumulating the results
269 let result = rxs.iter().fold(0, |accum, rx| accum + rx.recv() );
270 # fn some_expensive_computation(_i: uint) -> int { 42 }
273 ## Backgrounding computations: Futures
274 With `sync::Future`, rust has a mechanism for requesting a computation and getting the result
277 The basic example below illustrates this.
283 # fn make_a_sandwich() {};
284 fn fib(n: u64) -> u64 {
285 // lengthy computation returning an uint
289 let mut delayed_fib = sync::Future::spawn(proc() fib(50));
291 println!("fib(50) = {:?}", delayed_fib.get())
295 The call to `future::spawn` returns immediately a `future` object regardless of how long it
296 takes to run `fib(50)`. You can then make yourself a sandwich while the computation of `fib` is
297 running. The result of the execution of the method is obtained by calling `get` on the future.
298 This call will block until the value is available (*i.e.* the computation is complete). Note that
299 the future needs to be mutable so that it can save the result for next time `get` is called.
301 Here is another example showing how futures allow you to background computations. The workload will
302 be distributed on the available cores.
306 fn partial_sum(start: uint) -> f64 {
307 let mut local_sum = 0f64;
308 for num in range(start*100000, (start+1)*100000) {
309 local_sum += (num as f64 + 1.0).powf(&-2.0);
315 let mut futures = Vec::from_fn(1000, |ind| sync::Future::spawn( proc() { partial_sum(ind) }));
317 let mut final_res = 0f64;
318 for ft in futures.mut_iter() {
319 final_res += ft.get();
321 println!("π^2/6 is not far from : {}", final_res);
325 ## Sharing immutable data without copy: Arc
327 To share immutable data between tasks, a first approach would be to only use pipes as we have seen
328 previously. A copy of the data to share would then be made for each task. In some cases, this would
329 add up to a significant amount of wasted memory and would require copying the same data more than
332 To tackle this issue, one can use an Atomically Reference Counted wrapper (`Arc`) as implemented in
333 the `sync` library of Rust. With an Arc, the data will no longer be copied for each task. The Arc
334 acts as a reference to the shared data and only this reference is shared and cloned.
336 Here is a small example showing how to use Arcs. We wish to run concurrently several computations on
337 a single large vector of floats. Each task needs the full vector to perform its duty.
345 fn pnorm(nums: &[f64], p: uint) -> f64 {
346 nums.iter().fold(0.0, |a,b| a+(*b).powf(&(p as f64)) ).powf(&(1.0 / (p as f64)))
350 let numbers = Vec::from_fn(1000000, |_| rand::random::<f64>());
351 let numbers_arc = Arc::new(numbers);
353 for num in range(1u, 10) {
354 let (tx, rx) = channel();
355 tx.send(numbers_arc.clone());
358 let local_arc : Arc<Vec<f64>> = rx.recv();
359 let task_numbers = &*local_arc;
360 println!("{}-norm = {}", num, pnorm(task_numbers.as_slice(), num));
366 The function `pnorm` performs a simple computation on the vector (it computes the sum of its items
367 at the power given as argument and takes the inverse power of this value). The Arc on the vector is
375 # let numbers = Vec::from_fn(1000000, |_| rand::random::<f64>());
376 let numbers_arc=Arc::new(numbers);
380 and a clone of it is sent to each task
387 # let numbers=Vec::from_fn(1000000, |_| rand::random::<f64>());
388 # let numbers_arc = Arc::new(numbers);
389 # let (tx, rx) = channel();
390 tx.send(numbers_arc.clone());
394 copying only the wrapper and not its contents.
396 Each task recovers the underlying data by
403 # let numbers=Vec::from_fn(1000000, |_| rand::random::<f64>());
404 # let numbers_arc=Arc::new(numbers);
405 # let (tx, rx) = channel();
406 # tx.send(numbers_arc.clone());
407 # let local_arc : Arc<Vec<f64>> = rx.recv();
408 let task_numbers = &*local_arc;
412 and can use it as if it were local.
414 The `arc` module also implements Arcs around mutable data that are not covered here.
416 # Handling task failure
418 Rust has a built-in mechanism for raising exceptions. The `fail!()` macro
419 (which can also be written with an error string as an argument: `fail!(
420 ~reason)`) and the `assert!` construct (which effectively calls `fail!()`
421 if a boolean expression is false) are both ways to raise exceptions. When a
422 task raises an exception the task unwinds its stack---running destructors and
423 freeing memory along the way---and then exits. Unlike exceptions in C++,
424 exceptions in Rust are unrecoverable within a single task: once a task fails,
425 there is no way to "catch" the exception.
427 While it isn't possible for a task to recover from failure, tasks may notify
428 each other of failure. The simplest way of handling task failure is with the
429 `try` function, which is similar to `spawn`, but immediately blocks waiting
430 for the child task to finish. `try` returns a value of type `Result<T,
431 ()>`. `Result` is an `enum` type with two variants: `Ok` and `Err`. In this
432 case, because the type arguments to `Result` are `int` and `()`, callers can
433 pattern-match on a result to check whether it's an `Ok` result with an `int`
434 field (representing a successful result) or an `Err` result (representing
435 termination with an error).
437 ~~~{.ignore .linked-failure}
439 # fn some_condition() -> bool { false }
440 # fn calculate_result() -> int { 0 }
441 let result: Result<int, ()> = task::try(proc() {
442 if some_condition() {
448 assert!(result.is_err());
451 Unlike `spawn`, the function spawned using `try` may return a value,
452 which `try` will dutifully propagate back to the caller in a [`Result`]
453 enum. If the child task terminates successfully, `try` will
454 return an `Ok` result; if the child task fails, `try` will return
457 [`Result`]: std/result/index.html
459 > ***Note:*** A failed task does not currently produce a useful error
460 > value (`try` always returns `Err(())`). In the
461 > future, it may be possible for tasks to intercept the value passed to
464 TODO: Need discussion of `future_result` in order to make failure
467 But not all failures are created equal. In some cases you might need to
468 abort the entire program (perhaps you're writing an assert which, if
469 it trips, indicates an unrecoverable logic error); in other cases you
470 might want to contain the failure at a certain boundary (perhaps a
471 small piece of input from the outside world, which you happen to be
472 processing in parallel, is malformed and its processing task can't
475 ## Creating a task with a bi-directional communication path
477 A very common thing to do is to spawn a child task where the parent
478 and child both need to exchange messages with each other. The
479 function `sync::comm::duplex` supports this pattern. We'll
480 look briefly at how to use it.
482 To see how `duplex` works, we will create a child task
483 that repeatedly receives a `uint` message, converts it to a string, and sends
484 the string in response. The child terminates when it receives `0`.
485 Here is the function that implements the child task:
490 fn stringifier(channel: &sync::DuplexStream<~str, uint>) {
493 value = channel.recv();
494 channel.send(value.to_str());
495 if value == 0 { break; }
501 The implementation of `DuplexStream` supports both sending and
502 receiving. The `stringifier` function takes a `DuplexStream` that can
503 send strings (the first type parameter) and receive `uint` messages
504 (the second type parameter). The body itself simply loops, reading
505 from the channel and then sending its response back. The actual
506 response itself is simply the stringified version of the received value,
507 `uint::to_str(value)`.
509 Here is the code for the parent task:
513 # use std::task::spawn;
514 # use sync::DuplexStream;
515 # fn stringifier(channel: &sync::DuplexStream<~str, uint>) {
516 # let mut value: uint;
518 # value = channel.recv();
519 # channel.send(value.to_str());
520 # if value == 0u { break; }
525 let (from_child, to_child) = sync::duplex();
528 stringifier(&to_child);
532 assert!(from_child.recv() == "22".to_owned());
537 assert!(from_child.recv() == "23".to_owned());
538 assert!(from_child.recv() == "0".to_owned());
543 The parent task first calls `DuplexStream` to create a pair of bidirectional
544 endpoints. It then uses `task::spawn` to create the child task, which captures
545 one end of the communication channel. As a result, both parent and child can
546 send and receive data to and from the other.