---

yaml
---
r: 22973
b: refs/heads/master
c: 0c623c4
h: refs/heads/master
i:
  22971: 388fbc8
v: v3

Author: bblum

[refs]

@@ -1,5 +1,5 @@
 ---
-refs/heads/master: 241085a073805447c0ad1b55525faaddcd00bedc
+refs/heads/master: 0c623c4474f439c0bb85b7f91ae663d9584e7973
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: cd6f24f9d14ac90d167386a56e7a6ac1f0318195
 refs/heads/try: ffbe0e0e00374358b789b0037bcb3a577cd218be

trunk/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);