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/lib.rs

@@ -2,11 +2,14 @@
 //!
 //! Erlang-style green-thread actor concurrency for Rust.
 //!
-//! v0.1 is single-threaded. One scheduler, one OS thread. The scheduler
+//! Single-threaded for now: one scheduler, one OS thread. The scheduler
 //! cooperatively interleaves green-thread actors with hand-rolled context
 //! switches. Actors communicate by sending `Send` messages over channels;
 //! every actor has a supervisor, which is itself just an actor with a
-//! `Receiver<Signal>`.
+//! `Receiver<Signal>`. Synchronisation primitives — `Mutex<T>` with
+//! mandatory lock timeouts, channel `recv`, `sleep`, and epoll-backed
+//! `wait_readable`/`wait_writable` — all park the green thread, never
+//! the OS thread.
 //!
 //! See `LOOM.md` for the design intent and the deferred-for-later list.
 
@@ -20,6 +23,7 @@ pub mod scheduler;
 pub mod supervisor;
 pub mod timer;
 pub mod io;
+pub mod mutex;
 
 // ---------------------------------------------------------------------------
 // Global allocator
@@ -37,10 +41,16 @@ static ALLOCATOR: preempt::PreemptingAllocator = preempt::PreemptingAllocator;
 // ---------------------------------------------------------------------------
 
 pub use channel::{channel, Receiver, RecvError, Sender};
+pub use mutex::{LockTimeout, Mutex, MutexGuard};
 pub use pid::Pid;
 pub use scheduler::{
-    block_on_io, run, self_pid, sleep, spawn, spawn_under, yield_now, JoinError, JoinHandle,
+    block_on_io, run, self_pid, sleep, spawn, spawn_under, wait_readable, wait_writable,
+    yield_now, JoinError, JoinHandle,
 };
+// `read` and `write` would shadow heavily-used names if re-exported at the
+// crate root; users reach for them as `smarm::scheduler::read` /
+// `smarm::scheduler::write` instead. May reshuffle into a `smarm::io`
+// surface in a future pass.
 pub use supervisor::Signal;
 
 // ---------------------------------------------------------------------------