Readme and no_std support

Author: tomerfiliba

.github/workflows/ci.yml

@@ -16,5 +16,6 @@ jobs:
             - uses: actions/checkout@v4
             - uses: dtolnay/rust-toolchain@stable
             - run: cargo test
+            - run: cargo check --no-default-features
             - run: cargo run --example raw
             - run: cargo run --example intrusive

Cargo.toml

@@ -3,4 +3,8 @@ name = "intrusivelock"
 version = "0.1.0"
 edition = "2024"
 
+[features]
+default = ["std"]
+std = []
+
 [dependencies]

README.md

@@ -1,38 +1,105 @@
-# Intrusive Locks for Rust
+# intrusivelock
 
-The purpose of this crate is to provide intrusive locks (locks that are contained inside the memory region 
-they protect). For example, data that's kept in an `mmap` - where you want the lock and the data it protects 
-to live side-by-side.
+Intrusive locks for Rust — locks that live inside the memory region they protect.
 
-Currently only `SpinRwLock` is implemented. Unlike rust's canonical locks/mutexes, it does not hold an `UnsafeCell<T>` - 
-it's a standalone lock object. You can use `IntrusiveSpinRwLock` to encompass the value to protect, which must contain
-the lock inside (use `HasIntrusiveSpinRwLock` to return the contained lock).
+This is useful when the lock and the data must be co-located in the same allocation, for example inside an `mmap`-backed region, a shared-memory arena, or a custom cache-line-aligned struct.
 
-Notes:
-* Being a spin lock, it is expected to work under low-to-moderate contention.
-* It is not intended for multiprocessing, only multithreading. You need kernel support 
+## Features
+
+- **`SpinRwLock`** — a standalone, 8-byte reader-writer spin lock (`AtomicU64`). Unlike `std::sync::RwLock`, it does not wrap data in an `UnsafeCell<T>`. You manage the protected data yourself.
+- **`IntrusiveSpinRwLock<T>`** — a safe wrapper that pairs a value `T` (which contains a `SpinRwLock`) with RAII read/write guards that `Deref`/`DerefMut` into `T`.
+- **`try_read` / `try_write`** — non-blocking variants that return `None` on contention.
+- **Writer-preferring** — once a writer is pending, new readers are blocked until the writer completes. This prevents writer starvation under read-heavy workloads.
+
+### Design notes
+
+- Being a spin lock, it is intended for **low-to-moderate contention** with short critical sections.
+- It is **not** suitable for multi-process synchronization (which requires kernel-assisted locks like `pthread_rwlock` or futexes).
+- There is **no poisoning**: if a thread panics inside a critical section, subsequent lock acquisitions will succeed without any indication of the prior panic.
+
+## Usage
+
+### Intrusive (recommended)
+
+Embed the lock inside your data structure and implement `HasIntrusiveSpinRwLock`:
 
-## Example
 ```rust
+use intrusivelock::spin_rwlock::*;
+
 #[derive(Default)]
-#[repr(C, align(64))]
-struct _MyCacheLine {
-    val2: u128,
-    val1: u64,
+struct MyData {
     _lock: SpinRwLock,
-    val3: [u8; 32],
+    counter: u64,
 }
 
-unsafe impl HasIntrusiveSpinRwLock for _MyCacheLine {
-    fn lock<'a>(&'a self) -> &'a SpinRwLock {
+unsafe impl HasIntrusiveSpinRwLock for MyData {
+    fn lock(&self) -> &SpinRwLock {
         &self._lock
     }
 }
 
-type MyCacheLine = IntrusiveSpinRwLock<_MyCacheLine>;
+type Protected = IntrusiveSpinRwLock<MyData>;
+
+let data = Protected::default();
 
-let cache_line = MyCacheLine::new(_MyCacheLine::default());
+// Write access — returns a guard that DerefMuts into MyData
+data.write().counter += 1;
 
-cache_line.write().val2 = 12345;
-assert_eq!(cache_line.read().val2, 12345);
+// Read access
+assert_eq!(data.read().counter, 1);
+
+// Non-blocking
+if let Some(guard) = data.try_write() {
+    // got exclusive access
+}
 ```
+
+### Standalone lock
+
+Use `SpinRwLock` directly when you need the lock separate from the data (e.g. protecting a `static mut`):
+
+```rust
+use intrusivelock::spin_rwlock::SpinRwLock;
+
+let lock = SpinRwLock::new();
+
+{
+    let _r = lock.read();   // shared access
+}
+{
+    let _w = lock.write();  // exclusive access
+}
+```
+
+## API
+
+### `SpinRwLock`
+
+| Method | Description |
+|--------|-------------|
+| `new() -> Self` | Create a new unlocked `SpinRwLock` |
+| `read() -> ReadGuard` | Acquire shared read access (spins until available) |
+| `write() -> WriteGuard` | Acquire exclusive write access (spins until available) |
+| `try_read() -> Option<ReadGuard>` | Try to acquire read access; returns `None` if contended |
+| `try_write() -> Option<WriteGuard>` | Try to acquire write access; returns `None` if contended |
+
+### `IntrusiveSpinRwLock<T>`
+
+| Method | Description |
+|--------|-------------|
+| `new(value: T) -> Self` | Wrap a value containing an embedded lock |
+| `read() -> IntrusiveReadGuard<T>` | Shared access; guard derefs to `&T` |
+| `write() -> IntrusiveWriteGuard<T>` | Exclusive access; guard derefs to `&mut T` |
+| `try_read() -> Option<IntrusiveReadGuard<T>>` | Non-blocking read attempt |
+| `try_write() -> Option<IntrusiveWriteGuard<T>>` | Non-blocking write attempt |
+
+## `no_std` support
+
+The crate is `no_std`-compatible. The `std` feature is enabled by default (providing `thread::yield_now()` in the spin backoff). To use in a `no_std` environment, disable default features:
+
+```toml
+[dependencies]
+intrusivelock = { version = "0.1", default-features = false }
+```
+
+Under `no_std`, the backoff strategy falls back to `core::hint::spin_loop()` instead of yielding.

src/lib.rs

@@ -1 +1,3 @@
+#![cfg_attr(not(feature = "std"), no_std)]
+
 pub mod spin_rwlock;

src/spin_rwlock.rs

@@ -1,4 +1,4 @@
-use std::{
+use core::{
     cell::UnsafeCell,
     ops::{Deref, DerefMut},
     sync::atomic::{AtomicU64, Ordering},
@@ -33,11 +33,14 @@ impl Backoff {
     fn spin(&mut self) {
         if self.spins < 200 {
             // Phase 1: busy-spin for the first 200 attempts.
-            std::hint::spin_loop();
+            core::hint::spin_loop();
             self.spins += 1;
         } else {
             // Phase 2: yield then do 10 more spins before yielding again.
+            #[cfg(feature = "std")]
             std::thread::yield_now();
+            #[cfg(not(feature = "std"))]
+            core::hint::spin_loop();
             self.spins = 190;
         }
     }