clarify partially initialized Mutex issues

3 files changed, 10 insertions, 2 deletions

diff --git a/src/libstd/sys/unix/args.rs b/src/libstd/sys/unix/args.rs
index 7e32ec1347e..c91bd5b22af 100644
--- a/src/libstd/sys/unix/args.rs
+++ b/src/libstd/sys/unix/args.rs
@@ -80,6 +80,9 @@ mod imp {
 
     static mut ARGC: isize = 0;
     static mut ARGV: *const *const u8 = ptr::null();
+    // `ENV_LOCK` is never initialized fully, so this mutex is reentrant!
+    // Do not use it in a way that might be reentrant, that could lead to
+    // aliasing `&mut`.
     static LOCK: Mutex = Mutex::new();
 
     pub unsafe fn init(argc: isize, argv: *const *const u8) {
diff --git a/src/libstd/sys/unix/mutex.rs b/src/libstd/sys/unix/mutex.rs
index 52cf3f97c5c..f0711b60320 100644
--- a/src/libstd/sys/unix/mutex.rs
+++ b/src/libstd/sys/unix/mutex.rs
@@ -25,8 +25,10 @@ unsafe impl Sync for Mutex {}
 #[allow(dead_code)] // sys isn't exported yet
 impl Mutex {
     pub const fn new() -> Mutex {
-        // Might be moved and address is changing it is better to avoid
-        // initialization of potentially opaque OS data before it landed
+        // Might be moved to a different address, so it is better to avoid
+        // initialization of potentially opaque OS data before it landed.
+        // Be very careful using this newly constructed `Mutex`, it should
+        // be initialized by calling `init()` first!
         Mutex { inner: UnsafeCell::new(libc::PTHREAD_MUTEX_INITIALIZER) }
     }
     #[inline]
diff --git a/src/libstd/sys/unix/os.rs b/src/libstd/sys/unix/os.rs
index 1d92e8fc97c..6ef9502ba62 100644
--- a/src/libstd/sys/unix/os.rs
+++ b/src/libstd/sys/unix/os.rs
@@ -33,6 +33,9 @@ use sys::fd;
 use vec;
 
 const TMPBUF_SZ: usize = 128;
+// `ENV_LOCK` is never initialized fully, so this mutex is reentrant!
+// Do not use it in a way that might be reentrant, that could lead to
+// aliasing `&mut`.
 static ENV_LOCK: Mutex = Mutex::new();