std: Handle OS errors when joining threads

Also add to the documentation that the `join` method can panic.

cc #34971
cc #43539

src/libstd/sys/unix/thread.rs

@@ -168,7 +168,8 @@ impl Thread {
         unsafe {
             let ret = libc::pthread_join(self.id, ptr::null_mut());
             mem::forget(self);
-            debug_assert_eq!(ret, 0);
+            assert!(ret == 0,
+                    "failed to join thread: {}", io::Error::from_raw_os_error(ret));
         }
     }
 

src/libstd/sys/windows/c.rs

@@ -273,6 +273,7 @@ pub const FILE_END: DWORD = 2;
 
 pub const WAIT_OBJECT_0: DWORD = 0x00000000;
 pub const WAIT_TIMEOUT: DWORD = 258;
+pub const WAIT_FAILED: DWORD = 0xFFFFFFFF;
 
 #[cfg(target_env = "msvc")]
 pub const MAX_SYM_NAME: usize = 2000;

src/libstd/sys/windows/thread.rs

@@ -61,7 +61,11 @@ impl Thread {
     }
 
     pub fn join(self) {
-        unsafe { c::WaitForSingleObject(self.handle.raw(), c::INFINITE); }
+        let rc = unsafe { c::WaitForSingleObject(self.handle.raw(), c::INFINITE) };
+        if rc == c::WAIT_FAILED {
+            panic!("failed to join on thread: {}",
+                   io::Error::last_os_error());
+        }
     }
 
     pub fn yield_now() {

src/libstd/thread/mod.rs

@@ -1230,6 +1230,11 @@ impl<T> JoinHandle<T> {
     /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
     /// [`panic`]: ../../std/macro.panic.html
     ///
+    /// # Panics
+    ///
+    /// This function may panic on some platforms if a thread attempts to join
+    /// itself or otherwise may create a deadlock with joining threads.
+    ///
     /// # Examples
     ///
     /// ```