std: add comment explaining lock result check

Author: joboet

library/std/src/sys/pal/unix/locks/pthread_mutex.rs

@@ -112,6 +112,13 @@ impl Mutex {
         }
 
         let r = libc::pthread_mutex_lock(raw(self));
+        // As we set the mutex type to `PTHREAD_MUTEX_NORMAL` above, we expect
+        // the lock call to never fail. Unfortunately however, some platforms
+        // (Solaris) do not conform to the standard, and instead always provide
+        // deadlock detection. How kind of them! Unfortunately that means that
+        // we need to check the error code here. To save use from UB on other
+        // less well-behaved platforms in the future, we do it even on "good"
+        // platforms like macOS. See #120147 for more context.
         if r != 0 {
             fail()
         }