---

yaml
---
r: 22225
b: refs/heads/snap-stage3
c: ebdb4b7
h: refs/heads/master
i:
  22223: 3918a57
v: v3

Author: Daniel Patterson

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: e430a699f2c60890d9b86069fd0c68a70ece7120
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: fa010a6ee45f5ca106a4a475e06f4fa75d0c0970
+refs/heads/snap-stage3: ebdb4b7ef793a1f49e307a7a39567b733c5624c8
 refs/heads/try: ffbe0e0e00374358b789b0037bcb3a577cd218be
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/doc/tutorial-tasks.md

@@ -2,16 +2,12 @@
 
 # Introduction
 
-The Rust language is designed from the ground up to support pervasive
-and safe concurrency through lightweight, memory-isolated tasks and
-message passing.
-
-Rust tasks are not the same as traditional threads - they are what are
-often referred to as _green threads_, cooperatively scheduled by the
-Rust runtime onto a small number of operating system threads.  Being
-significantly cheaper to create than traditional threads, Rust can
-create hundreds of thousands of concurrent tasks on a typical 32-bit
-system.
+Rust supports concurrency and parallelism through lightweight tasks.
+Rust tasks are significantly cheaper to create than traditional
+threads, with a typical 32-bit system able to run hundreds of
+thousands simultaneously. Tasks in Rust are what are often referred to
+as _green threads_, cooperatively scheduled by the Rust runtime onto a
+small number of operating system threads.
 
 Tasks provide failure isolation and recovery. When an exception occurs
 in rust code (either by calling `fail` explicitly or by otherwise performing
@@ -20,11 +16,11 @@ to `catch` an exception as in other languages. Instead tasks may monitor
 each other to detect when failure has occurred.
 
 Rust tasks have dynamically sized stacks. When a task is first created
-it starts off with a small amount of stack (currently in the low
-thousands of bytes, depending on platform) and more stack is acquired as
-needed. A Rust task will never run off the end of the stack as is
-possible in many other languages, but they do have a stack budget, and
-if a Rust task exceeds its stack budget then it will fail safely.
+it starts off with a small amount of stack (in the hundreds to
+low thousands of bytes, depending on plattform), and more stack is
+added as needed. A Rust task will never run off the end of the stack as
+is possible in many other languages, but they do have a stack budget,
+and if a Rust task exceeds its stack budget then it will fail safely.
 
 Tasks make use of Rust's type system to provide strong memory safety
 guarantees, disallowing shared mutable state. Communication between
@@ -36,12 +32,12 @@ explore some typical patterns in concurrent Rust code, and finally
 discuss some of the more exotic synchronization types in the standard
 library.
 
-## A note about the libraries
+# 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.
+and do not always present a nice programming interface.
 
 In particular, there are currently two independent modules that provide
 a message passing interface to Rust code: `core::comm` and `core::pipes`.
@@ -70,96 +66,43 @@ concurrency at the moment.
 [`std::arc`]: std/arc.html
 [`std::par`]: std/par.html
 
-# Basics
+# Spawning a task
 
-The programming interface for creating and managing tasks is contained
-in the `task` module of the `core` library, making it available to all
-Rust code by default. At it's simplest, creating a task is a matter of
-calling the `spawn` function, passing a closure to run in the new
-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 io::println;
 use task::spawn;
+use io::println;
 
-// 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!") );
+let some_value = 22;
 
-// The canonical way to spawn is using `do` notation
 do spawn {
-    println("I too am running in a different task!");
+    println(~"This executes in the child task.");
+    println(fmt!("%d", some_value));
 }
 ~~~~
 
-In Rust, there is nothing special about creating tasks - the language
-itself doesn't know what a 'task' is. Instead, Rust provides in the
-type system all the tools necessary to implement safe concurrency,
-_owned types_ in particular, and leaves the dirty work up to the
-core library.
-
-The `spawn` function has a very simple type signature: `fn spawn(f:
-~fn())`. Because it accepts only owned closures, and owned closures
-contained only owned data, `spawn` can safely move the entire closure
-and all its associated state into an entirely different task for
-execution. Like any closure, the function passed to spawn may capture
-an environment that it carries across tasks.
-
-~~~
-# use io::println;
-# use task::spawn;
-# fn generate_task_number() -> int { 0 }
-// 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));
-}
-~~~
-
-By default tasks will be multiplexed across the available cores, running
-in parallel, thus on a multicore machine, running the following code
-should interleave the output in vaguely random order.
+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.
 
-~~~
-# use io::print;
-# use task::spawn;
+# Communication
 
-for int::range(0, 20) |child_task_number| {
-    do spawn {
-       print(fmt!("I am child number %d\n", child_task_number));
-    }
-}
-~~~
-
-## 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*.
-
-Pipes are simply a pair of endpoints, with one for sending messages
-and another for receiving messages. Pipes are low-level communication
-building-blocks and so come in a variety of forms, appropriate for
-different use cases, but there are just a few varieties that are most
-commonly used, which we will cover presently.
-
-The simplest way to create a pipe is to use the `pipes::stream`
-function to create a `(Chan, Port)` pair. In Rust parlance a 'channel'
-is a sending endpoint of a pipe, and a 'port' is the recieving
-endpoint. Consider the following example of performing two calculations
-concurrently.
+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): (Chan<int>, Port<int>) = stream();
+let (chan, port) = stream();
 
 do spawn {
     let result = some_expensive_computation();
@@ -173,19 +116,17 @@ let result = port.recv();
 # fn some_other_expensive_computation() {}
 ~~~~
 
-Let's examine this example in detail. The `let` statement first creates a
-stream for sending and receiving integers (recall that `let` can be
-used for destructuring patterns, in this case separating a tuple into
-its component parts).
+Let's walk through this code line-by-line.  The first line creates a
+stream for sending and receiving integers:
 
-~~~~
-# use pipes::{stream, Chan, Port};
-let (chan, port): (Chan<int>, Port<int>) = stream();
+~~~~ {.ignore}
+# use pipes::stream;
+let (chan, port) = stream();
 ~~~~
 
-The channel will be used by the child task to send data to the parent task,
-which will wait to recieve the data on the port. The next statement
-spawns the child task.
+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};
@@ -199,15 +140,14 @@ do spawn {
 }
 ~~~~
 
-Notice that `chan` was transferred to the child task implicitly by
-capturing it in the task closure. Both `Chan` and `Port` are sendable
-types and may be captured into tasks or otherwise transferred between
-them. In the example, the child task performs an expensive computation
-then sends the result over the captured channel.
+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:
+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};
@@ -218,73 +158,7 @@ some_other_expensive_computation();
 let result = port.recv();
 ~~~~
 
-The `Port` and `Chan` pair created by `stream` enable efficient
-communication between a single sender and a single receiver, but
-multiple senders cannot use a single `Chan`, nor can multiple
-receivers use a single `Port`. What if our example needed to
-perform multiple computations across a number of tasks? In that
-case we might use a `SharedChan`, a type that allows a single
-`Chan` to be used by multiple senders.
-
-~~~
-# use task::spawn;
-use pipes::{stream, SharedChan};
-
-let (chan, port) = 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 {
-        child_chan.send(some_expensive_computation(init_val));
-    }
-}
-
-let result = port.recv() + port.recv() + port.recv();
-# fn some_expensive_computation(_i: uint) -> int { 42 }
-~~~
-
-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
-`Chan` though, `SharedChan` may be duplicated 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.
-
-~~~
-# use task::spawn;
-# use pipes::{stream, Port, Chan};
-
-let ports = do vec::from_fn(3) |init_val| {
-    let (chan, port) = stream();
-
-    do spawn {
-        chan.send(some_expensive_computation(init_val));
-    }
-
-    port
-};
-
-// Wait on each port, accumulating the results
-let result = ports.foldl(0, |accum, port| *accum + port.recv() );
-# fn some_expensive_computation(_i: uint) -> int { 42 }
-~~~
-
-# Unfinished notes
-
-## Actor patterns
-
-## Linearity, option dancing, owned closures
-
-## Creating a task with a bi-directional communication path
+# 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
@@ -353,4 +227,3 @@ 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.
-

branches/snap-stage3/src/libcore/core.rc

@@ -185,6 +185,7 @@ mod cmp;
 mod num;
 mod hash;
 mod either;
+#[legacy_exports]
 mod iter;
 mod logging;
 mod option;
@@ -193,6 +194,7 @@ mod option_iter {
     #[path = "option.rs"]
     mod inst;
 }
+#[legacy_exports]
 mod result;
 mod to_str;
 mod to_bytes;
@@ -201,16 +203,22 @@ mod util;
 
 // Data structure modules
 
+#[legacy_exports]
 mod dvec;
 #[path="iter-trait"]
 mod dvec_iter {
+    #[legacy_exports];
     #[path = "dvec.rs"]
+    #[legacy_exports]
     mod inst;
 }
+#[legacy_exports]
 mod dlist;
 #[path="iter-trait"]
 mod dlist_iter {
+    #[legacy_exports];
     #[path ="dlist.rs"]
+    #[legacy_exports]
     mod inst;
 }
 mod send_map;

branches/snap-stage3/src/libcore/iter-trait/dlist.rs

@@ -1,5 +1,5 @@
 #[allow(non_camel_case_types)]
-pub type IMPL_T<A> = dlist::DList<A>;
+type IMPL_T<A> = dlist::DList<A>;
 
 /**
  * Iterates through the current contents.
@@ -8,7 +8,7 @@ pub type IMPL_T<A> = dlist::DList<A>;
  * e.g. breadth-first search with in-place enqueues), but removing the current
  * node is forbidden.
  */
-pub pure fn EACH<A>(self: &IMPL_T<A>, f: fn(v: &A) -> bool) {
+pure fn EACH<A>(self: &IMPL_T<A>, f: fn(v: &A) -> bool) {
     let mut link = self.peek_n();
     while option::is_some(&link) {
         let nobe = option::get(&link);
@@ -29,6 +29,6 @@ pub pure fn EACH<A>(self: &IMPL_T<A>, f: fn(v: &A) -> bool) {
     }
 }
 
-pub pure fn SIZE_HINT<A>(self: &IMPL_T<A>) -> Option<uint> {
+pure fn SIZE_HINT<A>(self: &IMPL_T<A>) -> Option<uint> {
     Some(self.len())
 }

branches/snap-stage3/src/libcore/iter-trait/dvec.rs

@@ -1,12 +1,12 @@
 #[allow(non_camel_case_types)]
-pub type IMPL_T<A> = dvec::DVec<A>;
+type IMPL_T<A> = dvec::DVec<A>;
 
 /**
  * Iterates through the current contents.
  *
  * Attempts to access this dvec during iteration will fail.
  */
-pub pure fn EACH<A>(self: &IMPL_T<A>, f: fn(v: &A) -> bool) {
+pure fn EACH<A>(self: &IMPL_T<A>, f: fn(v: &A) -> bool) {
     unsafe {
         do self.swap |v| {
             v.each(f);
@@ -15,6 +15,6 @@ pub pure fn EACH<A>(self: &IMPL_T<A>, f: fn(v: &A) -> bool) {
     }
 }
 
-pub pure fn SIZE_HINT<A>(self: &IMPL_T<A>) -> Option<uint> {
+pure fn SIZE_HINT<A>(self: &IMPL_T<A>) -> Option<uint> {
     Some(self.len())
 }