---
README.md | 4 ++++
src/lib.rs | 17 +++++++++++++++++
2 files changed, 21 insertions(+)
diff --git a/README.md b/README.md
index c039e0f..83d3b05 100644
--- a/README.md
+++ b/README.md
@@ -8,3 +8,7 @@ This library provides an alternative to tokio's [`sleep_until`] method which
takes a real time instead of a monotonically decreasing duration.
[`sleep_until`]: https://docs.rs/tokio/latest/tokio/time/fn.sleep_until.html
+
+# Contributing
+
+Send patches or questions to the list: https://lists.sr.ht/~pounce/tokio-walltime
diff --git a/src/lib.rs b/src/lib.rs
index d0e2ac2..295e903 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -69,6 +69,23 @@ unsafe fn disarm_timer(timer: libc::timer_t) -> Result<()> {
Ok(())
}
+/// Waits until the specified time.
+///
+/// `tokio::time::sleep` uses monotonic clock, so if the system is suspended while the timer is
+/// active, the timer is delayed by a period equal to the amount of time the system was suspended.
+///
+/// This timer operates using wall clock as a reference instead. If the system is suspended at the
+/// time that the timer would expire, the timer expires immediately after the system resumes from
+/// sleep.
+///
+/// # Errors
+///
+/// Returns an error if:
+/// - Setting a underlying signal handler fails for any reason (see [`signal#errors`]).
+/// - Getting the current time (via `clock_gettime(2)`) fails.
+/// - Creating the timer (via `timer_create(2)`) fails.
+/// - Setting the timer (via `timer_settime(2)`) fails.
+/// - Cleaning up the timer after it has triggered (via `timer_delete(2)`) fails.
#[cfg(unix)]
pub async fn sleep_until<Tz: chrono::TimeZone>(time: DateTime<Tz>) -> Result<()> {
let time = time.with_timezone(&Utc);
--
2.39.1