Rename reactor -> driver, prep for lib/reactivity

lib/runtime/src/time.rs

@@ -1,9 +1,11 @@
 //! Runtime time primitives.
+//!
+//! These helpers integrate with the runtime's timer queue and are designed to be used from
+//! futures scheduled with [`crate::queue_future`] or one of the runtime entry macros.
 
 use std::cell::{Cell, RefCell};
 use std::fmt;
 use std::future::{Future, poll_fn};
-use std::io;
 use std::pin::Pin;
 use std::rc::Rc;
 use std::task::Waker;
@@ -12,6 +14,7 @@ use std::time::Duration;
 
 use crate::{clear_timeout, set_timeout};
 
+/// Future returned by [`sleep`].
 pub struct Sleep {
     delay: Option<Duration>,
     state: Option<Rc<SleepState>>,
@@ -20,8 +23,18 @@ pub struct Sleep {
 }
 
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+/// Error returned by [`timeout`] when the deadline expires first.
 pub struct Elapsed;
 
+/// Returns a future that completes after `duration` has elapsed on the current runtime thread.
+///
+/// # Examples
+///
+/// ```
+/// # let _ = || async {
+/// ruin_runtime::time::sleep(std::time::Duration::from_millis(10)).await;
+/// # };
+/// ```
 pub fn sleep(duration: Duration) -> Sleep {
     Sleep {
         delay: Some(duration),
@@ -31,6 +44,24 @@ pub fn sleep(duration: Duration) -> Sleep {
     }
 }
 
+/// Runs `future` until it completes or `duration` elapses, whichever happens first.
+///
+/// The wrapped future is dropped when the timeout fires. As with other runtime operations, dropping
+/// a future cancels interest in the result but does not guarantee cancellation of any underlying
+/// OS work that future may have started.
+///
+/// # Examples
+///
+/// ```
+/// # let _ = || async {
+/// let result = ruin_runtime::time::timeout(
+///     std::time::Duration::from_millis(5),
+///     async { 42usize },
+/// )
+/// .await;
+/// assert_eq!(result, Ok(42));
+/// # };
+/// ```
 pub async fn timeout<F>(duration: Duration, future: F) -> Result<F::Output, Elapsed>
 where
     F: Future,
@@ -52,10 +83,6 @@ where
     .await
 }
 
-pub fn timeout_error(action: &'static str) -> io::Error {
-    io::Error::new(io::ErrorKind::TimedOut, format!("{action} timed out"))
-}
-
 impl Future for Sleep {
     type Output = ();