---

yaml
---
r: 146815
b: refs/heads/try2
c: 6acf227
h: refs/heads/master
i:
  146813: e491930
  146811: c41c48d
  146807: d03ffb6
  146799: 87d8465
  146783: f15cb6a
  146751: 0e67e03
  146687: 06c094d
v: v3

Author: alexcrichton

[refs]

@@ -5,7 +5,7 @@ refs/heads/snap-stage3: 78a7676898d9f80ab540c6df5d4c9ce35bb50463
 refs/heads/try: 519addf6277dbafccbb4159db4b710c37eaa2ec5
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
-refs/heads/try2: 1746c0269d356a93aaef367541872d363651cb23
+refs/heads/try2: 6acf227cc8db09ca25d274918f860849c41df19a
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try2/doc/rust.md

@@ -2349,9 +2349,9 @@ Indices are zero-based, and may be of any integral type. Vector access
 is bounds-checked at run-time. When the check fails, it will put the
 task in a _failing state_.
 
-~~~~ {.xfail-test}
+~~~~
 # use std::task;
-# do task::spawn {
+# do task::spawn_unlinked {
 
 ([1, 2, 3, 4])[0];
 (["a", "b"])[10]; // fails

branches/try2/doc/tutorial-tasks.md

@@ -402,6 +402,22 @@ freeing memory along the way---and then exits. Unlike exceptions in C++,
 exceptions in Rust are unrecoverable within a single task: once a task fails,
 there is no way to "catch" the exception.
 
+All tasks are, by default, _linked_ to each other. That means that the fates
+of all tasks are intertwined: if one fails, so do all the others.
+
+~~~{.xfail-test .linked-failure}
+# use std::task::spawn;
+# use std::task;
+# fn do_some_work() { loop { task::yield() } }
+# do task::try {
+// Create a child task that fails
+do spawn { fail!() }
+
+// This will also fail because the task we spawned failed
+do_some_work();
+# };
+~~~
+
 While it isn't possible for a task to recover from failure, tasks may notify
 each other of failure. The simplest way of handling task failure is with the
 `try` function, which is similar to `spawn`, but immediately blocks waiting
@@ -448,7 +464,101 @@ it trips, indicates an unrecoverable logic error); in other cases you
 might want to contain the failure at a certain boundary (perhaps a
 small piece of input from the outside world, which you happen to be
 processing in parallel, is malformed and its processing task can't
-proceed).
+proceed). Hence, you will need different _linked failure modes_.
+
+## Failure modes
+
+By default, task failure is _bidirectionally linked_, which means that if
+either task fails, it kills the other one.
+
+~~~{.xfail-test .linked-failure}
+# use std::task;
+# use std::comm::oneshot;
+# fn sleep_forever() { loop { let (p, c) = oneshot::<()>(); p.recv(); } }
+# do task::try {
+do spawn {
+    do spawn {
+        fail!();  // All three tasks will fail.
+    }
+    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 fail automatically if one of its child task fails, 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:
+
+~~~{.xfail-test .linked-failure}
+# use std::comm::{stream, Chan, Port};
+# use std::comm::oneshot;
+# use std::task::{spawn, try};
+# use std::task;
+# fn sleep_forever() { loop { let (p, c) = oneshot::<()>(); p.recv(); } }
+# do task::try {
+let (receiver, sender): (Port<int>, Chan<int>) = stream();
+do spawn {  // 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 {  // 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:
+
+~~~{.xfail-test .linked-failure}
+# use std::task;
+# use std::comm::oneshot;
+# fn sleep_forever() { loop { let (p, c) = oneshot::<()>(); p.recv(); } }
+# fn wait_for_a_while() { for _ in range(0, 1000u) { task::yield() } }
+# do task::try::<int> {
+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_.
+
+~~~{.xfail-test .linked-failure}
+# use std::task;
+# fn random() -> uint { 100 }
+# fn sleep_for(i: uint) { for _ in range(0, i) { task::yield() } }
+# do task::try::<()> {
+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.
+# };
+~~~
 
 ## Creating a task with a bi-directional communication path
 

branches/try2/mk/docs.mk

@@ -215,12 +215,10 @@ RUSTDOC = $(HBIN2_H_$(CFG_BUILD))/rustdoc$(X_$(CFG_BUILD))
 # $(1) - The crate name (std/extra)
 # $(2) - The crate file
 # $(3) - The relevant host build triple (to depend on libstd)
-#
-# Passes --cfg stage2 to rustdoc because it uses the stage2 librustc.
 define libdoc
 doc/$(1)/index.html: $$(RUSTDOC) $$(TLIB2_T_$(3)_H_$(3))/$(CFG_STDLIB_$(3))
 	@$$(call E, rustdoc: $$@)
-	$(Q)$(RUSTDOC) --cfg stage2 $(2)
+	$(Q)$(RUSTDOC) $(2)
 
 DOCS += doc/$(1)/index.html
 endef

branches/try2/src/libextra/arc.rs

@@ -655,7 +655,7 @@ mod tests {
         let arc2 = ~arc.clone();
         let (p, c) = comm::stream();
 
-        do spawn {
+        do task::spawn_unlinked || {
             let _ = p.recv();
             do arc2.access_cond |one, cond| {
                 cond.signal();

branches/try2/src/libextra/comm.rs

@@ -137,6 +137,7 @@ pub fn rendezvous<T: Send>() -> (SyncPort<T>, SyncChan<T>) {
 mod test {
     use comm::{DuplexStream, rendezvous};
     use std::rt::test::run_in_uv_task;
+    use std::task::spawn_unlinked;
 
 
     #[test]
@@ -176,7 +177,7 @@ mod test {
     #[test]
     fn send_and_fail_and_try_recv() {
         let (port, chan) = rendezvous();
-        do spawn {
+        do spawn_unlinked {
             chan.duplex_stream.send(()); // Can't access this field outside this module
             fail!()
         }
@@ -186,7 +187,7 @@ mod test {
     #[test]
     fn try_send_and_recv_then_fail_before_ack() {
         let (port, chan) = rendezvous();
-        do spawn {
+        do spawn_unlinked {
             port.duplex_stream.recv();
             fail!()
         }
@@ -197,7 +198,7 @@ mod test {
     #[should_fail]
     fn send_and_recv_then_fail_before_ack() {
         let (port, chan) = rendezvous();
-        do spawn {
+        do spawn_unlinked {
             port.duplex_stream.recv();
             fail!()
         }

branches/try2/src/libextra/future.rs

@@ -27,6 +27,7 @@
 
 use std::cell::Cell;
 use std::comm::{PortOne, oneshot};
+use std::task;
 use std::util::replace;
 
 /// A type encapsulating the result of a computation which may not be complete
@@ -129,12 +130,29 @@ impl<A:Send> Future<A> {
 
         let (port, chan) = oneshot();
 
-        do spawn {
+        do task::spawn_with(chan) |chan| {
             chan.send(blk());
         }
 
         Future::from_port(port)
     }
+
+    pub fn spawn_with<B: Send>(v: B, blk: proc(B) -> A) -> Future<A> {
+        /*!
+         * Create a future from a unique closure taking one argument.
+         *
+         * The closure and its argument will be moved into a new task. The
+         * closure will be run and its result used as the value of the future.
+         */
+
+         let (port, chan) = oneshot();
+
+         do task::spawn_with((v, chan)) |(v, chan)| {
+            chan.send(blk(v));
+         }
+
+         Future::from_port(port)
+    }
 }
 
 #[cfg(test)]
@@ -189,6 +207,12 @@ mod test {
         assert_eq!(f.get(), ~"bale");
     }
 
+    #[test]
+    fn test_spawn_with() {
+        let mut f = Future::spawn_with(~"gale", |s| { s });
+        assert_eq!(f.get(), ~"gale");
+    }
+
     #[test]
     #[should_fail]
     fn test_futurefail() {