std: clarify comments about initialization

Author: joboet

std/src/sys/pal/unix/sync/condvar.rs

@@ -23,23 +23,23 @@ impl Condvar {
     }
 
     /// # Safety
-    /// `init` must have been called.
+    /// `init` must have been called on this instance.
     #[inline]
     pub unsafe fn notify_one(self: Pin<&Self>) {
         let r = unsafe { libc::pthread_cond_signal(self.raw()) };
         debug_assert_eq!(r, 0);
     }
 
     /// # Safety
-    /// `init` must have been called.
+    /// `init` must have been called on this instance.
     #[inline]
     pub unsafe fn notify_all(self: Pin<&Self>) {
         let r = unsafe { libc::pthread_cond_broadcast(self.raw()) };
         debug_assert_eq!(r, 0);
     }
 
     /// # Safety
-    /// * `init` must have been called.
+    /// * `init` must have been called on this instance.
     /// * `mutex` must be locked by the current thread.
     /// * This condition variable may only be used with the same mutex.
     #[inline]
@@ -49,7 +49,7 @@ impl Condvar {
     }
 
     /// # Safety
-    /// * `init` must have been called.
+    /// * `init` must have been called on this instance.
     /// * `mutex` must be locked by the current thread.
     /// * This condition variable may only be used with the same mutex.
     pub unsafe fn wait_timeout(&self, mutex: Pin<&Mutex>, dur: Duration) -> bool {
@@ -95,7 +95,7 @@ impl Condvar {
     const CLOCK: libc::clockid_t = libc::CLOCK_MONOTONIC;
 
     /// # Safety
-    /// May only be called once.
+    /// May only be called once per instance of `Self`.
     pub unsafe fn init(self: Pin<&mut Self>) {
         use crate::mem::MaybeUninit;
 
@@ -137,7 +137,7 @@ impl Condvar {
     const CLOCK: libc::clockid_t = libc::CLOCK_REALTIME;
 
     /// # Safety
-    /// May only be called once.
+    /// May only be called once per instance of `Self`.
     pub unsafe fn init(self: Pin<&mut Self>) {
         if cfg!(any(target_os = "espidf", target_os = "horizon", target_os = "teeos")) {
             // NOTE: ESP-IDF's PTHREAD_COND_INITIALIZER support is not released yet

std/src/sys/pal/unix/sync/mutex.rs

@@ -18,7 +18,7 @@ impl Mutex {
     }
 
     /// # Safety
-    /// Must only be called once.
+    /// May only be called once per instance of `Self`.
     pub unsafe fn init(self: Pin<&mut Self>) {
         // Issue #33770
         //
@@ -58,7 +58,8 @@ impl Mutex {
     }
 
     /// # Safety
-    /// * If `init` was not called, reentrant locking causes undefined behaviour.
+    /// * If `init` was not called on this instance, reentrant locking causes
+    ///   undefined behaviour.
     /// * Destroying a locked mutex causes undefined behaviour.
     pub unsafe fn lock(self: Pin<&Self>) {
         #[cold]
@@ -82,7 +83,8 @@ impl Mutex {
     }
 
     /// # Safety
-    /// * If `init` was not called, reentrant locking causes undefined behaviour.
+    /// * If `init` was not called on this instance, reentrant locking causes
+    ///   undefined behaviour.
     /// * Destroying a locked mutex causes undefined behaviour.
     pub unsafe fn try_lock(self: Pin<&Self>) -> bool {
         unsafe { libc::pthread_mutex_trylock(self.raw()) == 0 }

std/src/sys/sync/condvar/pthread.rs

@@ -22,7 +22,7 @@ impl Condvar {
     fn get(&self) -> Pin<&pal::Condvar> {
         self.cvar.get_or_init(|| {
             let mut cvar = Box::pin(pal::Condvar::new());
-            // SAFETY: we only call `init` once, namely here.
+            // SAFETY: we only call `init` once per `pal::Condvar`, namely here.
             unsafe { cvar.as_mut().init() };
             cvar
         })

std/src/sys/sync/mutex/pthread.rs

@@ -21,7 +21,7 @@ impl Mutex {
         // This is sound however, as it cannot have been locked.
         self.pal.get_or_init(|| {
             let mut pal = Box::pin(pal::Mutex::new());
-            // SAFETY: we only call `init` once, namely here.
+            // SAFETY: we only call `init` once per `pal::Mutex`, namely here.
             unsafe { pal.as_mut().init() };
             pal
         })