---

yaml
---
r: 108342
b: refs/heads/dist-snap
c: 5d86e24
h: refs/heads/master
v: v3

Author: huonw

[refs]

@@ -6,7 +6,7 @@ refs/heads/try: f64fdf524a434f0e5cd0bc91d09c144723f3c90d
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: 147ecfdd8221e4a4d4e090486829a06da1e0ca3c
-refs/heads/dist-snap: 0f4294b4e2887ffe9d0532564521c456bb89a780
+refs/heads/dist-snap: 5d86e24ab27dba0a773bd00a98e3845ece0ebf16
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503
 refs/heads/try3: 9387340aab40a73e8424c48fd42f0c521a4875c0

branches/dist-snap/src/libstd/unstable/mutex.rs

@@ -27,31 +27,34 @@
 //!
 //! It is not recommended to use this type for idiomatic rust use. These types
 //! are appropriate where no other options are available, but other rust
-//! concurrency primitives should be used before them.
+//! concurrency primitives should be used before them: the `sync` crate defines
+//! `StaticMutex` and `Mutex` types.
 //!
 //! # Example
 //!
-//!     use std::unstable::mutex::{StaticNativeMutex, NATIVE_MUTEX_INIT};
+//! ```rust
+//! use std::unstable::mutex::{NativeMutex, StaticNativeMutex, NATIVE_MUTEX_INIT};
 //!
-//!     // Use a statically initialized mutex
-//!     static mut LOCK: StaticNativeMutex = NATIVE_MUTEX_INIT;
+//! // Use a statically initialized mutex
+//! static mut LOCK: StaticNativeMutex = NATIVE_MUTEX_INIT;
 //!
-//!     unsafe {
-//!         let _guard = LOCK.lock();
-//!     } // automatically unlocked here
+//! unsafe {
+//!     let _guard = LOCK.lock();
+//! } // automatically unlocked here
 //!
-//!     // Use a normally initialized mutex
-//!     unsafe {
-//!         let mut lock = NativeMutex::new();
+//! // Use a normally initialized mutex
+//! unsafe {
+//!     let mut lock = NativeMutex::new();
 //!
-//!         {
-//!             let _guard = lock.lock();
-//!         } // unlocked here
+//!     {
+//!         let _guard = lock.lock();
+//!     } // unlocked here
 //!
-//!         // sometimes the RAII guard isn't appropriate
-//!         lock.lock_noguard();
-//!         lock.unlock_noguard();
-//!     } // `lock` is deallocated here
+//!     // sometimes the RAII guard isn't appropriate
+//!     lock.lock_noguard();
+//!     lock.unlock_noguard();
+//! } // `lock` is deallocated here
+//! ```
 
 #[allow(non_camel_case_types)];
 
@@ -61,7 +64,8 @@ use ops::Drop;
 /// A native mutex suitable for storing in statics (that is, it has
 /// the `destroy` method rather than a destructor).
 ///
-/// Prefer the `NativeMutex` type where possible.
+/// Prefer the `NativeMutex` type where possible, since that does not
+/// require manual deallocation.
 pub struct StaticNativeMutex {
     priv inner: imp::Mutex,
 }
@@ -128,14 +132,16 @@ impl StaticNativeMutex {
 
     /// Acquire the lock without creating a `LockGuard`.
     ///
-    /// Prefer using `.lock`.
+    /// These needs to be paired with a call to `.unlock_noguard`. Prefer using
+    /// `.lock`.
     pub unsafe fn lock_noguard(&mut self) { self.inner.lock() }
 
     /// Attempts to acquire the lock without creating a
     /// `LockGuard`. The value returned is whether the lock was
     /// acquired or not.
     ///
-    /// Prefer using `.trylock`.
+    /// If `true` is returned, this needs to be paired with a call to
+    /// `.unlock_noguard`. Prefer using `.trylock`.
     pub unsafe fn trylock_noguard(&mut self) -> bool {
         self.inner.trylock()
     }
@@ -175,11 +181,14 @@ impl NativeMutex {
     /// # Example
     /// ```rust
     /// use std::unstable::mutex::NativeMutex;
-    /// let mut lock = NativeMutex::new();
     /// unsafe {
-    ///     let _guard = lock.lock();
-    ///     // critical section...
-    /// } // automatically unlocked in `_guard`'s destructor
+    ///     let mut lock = NativeMutex::new();
+    ///
+    ///     {
+    ///         let _guard = lock.lock();
+    ///         // critical section...
+    ///     } // automatically unlocked in `_guard`'s destructor
+    /// }
     /// ```
     pub unsafe fn lock<'a>(&'a mut self) -> LockGuard<'a> {
         self.inner.lock()
@@ -193,14 +202,16 @@ impl NativeMutex {
 
     /// Acquire the lock without creating a `LockGuard`.
     ///
-    /// Prefer using `.lock`.
+    /// These needs to be paired with a call to `.unlock_noguard`. Prefer using
+    /// `.lock`.
     pub unsafe fn lock_noguard(&mut self) { self.inner.lock_noguard() }
 
     /// Attempts to acquire the lock without creating a
     /// `LockGuard`. The value returned is whether the lock was
     /// acquired or not.
     ///
-    /// Prefer using `.trylock`.
+    /// If `true` is returned, this needs to be paired with a call to
+    /// `.unlock_noguard`. Prefer using `.trylock`.
     pub unsafe fn trylock_noguard(&mut self) -> bool {
         self.inner.trylock_noguard()
     }