1.1 A note about the libraries

While Rust's type system provides the building blocks needed for safe and efficient tasks, all of the task functionality itself is implemented in the core and standard libraries, which are still under development and do not always present a consistent interface.

In particular, there are currently two independent modules that provide a message passing interface to Rust code: core::comm and core::pipes. core::comm is an older, less efficient system that is being phased out in favor of pipes. At some point, we will remove the existing core::comm API and move the user-facing portions of core::pipes to core::comm. In this tutorial, we discuss pipes and ignore the comm API.

For your reference, these are the standard modules involved in Rust concurrency at this writing.

• core::task - All code relating to tasks and task scheduling
• core::comm - The deprecated message passing API
• core::pipes - The new message passing infrastructure and API
• std::comm - Higher level messaging types based on core::pipes
• std::sync - More exotic synchronization tools, including locks
• std::arc - The ARC (atomic reference counted) type, for safely sharing immutable data
• std::par - Some basic tools for implementing parallel algorithms

use task::spawn;

// Print something profound in a different task using a named function
fn print_message() { println("I am running in a different task!"); }
spawn(print_message);

// Print something more profound in a different task using a lambda expression
spawn( || println("I am also running in a different task!") );

// The canonical way to spawn is using `do` notation
do spawn {
    println("I too am running in a different task!");
}

// Generate some state locally
let child_task_number = generate_task_number();

do spawn {
   // Capture it in the remote task
   println(fmt!("I am child number %d", child_task_number));
}

for int::range(0, 20) |child_task_number| {
    do spawn {
       print(fmt!("I am child number %d\n", child_task_number));
    }
}

2.1 Communication

Now that we have spawned a new task, it would be nice if we could communicate with it. Recall that Rust does not have shared mutable state, so one task may not manipulate variables owned by another task. Instead we use pipes.

A pipe is simply a pair of endpoints: one for sending messages and another for receiving messages. Pipes are low-level communication building-blocks and so come in a variety of forms, each one appropriate for a different use case. In what follows, we cover the most commonly used varieties.

The simplest way to create a pipe is to use the pipes::stream function to create a (Port, Chan) pair. In Rust parlance, a channel is a sending endpoint of a pipe, and a port is the receiving endpoint. Consider the following example of calculating two results concurrently:

use task::spawn;
use pipes::{stream, Port, Chan};

let (port, chan): (Port<int>, Chan<int>) = stream();

do spawn |move chan| {
    let result = some_expensive_computation();
    chan.send(result);
}

some_other_expensive_computation();
let result = port.recv();

Let's examine this example in detail. First, the let statement creates a stream for sending and receiving integers (the left-hand side of the let, (chan, port), is an example of a destructuring let: the pattern separates a tuple into its component parts).

let (port, chan): (Port<int>, Chan<int>) = stream();

The child task will use the channel to send data to the parent task, which will wait to receive the data on the port. The next statement spawns the child task.

do spawn |move chan| {
    let result = some_expensive_computation();
    chan.send(result);
}

Notice that the creation of the task closure transfers chan to the child task implicitly: the closure captures chan in its environment. Both Chan and Port are sendable types and may be captured into tasks or otherwise transferred between them. In the example, the child task runs an expensive computation, then sends the result over the captured channel.

Finally, the parent continues with some other expensive computation, then waits for the child's result to arrive on the port:

some_other_expensive_computation();
let result = port.recv();

The Port and Chan pair created by stream enables efficient communication between a single sender and a single receiver, but multiple senders cannot use a single Chan, and multiple receivers cannot use a single Port. What if our example needed to computer multiple results across a number of tasks? The following program is ill-typed:

let (port, chan) = stream();

do spawn |move chan| {
    chan.send(some_expensive_computation());
}

// ERROR! The previous spawn statement already owns the channel,
// so the compiler will not allow it to be captured again
do spawn {
    chan.send(some_expensive_computation());
}

Instead we can use a SharedChan, a type that allows a single Chan to be shared by multiple senders.

use pipes::{stream, SharedChan};

let (port, chan) = stream();
let chan = SharedChan(move chan);

for uint::range(0, 3) |init_val| {
    // Create a new channel handle to distribute to the child task
    let child_chan = chan.clone();
    do spawn |move child_chan| {
        child_chan.send(some_expensive_computation(init_val));
    }
}

let result = port.recv() + port.recv() + port.recv();

Here we transfer ownership of the channel into a new SharedChan value. Like Chan, SharedChan is a non-copyable, owned type (sometimes also referred to as an affine or linear type). Unlike with Chan, though, the programmer may duplicate a SharedChan, with the clone() method. A cloned SharedChan produces a new handle to the same channel, allowing multiple tasks to send data to a single port. Between spawn, stream and SharedChan, we have enough tools to implement many useful concurrency patterns.

Note that the above SharedChan example is somewhat contrived since you could also simply use three stream pairs, but it serves to illustrate the point. For reference, written with multiple streams, it might look like the example below.

// Create a vector of ports, one for each child task
let ports = do vec::from_fn(3) |init_val| {
    let (port, chan) = stream();
    do spawn |move chan| {
        chan.send(some_expensive_computation(init_val));
    }
    move port
};

// Wait on each port, accumulating the results
let result = ports.foldl(0, |accum, port| *accum + port.recv() );

// Create a child task that fails
do spawn { fail }

// This will also fail because the task we spawned failed
do_some_work();

let result: Result<int, ()> = do task::try {
    if some_condition() {
        calculate_result()
    } else {
        fail ~"oops!";
    }
};
assert result.is_err();

3.1 Failure modes

By default, task failure is bidirectionally linked, which means that if either task dies, it kills the other one.

do task::spawn {
    do task::spawn {
        fail;  // All three tasks will die.
    }
    sleep_forever();  // Will get woken up by force, then fail
}
sleep_forever();  // Will get woken up by force, then fail

If you want parent tasks to be able to kill their children, but do not want a parent to die automatically if one of its child task dies, you can call task::spawn_supervised for unidirectionally linked failure. The function task::try, which we saw previously, uses spawn_supervised internally, with additional logic to wait for the child task to finish before returning. Hence:

let (receiver, sender): (Port<int>, Chan<int>) = stream();
do spawn |move receiver| {  // Bidirectionally linked
    // Wait for the supervised child task to exist.
    let message = receiver.recv();
    // Kill both it and the parent task.
    assert message != 42;
}
do try |move sender| {  // Unidirectionally linked
    sender.send(42);
    sleep_forever();  // Will get woken up by force
}
// Flow never reaches here -- parent task was killed too.

Supervised failure is useful in any situation where one task manages multiple fallible child tasks, and the parent task can recover if any child fails. On the other hand, if the parent (supervisor) fails, then there is nothing the children can do to recover, so they should also fail.

Supervised task failure propagates across multiple generations even if an intermediate generation has already exited:

do task::spawn_supervised {
    do task::spawn_supervised {
        sleep_forever();  // Will get woken up by force, then fail
    }
    // Intermediate task immediately exits
}
wait_for_a_while();
fail;  // Will kill grandchild even if child has already exited

Finally, tasks can be configured to not propagate failure to each other at all, using task::spawn_unlinked for isolated failure.

let (time1, time2) = (random(), random());
do task::spawn_unlinked {
    sleep_for(time2);  // Won't get forced awake
    fail;
}
sleep_for(time1);  // Won't get forced awake
fail;
// It will take MAX(time1,time2) for the program to finish.

3.2 Creating a task with a bi-directional communication path

A very common thing to do is to spawn a child task where the parent and child both need to exchange messages with each other. The function std::comm::DuplexStream() supports this pattern. We'll look briefly at how to use it.

To see how DuplexStream() works, we will create a child task that repeatedly receives a uint message, converts it to a string, and sends the string in response. The child terminates when it receives 0. Here is the function that implements the child task:

fn stringifier(channel: &DuplexStream<~str, uint>) {
    let mut value: uint;
    loop {
        value = channel.recv();
        channel.send(uint::to_str(value, 10));
        if value == 0 { break; }
    }
}

The implementation of DuplexStream supports both sending and receiving. The stringifier function takes a DuplexStream that can send strings (the first type parameter) and receive uint messages (the second type parameter). The body itself simply loops, reading from the channel and then sending its response back. The actual response itself is simply the stringified version of the received value, uint::to_str(value).

Here is the code for the parent task:

let (from_child, to_child) = DuplexStream();

do spawn |move to_child| {
    stringifier(&to_child);
};

from_child.send(22);
assert from_child.recv() == ~"22";

from_child.send(23);
from_child.send(0);

assert from_child.recv() == ~"23";
assert from_child.recv() == ~"0";

The parent task first calls DuplexStream to create a pair of bidirectional endpoints. It then uses task::spawn to create the child task, which captures one end of the communication channel. As a result, both parent and child can send and receive data to and from the other.