---

yaml
---
r: 31635
b: refs/heads/dist-snap
c: 0c623c4
h: refs/heads/master
i:
  31633: cc0f7ba
  31631: 1f425c1
v: v3

Author: bblum

[refs]

@@ -7,6 +7,6 @@ refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: d0c6ce338884ee21843f4b40bf6bf18d222ce5df
 refs/heads/incoming: d9317a174e434d4c99fc1a37fd7dc0d2f5328d37
-refs/heads/dist-snap: 241085a073805447c0ad1b55525faaddcd00bedc
+refs/heads/dist-snap: 0c623c4474f439c0bb85b7f91ae663d9584e7973
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/dist-snap/src/libcore/arc.rs

@@ -97,6 +97,7 @@ fn exclusive<T:send >(-data: T) -> exclusive<T> {
 }
 
 impl methods<T: send> for exclusive<T> {
+    /// Duplicate an exclusive ARC. See arc::clone.
     fn clone() -> exclusive<T> {
         unsafe {
             // this makes me nervous...
@@ -109,6 +110,22 @@ impl methods<T: send> for exclusive<T> {
         arc_destruct(self.data)
     }
 
+    /**
+     * Access the underlying mutable data with mutual exclusion from other
+     * tasks. The argument closure will be run with the mutex locked; all
+     * other tasks wishing to access the data will block until the closure
+     * finishes running.
+     *
+     * Currently, scheduling operations (i.e., yielding, receiving on a pipe,
+     * accessing the provided condition variable) are prohibited while inside
+     * the exclusive. Supporting that is a work in progress.
+     *
+     * The reason this function is 'unsafe' is because it is possible to
+     * construct a circular reference among multiple ARCs by mutating the
+     * underlying data. This creates potential for deadlock, but worse, this
+     * will guarantee a memory leak of all involved ARCs. Using exclusive
+     * ARCs inside of other ARCs is safe in absence of circular references.
+     */
     unsafe fn with<U>(f: fn(sys::condition, x: &mut T) -> U) -> U {
         let ptr: ~arc_data<ex_data<T>> =
             unsafe::reinterpret_cast(self.data);