From 2ef8774ac5b56ae264224d46ffa0078f5d39ce6c Mon Sep 17 00:00:00 2001
From: Ben Blum <bblum@andrew.cmu.edu>
Date: Thu, 13 Jun 2013 15:20:38 -0400
Subject: [PATCH] Improve comments in sync and arc a bit more.

---
 src/libextra/arc.rs  | 8 ++++----
 src/libextra/sync.rs | 8 +++++---
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/src/libextra/arc.rs b/src/libextra/arc.rs
index 197e3e44105..b1bec1f95db 100644
--- a/src/libextra/arc.rs
+++ b/src/libextra/arc.rs
@@ -380,12 +380,12 @@ impl<T:Const + Owned> RWARC<T> {
      * # Example
      *
      * ~~~ {.rust}
-     * do arc.write_downgrade |write_mode| {
-     *     do (&write_mode).write_cond |state, condvar| {
+     * do arc.write_downgrade |mut write_token| {
+     *     do write_token.write_cond |state, condvar| {
      *         ... exclusive access with mutable state ...
      *     }
-     *     let read_mode = arc.downgrade(write_mode);
-     *     do (&read_mode).read |state| {
+     *     let read_token = arc.downgrade(write_token);
+     *     do read_token.read |state| {
      *         ... shared access with immutable state ...
      *     }
      * }
diff --git a/src/libextra/sync.rs b/src/libextra/sync.rs
index 86cc014f714..5930bf50ff7 100644
--- a/src/libextra/sync.rs
+++ b/src/libextra/sync.rs
@@ -598,6 +598,8 @@ impl RWlock {
         // solves this because T1 will hold order_lock while waiting on access,
         // which will cause T3 to have to wait until T1 finishes its write,
         // which can't happen until T2 finishes the downgrade-read entirely.
+        // The astute reader will also note that making waking writers use the
+        // order_lock is better for not starving readers.
         unsafe {
             do task::unkillable {
                 (&self.order_lock).acquire();
@@ -622,12 +624,12 @@ impl RWlock {
      * # Example
      *
      * ~~~ {.rust}
-     * do lock.write_downgrade |write_token| {
-     *     do (&write_token).write_cond |condvar| {
+     * do lock.write_downgrade |mut write_token| {
+     *     do write_token.write_cond |condvar| {
      *         ... exclusive access ...
      *     }
      *     let read_token = lock.downgrade(write_token);
-     *     do (&read_token).read {
+     *     do read_token.read {
      *         ... shared access ...
      *     }
      * }