---

yaml
---
r: 30695
b: refs/heads/incoming
c: fd0de8b
h: refs/heads/master
i:
  30693: ca25b74
  30691: 4750c96
  30687: 7c7140d
v: v3

Author: brson

[refs]

@@ -6,7 +6,7 @@ refs/heads/try: d324a424d8f84b1eb049b12cf34182bda91b0024
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: d0c6ce338884ee21843f4b40bf6bf18d222ce5df
-refs/heads/incoming: 6caafaa9ea44d404733af6f9a907b6295dccc966
+refs/heads/incoming: fd0de8bfd70b01dd01ca541bfdfb52703fa44d9c
 refs/heads/dist-snap: 2f32a1581f522e524009138b33b1c7049ced668d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/incoming/configure

@@ -508,6 +508,7 @@ do
     make_dir $h/test/doc-tutorial-ffi
     make_dir $h/test/doc-tutorial-macros
     make_dir $h/test/doc-tutorial-borrowed-ptr
+    make_dir $h/test/doc-tutorial-tasks
     make_dir $h/test/doc-ref
 done
 

branches/incoming/doc/tutorial-tasks.md

@@ -0,0 +1,173 @@
+% Tasks and communication in Rust
+
+Rust supports a system of lightweight tasks, similar to what is found
+in Erlang or other actor systems. Rust tasks communicate via messages
+and do not share data. However, it is possible to send data without
+copying it by making use of [the exchange heap](#unique-boxes), which
+allow the sending task to release ownership of a value, so that the
+receiving task can keep on using it.
+
+> ***Note:*** As Rust evolves, we expect the task API to grow and
+> change somewhat.  The tutorial documents the API as it exists today.
+
+# Spawning a task
+
+Spawning a task is done using the various spawn functions in the
+module `task`.  Let's begin with the simplest one, `task::spawn()`:
+
+~~~~
+use task::spawn;
+use io::println;
+
+let some_value = 22;
+
+do spawn {
+    println(~"This executes in the child task.");
+    println(fmt!("%d", some_value));
+}
+~~~~
+
+The argument to `task::spawn()` is a [unique
+closure](#unique-closures) of type `fn~()`, meaning that it takes no
+arguments and generates no return value. The effect of `task::spawn()`
+is to fire up a child task that will execute the closure in parallel
+with the creator.
+
+# Communication
+
+Now that we have spawned a child task, it would be nice if we could
+communicate with it. This is done using *pipes*. Pipes are simply a
+pair of endpoints, with one for sending messages and another for
+receiving messages. The easiest way to create a pipe is to use
+`pipes::stream`.  Imagine we wish to perform two expensive
+computations in parallel.  We might write something like:
+
+~~~~
+use task::spawn;
+use pipes::{stream, Port, Chan};
+
+let (chan, port) = stream();
+
+do spawn {
+    let result = some_expensive_computation();
+    chan.send(result);
+}
+
+some_other_expensive_computation();
+let result = port.recv();
+
+# fn some_expensive_computation() -> int { 42 }
+# fn some_other_expensive_computation() {}
+~~~~
+
+Let's walk through this code line-by-line.  The first line creates a
+stream for sending and receiving integers:
+
+~~~~ {.ignore}
+# use pipes::stream;
+let (chan, port) = stream();
+~~~~
+
+This port is where we will receive the message from the child task
+once it is complete.  The channel will be used by the child to send a
+message to the port.  The next statement actually spawns the child:
+
+~~~~
+# use task::{spawn};
+# use comm::{Port, Chan};
+# fn some_expensive_computation() -> int { 42 }
+# let port = Port();
+# let chan = port.chan();
+do spawn {
+    let result = some_expensive_computation();
+    chan.send(result);
+}
+~~~~
+
+This child will perform the expensive computation send the result
+over the channel.  (Under the hood, `chan` was captured by the
+closure that forms the body of the child task.  This capture is
+allowed because channels are sendable.)
+
+Finally, the parent continues by performing
+some other expensive computation and then waiting for the child's result
+to arrive on the port:
+
+~~~~
+# use pipes::{stream, Port, Chan};
+# fn some_other_expensive_computation() {}
+# let (chan, port) = stream::<int>();
+# chan.send(0);
+some_other_expensive_computation();
+let result = port.recv();
+~~~~
+
+# 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 it is used.
+
+To see how `spawn_conversation()` works, we will create a child task
+that receives `uint` messages, converts them to a string, and sends
+the string in response.  The child terminates when `0` is received.
+Here is the function that implements the child task:
+
+~~~~
+# use std::comm::DuplexStream;
+# use pipes::{Port, Chan};
+fn stringifier(channel: &DuplexStream<~str, uint>) {
+    let mut value: uint;
+    loop {
+        value = channel.recv();
+        channel.send(uint::to_str(value, 10u));
+        if value == 0u { 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 strified version of the received value,
+`uint::to_str(value)`.
+
+Here is the code for the parent task:
+
+~~~~
+# use std::comm::DuplexStream;
+# use pipes::{Port, Chan};
+# use task::spawn;
+# fn stringifier(channel: &DuplexStream<~str, uint>) {
+#     let mut value: uint;
+#     loop {
+#         value = channel.recv();
+#         channel.send(uint::to_str(value, 10u));
+#         if value == 0u { break; }
+#     }
+# }
+# fn main() {
+
+let (from_child, to_child) = DuplexStream();
+
+do spawn || {
+    stringifier(&to_child);
+};
+
+from_child.send(22u);
+assert from_child.recv() == ~"22";
+
+from_child.send(23u);
+from_child.send(0u);
+
+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.