feat: I/O and mutex support (v0.3)

Add epoll-based non-blocking I/O and kernel-like mutexes:
- src/io.rs: Complete epoll backend with timeout & error handling
- src/mutex.rs: Fair mutex with waiter queues & parking integration
- Enhanced scheduler to support synchronous I/O blocking
- Comprehensive test suites for I/O (epoll) and mutex behavior
- Documentation: LOOM.md concurrency model & README

src/scheduler.rs

@@ -73,6 +73,10 @@ struct Slot {
     /// Number of `JoinHandle`s still outstanding for this actor. The slot
     /// is reclaimed only when the actor is done AND outstanding_handles == 0.
     outstanding_handles: u32,
+    /// One-shot mailbox for the result of an in-flight `block_on_io` call.
+    /// The scheduler writes it on completion; `block_on_io` reads it on
+    /// resume.
+    pending_io_result: Option<crate::io::IoResult>,
 }
 
 impl Slot {
@@ -85,6 +89,7 @@ impl Slot {
             outcome: None,
             supervisor_channel: None,
             outstanding_handles: 0,
+            pending_io_result: None,
         }
     }
 }
@@ -102,6 +107,8 @@ struct SchedulerState {
     root_pid: Option<Pid>,
     /// Pending sleep timers. Min-heap keyed by deadline.
     timers: crate::timer::Timers,
+    /// IO worker thread. `None` outside `run()`.
+    io: Option<crate::io::IoThread>,
 }
 
 impl SchedulerState {
@@ -112,6 +119,7 @@ impl SchedulerState {
             run_queue: VecDeque::new(),
             root_pid: None,
             timers: crate::timer::Timers::new(),
+            io: None,
         }
     }
 
@@ -251,6 +259,7 @@ fn reclaim_slot(s: &mut SchedulerState, pid: Pid) {
     slot.supervisor_channel = None;
     slot.state = State::Done; // semantically vacant; allocator checks free_list
     slot.outstanding_handles = 0;
+    slot.pending_io_result = None;
     s.free_list.push(idx);
 }
 
@@ -284,6 +293,7 @@ pub fn spawn_under(supervisor: Pid, f: impl FnOnce() + Send + 'static) -> JoinHa
         slot.outcome = None;
         slot.waiters.clear();
         slot.supervisor_channel = None;
+        slot.pending_io_result = None;
         s.run_queue.push_back(pid);
         pid
     });
@@ -344,6 +354,53 @@ pub fn sleep(duration: std::time::Duration) {
     park_current();
 }
 
+/// Run `f` on the IO worker thread, park the current actor while it runs,
+/// and return `f`'s value when it completes. Panics inside `f` propagate
+/// to the calling actor.
+///
+/// Use this for blocking calls that would otherwise stall the scheduler —
+/// synchronous file IO, blocking C FFI, libpq, etc.
+pub fn block_on_io<F, T>(f: F) -> T
+where
+    F: FnOnce() -> T + Send + 'static,
+    T: Send + 'static,
+{
+    let me = current_pid().expect("block_on_io() called outside an actor");
+
+    // Box the user closure into the wire-form result-shaped closure that
+    // the worker expects. The worker also wraps in catch_unwind, but doing
+    // it here too would let us downcast `T` only when the closure didn't
+    // panic. We let the worker handle catch_unwind so the boxing here
+    // stays straightforward.
+    let work: Box<dyn FnOnce() -> crate::io::IoResult + Send> = Box::new(move || {
+        let v: T = f();
+        Ok(Box::new(v) as Box<dyn std::any::Any + Send>)
+    });
+
+    with_sched(|s| {
+        let io = s.io.as_mut().expect("io thread not started");
+        io.submit(me, work);
+    });
+
+    park_current();
+
+    // On resume, our slot has a result waiting.
+    let result = with_sched(|s| {
+        s.slot_mut(me)
+            .expect("block_on_io: own slot vanished")
+            .pending_io_result
+            .take()
+            .expect("block_on_io: resumed without a result")
+    });
+
+    match result {
+        Ok(any) => *any
+            .downcast::<T>()
+            .expect("block_on_io: result type mismatch — should be unreachable"),
+        Err(payload) => std::panic::resume_unwind(payload),
+    }
+}
+
 /// Wake a parked actor. If the actor isn't parked (already runnable or done)
 /// this is a no-op — that's important; channel and join can both fire
 /// spurious unparks under some orderings and we want them to be cheap.
@@ -405,6 +462,7 @@ pub fn run<F: FnOnce() + Send + 'static>(initial: F) {
         assert!(c.borrow().is_none(), "smarm::run() called recursively");
         let mut state = SchedulerState::new();
         state.root_pid = Some(ROOT_PID);
+        state.io = Some(crate::io::IoThread::start().expect("failed to start io thread"));
         *c.borrow_mut() = Some(state);
     });
 
@@ -445,24 +503,76 @@ fn schedule_loop() {
             });
         }
 
-        // 2. Pop a runnable actor. If none, sleep on the soonest timer or
-        // exit if there isn't one.
+        // 2. Drain IO completions: route each result to its slot and
+        // unpark the actor. Drain even when we have other runnables —
+        // it's cheap (a try_lock of the completion queue) and keeps
+        // pending_io_result freshness bounded.
+        let completions = with_sched(|s| {
+            s.io.as_mut().map(|io| io.drain_completions()).unwrap_or_default()
+        });
+        for (pid, result) in completions {
+            with_sched(|s| {
+                if let Some(io) = s.io.as_mut() {
+                    io.outstanding = io.outstanding.saturating_sub(1);
+                }
+                if let Some(slot) = s.slot_mut(pid) {
+                    slot.pending_io_result = Some(result);
+                    if matches!(slot.state, State::Parked) {
+                        slot.state = State::Runnable;
+                        s.run_queue.push_back(pid);
+                    }
+                }
+            });
+        }
+
+        // 3. Pop a runnable actor. If none, decide whether to block on
+        // the wake pipe (for timers or IO) or exit (nothing pending).
         let pid = match with_sched(|s| s.run_queue.pop_front()) {
             Some(p) => p,
             None => {
-                let next = with_sched(|s| s.timers.peek_deadline());
-                match next {
-                    Some(deadline) => {
+                // Read out what we'd need to block on. We must take the
+                // wake fd separately because we can't hold an SCHED
+                // borrow across `poll_wake` — the IO thread will be
+                // trying to take the completions mutex, which is fine,
+                // but the scheduler thread itself mustn't hold SCHED
+                // borrowed across a blocking syscall.
+                let (next_deadline, io_outstanding, wake_fd) = with_sched(|s| {
+                    let next = s.timers.peek_deadline();
+                    let (out, fd) = match s.io.as_ref() {
+                        Some(io) => (io.outstanding, Some(io.wake_fd())),
+                        None     => (0, None),
+                    };
+                    (next, out, fd)
+                });
+
+                match (next_deadline, io_outstanding, wake_fd) {
+                    // Nothing pending — we're done.
+                    (None, 0, _) | (None, _, None) => return,
+                    // Timer pending, nothing else: poll with a deadline,
+                    // or fall back to plain sleep if we somehow have no
+                    // wake fd (shouldn't happen — io thread is always up
+                    // during run()).
+                    (Some(deadline), _, fd_opt) => {
                         let now = std::time::Instant::now();
                         if deadline > now {
-                            // No other thread can wake us; plain sleep is
-                            // correct. When the IO thread lands in v0.2
-                            // this becomes a Condvar / pipe wakeup.
-                            std::thread::sleep(deadline - now);
+                            let timeout = deadline - now;
+                            match fd_opt {
+                                Some(fd) => {
+                                    crate::io::poll_wake(fd, Some(timeout));
+                                    crate::io::drain_wake_pipe(fd);
+                                }
+                                None => std::thread::sleep(timeout),
+                            }
                         }
                         continue;
                     }
-                    None => return, // no runnables, no timers — done.
+                    // No timer, but IO outstanding: poll forever for the
+                    // pipe wakeup.
+                    (None, _, Some(fd)) => {
+                        crate::io::poll_wake(fd, None);
+                        crate::io::drain_wake_pipe(fd);
+                        continue;
+                    }
                 }
             }
         };