---

yaml
---
r: 81304
b: refs/heads/snap-stage3
c: d6c3b67
h: refs/heads/master
v: v3

Author: bors

[refs]

@@ -1,7 +1,7 @@
 ---
 refs/heads/master: 4c6bf4872012c010f84dc7fa2cdfe87522533f89
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
-refs/heads/snap-stage3: 8bb48cc1e607a7189c80c1d0f3f5567312bf1a99
+refs/heads/snap-stage3: d6c3b67348d9d6860051a04ee24e284414fa49a6
 refs/heads/try: 70152ff55722878cde684ee6462c14c65f2c4729
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b

branches/snap-stage3/src/libstd/task/mod.rs

@@ -13,16 +13,34 @@
  *
  * An executing Rust program consists of a tree of tasks, each with their own
  * stack, and sole ownership of their allocated heap data. Tasks communicate
- * with each other using ports and channels.
+ * with each other using ports and channels (see std::rt::comm for more info
+ * about how communication works).
  *
- * When a task fails, that failure will propagate to its parent (the task
- * that spawned it) and the parent will fail as well. The reverse is not
- * true: when a parent task fails its children will continue executing. When
- * the root (main) task fails, all tasks fail, and then so does the entire
- * process.
+ * Tasks can be spawned in 3 different modes.
  *
- * Tasks may execute in parallel and are scheduled automatically by the
- * runtime.
+ *  * Bidirectionally linked: This is the default mode and it's what ```spawn``` does.
+ *  Failures will be propagated from parent to child and vice versa.
+ *
+ *  * Unidirectionally linked (parent->child): This type of task can be created with
+ *  ```spawn_supervised```. In this case, failures are propagated from parent to child
+ *  but not the other way around.
+ *
+ *  * Unlinked: Tasks can be completely unlinked. These tasks can be created by using
+ *  ```spawn_unlinked```. In this case failures are not propagated at all.
+ *
+ * Tasks' failure modes can be further configured. For instance, parent tasks can (un)watch
+ * children failures. Please, refer to TaskBuilder's documentation bellow for more information.
+ *
+ * When a (bi|uni)directionally linked task fails, its failure will be propagated to all tasks
+ * linked to it, this will cause such tasks to fail by a `linked failure`.
+ *
+ * Task Scheduling:
+ *
+ * By default, every task is created in the same scheduler as its parent, where it
+ * is scheduled cooperatively with all other tasks in that scheduler. Some specialized
+ * applications may want more control over their scheduling, in which case they can be
+ * spawned into a new scheduler with the specific properties required. See TaskBuilder's
+ * documentation bellow for more information.
  *
  * # Example
  *
@@ -120,17 +138,9 @@ pub struct SchedOpts {
  * * name - A name for the task-to-be, for identification in failure messages.
  *
  * * sched - Specify the configuration of a new scheduler to create the task
- *           in
- *
- *     By default, every task is created in the same scheduler as its
- *     parent, where it is scheduled cooperatively with all other tasks
- *     in that scheduler. Some specialized applications may want more
- *     control over their scheduling, in which case they can be spawned
- *     into a new scheduler with the specific properties required.
- *
- *     This is of particular importance for libraries which want to call
- *     into foreign code that blocks. Without doing so in a different
- *     scheduler other tasks will be impeded or even blocked indefinitely.
+ *           in. This is of particular importance for libraries which want to call
+ *           into foreign code that blocks. Without doing so in a different
+ *           scheduler other tasks will be impeded or even blocked indefinitely.
  */
 pub struct TaskOpts {
     linked: bool,