---

yaml
---
r: 29945
b: refs/heads/incoming
c: 3b09c3d
h: refs/heads/master
i:
  29943: f44bbe8
v: v3

Author: bblum

[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: 71ec545614e72b815a3685bb461c7853368b92b0
+refs/heads/incoming: 3b09c3deaa9a376d0ae40a783713ece3720ca08f
 refs/heads/dist-snap: 2f32a1581f522e524009138b33b1c7049ced668d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/incoming/src/libstd/arc.rs

@@ -93,6 +93,15 @@ fn clone<T: const send>(rc: &arc<T>) -> arc<T> {
     arc { x: unsafe { clone_shared_mutable_state(&rc.x) } }
 }
 
+/**
+ * Retrieve the data back out of the ARC. This function blocks until the
+ * reference given to it is the last existing one, and then unwrap the data
+ * instead of destroying it.
+ *
+ * If multiple tasks call unwrap, all but the first will fail. Do not call
+ * unwrap from a task that holds another reference to the same ARC; it is
+ * guaranteed to deadlock.
+ */
 fn unwrap<T: const send>(+rc: arc<T>) -> T {
     let arc { x: x } = rc;
     unsafe { unwrap_shared_mutable_state(x) }
@@ -186,6 +195,12 @@ impl<T: send> &mutex_arc<T> {
     }
 }
 
+/**
+ * Retrieves the data, blocking until all other references are dropped,
+ * exactly as arc::unwrap.
+ *
+ * Will additionally fail if another task has failed while accessing the arc.
+ */
 // FIXME(#2585) make this a by-move method on the arc
 fn unwrap_mutex_arc<T: send>(+arc: mutex_arc<T>) -> T {
     let mutex_arc { x: x } = arc;
@@ -363,6 +378,13 @@ impl<T: const send> &rw_arc<T> {
     }
 }
 
+/**
+ * Retrieves the data, blocking until all other references are dropped,
+ * exactly as arc::unwrap.
+ *
+ * Will additionally fail if another task has failed while accessing the arc
+ * in write mode.
+ */
 // FIXME(#2585) make this a by-move method on the arc
 fn unwrap_rw_arc<T: const send>(+arc: rw_arc<T>) -> T {
     let rw_arc { x: x, _ } = arc;