(lib/sleep_until) adds test & update docs & fix mac support

Author: dvdsk

library/std/src/sys/pal/unix/thread.rs

@@ -357,10 +357,6 @@ impl Thread {
 
     #[cfg(any(target_os = "macos", target_os = "ios", target_os = "tvos", target_os = "watchos"))]
     pub fn sleep_until(deadline: crate::time::Instant) {
-        // does not count during sleep/suspend same as clock monotonic
-        // does instant use mach_absolute_time?
-        // https://developer.apple.com/library/archive/technotes/tn2169/_index.html
-
         use super::time::Timespec;
         use core::mem::MaybeUninit;
 

library/std/src/sys/pal/unix/time.rs

@@ -19,7 +19,7 @@ pub(in crate::sys) const TIMESPEC_MAX_CAPPED: libc::timespec = libc::timespec {
 #[repr(transparent)]
 #[rustc_layout_scalar_valid_range_start(0)]
 #[rustc_layout_scalar_valid_range_end(999_999_999)]
-pub(in crate::sys::unix) struct Nanoseconds(pub(in crate::sys::unix) u32);
+pub(crate) struct Nanoseconds(pub(crate) u32);
 
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct SystemTime {
@@ -28,8 +28,8 @@ pub struct SystemTime {
 
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub(crate) struct Timespec {
-    tv_sec: i64,
-    tv_nsec: Nanoseconds,
+    pub(crate) tv_sec: i64,
+    pub(crate) tv_nsec: Nanoseconds,
 }
 
 impl SystemTime {
@@ -288,7 +288,7 @@ impl Instant {
         Some(Instant { t: self.t.checked_sub_duration(other)? })
     }
 
-    pub(in crate::sys::unix) fn into_timespec(self) -> Timespec {
+    pub(crate) fn into_timespec(self) -> Timespec {
         self.t
     }
 }

library/std/src/thread/mod.rs

@@ -878,8 +878,34 @@ pub fn sleep(dur: Duration) {
 ///
 /// # Platform-specific behavior
 ///
-/// This function uses [`sleep`] internally, see its platform-specific behavior.
+/// In most cases this function will call an OS specific function. Where that
+/// is not supported [`sleep`] is used. Those platforms are referred to as other
+/// in the table below.
 ///
+/// # Underlying System calls
+///
+/// The following system calls are [currently] being used:
+///
+///
+/// |  Platform |               System call                                            |
+/// |-----------|----------------------------------------------------------------------|
+/// | Linux     | [clock_nanosleep] (Monotonic clock)                                  |
+/// | BSD except OpenBSD | [clock_nanosleep] (Monotonic Clock)]                        |
+/// | Android   | [clock_nanosleep] (Monotonic Clock)]                                 |
+/// | Solaris   | [clock_nanosleep] (Monotonic Clock)]                                 |
+/// | Illumos   | [clock_nanosleep] (Monotonic Clock)]                                 |
+/// | Darwin    | [mach_wait_until]                                                    |
+/// | WASI      | [subscription_clock]                                                 |
+/// | Windows   | [SetWaitableTimer]                                                   |
+/// | Other     | `sleep_until` uses [`sleep`] and does not issue a syscall itself     |
+///
+/// [currently]: crate::io#platform-specific-behavior
+/// [clock_nanosleep]: https://linux.die.net/man/3/clock_nanosleep
+/// [subscription_clock]: https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/docs.md#-subscription_clock-record
+/// [mach_wait_until]: https://developer.apple.com/library/archive/technotes/tn2169/_index.html
+/// [SetWaitableTimer]: https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-setwaitabletimer
+///
+/// **Disclaimer:** These system calls might change over time.
 ///
 /// # Examples
 ///
@@ -904,9 +930,9 @@ pub fn sleep(dur: Duration) {
 /// }
 /// ```
 ///
-/// A slow api we must not call too fast and which takes a few
+/// A slow API we must not call too fast and which takes a few
 /// tries before succeeding. By using `sleep_until` the time the
-/// api call takes does not influence when we retry or when we give up
+/// API call takes does not influence when we retry or when we give up
 ///
 /// ```no_run
 /// #![feature(thread_sleep_until)]

library/std/tests/thread.rs

@@ -2,6 +2,8 @@ use std::cell::{Cell, RefCell};
 use std::sync::{Arc, Mutex};
 use std::thread;
 use std::time::Duration;
+#[feature(thread_sleep_until)]
+use std::time::Instant;
 
 #[test]
 #[cfg_attr(any(target_os = "emscripten", target_os = "wasi"), ignore)] // no threads
@@ -78,3 +80,14 @@ fn available_parallelism() {
     // check that std::thread::available_parallelism() returns a valid value
     assert!(thread::available_parallelism().is_ok());
 }
+
+#[test]
+fn sleep_until() {
+    let now = Instant::now();
+    let period = Duration::from_millis(100);
+    let deadline = now + period;
+    thread::sleep_until(deadline);
+
+    let elapsed = now.elapsed();
+    assert!(elapsed >= period);
+}