Merge pull request #30 from akashsoni01/main

2.0.6 and iter

Author: codefonsi

.github/workflows/rust.yml

@@ -0,0 +1,22 @@
+name: Rust
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Build
+      run: cargo build --verbose
+    - name: Run tests
+      run: cargo test --verbose

.gitignore

@@ -32,3 +32,6 @@ key-paths-core/.idea/tagged-core.iml
 key-paths-core/.idea/modules.xml
 key-paths-core/.idea/key-paths-core.iml
 *.mdc
+
+# Cheque dataset (benchmark images)
+benches/cheq_dataset

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rust-key-paths"
-version = "2.0.0"
+version = "2.0.7"
 edition = "2024"
 authors = ["Codefonsi <info@codefonsi.com>"]
 license = "MPL-2.0"
@@ -14,19 +14,26 @@ include = ["src/**/*", "Cargo.toml", "README.md", "LICENSE"]
 
 [dependencies]
 async-trait = "0.1"
-tokio = { version = "1.38.0", features = ["sync", "rt"], optional = true }
+pin-project = { version = "1.1", optional = true }
+tokio = { version = "1.38.0", features = ["sync", "rt", "rt-multi-thread", "macros", "time"], optional = true }
 parking_lot = { version = "0.12", optional = true }
 
 [workspace]
 resolver = "3" # or "3"
 members = [
     "key-paths-derive",
+    "key-paths-iter",
 ]
 
+# Use local rust-key-paths when developing (remove or override when publishing dependents)
+[patch.crates-io]
+rust-key-paths = { path = "." }
+
 
 [features]
 default = []
 parking_lot = ["dep:parking_lot"]
+pin_project = ["dep:pin-project"]
 tagged_core = ["tagged-core/default"]
 tokio = ["dep:tokio"]
 
@@ -40,6 +47,10 @@ uuid = { version = "1.0", features = ["v4", "serde"] }
 criterion = { version = "0.5", features = ["html_reports"] }
 tokio = { version = "1.38.0", features = ["sync", "rt", "rt-multi-thread", "macros"] }
 key-paths-derive = { path = "key-paths-derive" }
+key-paths-iter = { path = "key-paths-iter", features = ["rayon", "gpu"] }
+num_cpus = "1.16"
+rayon = "1.10"
+pin-project = "1.1"
 
 [[bench]]
 name = "deep_chain_leaf"
@@ -56,3 +67,27 @@ harness = false
 [[bench]]
 name = "deep_chain_async_only"
 harness = false
+
+[[bench]]
+name = "keypath_vs_unwrap"
+harness = false
+
+[[bench]]
+name = "ten_level_arc_rwlock"
+harness = false
+
+[[bench]]
+name = "ten_level_std_rwlock"
+harness = false
+
+[[bench]]
+name = "ten_level_tokio_rwlock"
+harness = false
+
+[[bench]]
+name = "scale_par_bench"
+harness = false
+
+[[bench]]
+name = "akp_cpu_bench"
+harness = false

README.md

@@ -3,15 +3,265 @@
 Key paths provide a **safe, composable way to access and modify nested data** in Rust.
 Inspired by **KeyPath and Functional Lenses** system, this feature rich crate lets you work with **struct fields** and **enum variants** as *first-class values*.
 
+## Starter Guide
+
+### Installation
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies]
+rust-key-paths = "2.0.6"
+key-paths-derive = "2.0.6"
+```
+
+### Basic usage
+
+```rust
+use std::sync::Arc;
+use key_paths_derive::Kp;
+
+#[derive(Debug, Kp)]
+struct SomeComplexStruct {
+    scsf: Option<SomeOtherStruct>,
+    scfs2: Arc<std::sync::RwLock<SomeOtherStruct>>,
+}
+
+#[derive(Debug, Kp)]
+struct SomeOtherStruct {
+    sosf: Option<OneMoreStruct>,
+}
+
+#[derive(Debug, Kp)]
+enum SomeEnum {
+    A(String),
+    B(Box<DarkStruct>),
+}
+
+#[derive(Debug, Kp)]
+struct OneMoreStruct {
+    omsf: Option<String>,
+    omse: Option<SomeEnum>,
+}
+
+#[derive(Debug, Kp)]
+struct DarkStruct {
+    dsf: Option<String>,
+}
+
+impl SomeComplexStruct {
+    fn new() -> Self {
+        Self {
+            scsf: Some(SomeOtherStruct {
+                sosf: Some(OneMoreStruct {
+                    omsf: Some(String::from("no value for now")),
+                    omse: Some(SomeEnum::B(Box::new(DarkStruct {
+                        dsf: Some(String::from("dark field")),
+                    }))),
+                }),
+            }),
+            scfs2: Arc::new(std::sync::RwLock::new(SomeOtherStruct {
+                sosf: Some(OneMoreStruct {
+                    omsf: Some(String::from("no value for now")),
+                    omse: Some(SomeEnum::B(Box::new(DarkStruct {
+                        dsf: Some(String::from("dark field")),
+                    }))),
+                }),
+            })),
+        }
+    }
+}
+fn main() {
+    let mut instance = SomeComplexStruct::new();
+
+    SomeComplexStruct::scsf()
+        .then(SomeOtherStruct::sosf())
+        .then(OneMoreStruct::omse())
+        .then(SomeEnum::b())
+        .then(DarkStruct::dsf())
+        .get_mut(&mut instance).map(|x| {
+        *x = String::from("🖖🏿🖖🏿🖖🏿🖖🏿");
+    });
+
+    println!("instance = {:?}", instance.scsf.unwrap().sosf.unwrap().omse.unwrap());
+    // output - instance = B(DarkStruct { dsf: Some("🖖🏿🖖🏿🖖🏿🖖🏿") })
+}
+```
+
+### Composing keypaths
+
+Chain through nested structures with `then()`:
+
+```rust
+#[derive(Kp)]
+struct Address { street: String }
+
+#[derive(Kp)]
+struct Person { address: Box<Address> }
+
+let street_kp = Person::address().then(Address::street());
+let street = street_kp.get(&person);  // Option<&String>
+```
+
+### Partial and Any keypaths
+
+Use `#[derive(Pkp, Akp)]` (requires `Kp`) to get type-erased keypath collections:
+
+- **PKp** – `partial_kps()` returns `Vec<PKp<Self>>`; value type erased, root known
+- **AKp** – `any_kps()` returns `Vec<AKp>`; both root and value type-erased for heterogeneous collections
+
+Filter by `value_type_id()` / `root_type_id()` and read with `get_as()`. For writes, dispatch to the typed `Kp` (e.g. `Person::name()`) based on TypeId.
+
+See examples: `pkp_akp_filter_typeid`, `pkp_akp_read_write_convert`.
+
+### GPU / wgpu (key-paths-iter, optional)
+
+The [key-paths-iter](https://github.com/codefonsi/rust-key-paths) crate can run **numeric** keypaths (e.g. `f32`) on the GPU via wgpu. Two styles:
+
+- **AKp runner** (`wgpu` module): `IntoNumericAKp` from Kp, `AKpTier::Numeric` / `Arbitrary`, `AKpRunner`. Examples: `kp_pkp_wgpu`, `akp_wgpu_runner`.
+- **Kp-only** (`kp_gpu` module): no AKp/PKp — `.map_gpu(wgsl)`, `.par_gpu(wgsl, roots, ctx)`, `GpuKpRunner`. Examples: `kp_gpu_example`, `kp_gpu_vec_example`, `kp_gpu_practical_app` (finance: Monte Carlo, batch options, stress-test). Kp with value `Vec<V>`: `.map_gpu_vec(wgsl)` for one dispatch over the vector.
+
+Run benchmarks: `cargo bench --bench akp_cpu_bench`. Typical results (MacBook Air M1):
+
+| Roots   | Serial (CPU) | Parallel CPU (Rayon) | Parallel GPU (wgpu) |
+|--------|---------------|----------------------|---------------------|
+| 1,000  | ~35 µs        | ~86 µs               | ~1.6 ms             |
+| 10,000 | ~350 µs       | ~425 µs              | ~1.9 ms             |
+| 50,000 | ~1.8 ms       | ~1.8 ms              | ~3.7 ms             |
+| 100,000| ~3.7 ms       | ~3.7 ms              | ~5.5 ms             |
+
+For this lightweight transform, CPU wins; GPU pays off for larger batches or heavier per-element math.
+
+### Features
+
+| Feature | Description |
+|---------|-------------|
+| `parking_lot` | Use `parking_lot::Mutex` / `RwLock` instead of `std::sync` |
+| `tokio` | Async lock support (`tokio::sync::Mutex`, `RwLock`) |
+| `pin_project` | Enable `#[pin]` field support for pin-project compatibility |
+
+### More examples
+
+```bash
+cargo run --example kp_derive_showcase
+cargo run --example pkp_akp_filter_typeid
+cargo run --example pkp_akp_read_write_convert
+# Kp/Pkp + wgpu (key-paths-iter with gpu feature)
+cargo run --example kp_pkp_wgpu
+cargo run --example akp_wgpu_runner
+cargo run --example kp_gpu_example
+cargo run --example kp_gpu_vec_example
+cargo run --example kp_gpu_practical_app
+# Box and Pin support
+cargo run --example box_and_pin_example
+# pin_project #[pin] fields
+cargo run --example pin_project_example --features pin_project
+cargo run --example pin_project_fair_race --features "pin_project,tokio"
+# Deadlock prevention (parallel execution)
+cargo run --example deadlock_prevention_sync --features parking_lot
+cargo run --example deadlock_prevention_async --features tokio
+```
+
+---
+
+## Supported containers
+
+The `#[derive(Kp)]` macro (from `key-paths-derive`) generates keypath accessors for these wrapper types:
+
+| Container | Access | Notes |
+|-----------|--------|-------|
+| `Option<T>` | `field()` | Unwraps to inner type |
+| `Box<T>` | `field()` | Derefs to inner |
+| `Pin<T>`, `Pin<Box<T>>` | `field()`, `field_inner()` | Container + inner (when `T: Unpin`) |
+| `Rc<T>`, `Arc<T>` | `field()` | Derefs; mut when unique ref |
+| `Vec<T>` | `field()`, `field_at(i)` | Container + index access |
+| `HashMap<K,V>`, `BTreeMap<K,V>` | `field_at(k)` | Key-based access |
+| `HashSet<T>`, `BTreeSet<T>` | `field()` | Container identity |
+| `VecDeque<T>`, `LinkedList<T>`, `BinaryHeap<T>` | `field()`, `field_at(i)` | Index where applicable |
+| `Result<T,E>` | `field()` | Unwraps `Ok` |
+| `Cow<'_, T>` | `field()` | `as_ref` / `to_mut` |
+| `Option<Cow<'_, T>>` | `field()` | Optional Cow unwrap |
+| `std::sync::Mutex<T>`, `std::sync::RwLock<T>` | `field()` | Container (use `LockKp` for lock-through) |
+| `Arc<Mutex<T>>`, `Arc<RwLock<T>>` | `field()`, `field_lock()` | Lock-through via `LockKp` |
+| `tokio::sync::Mutex`, `tokio::sync::RwLock` | `field_async()` | Async lock-through (tokio feature) |
+| `parking_lot::Mutex`, `parking_lot::RwLock` | `field()`, `field_lock()` | parking_lot feature |
+
+Nested combinations (e.g. `Option<Box<T>>`, `Option<Vec<T>>`, `Vec<Option<T>>`) are supported.
+
+### pin_project `#[pin]` fields (optional feature)
+
+When using [pin-project](https://docs.rs/pin-project), mark pinned fields with `#[pin]`. The derive generates:
+
+| `#[pin]` field type | Access | Notes |
+|---------------------|--------|-------|
+| Plain (e.g. `i32`) | `field()`, `field_pinned()` | Pinned projection via `this.project()` |
+| `Future` | `field()`, `field_pinned()`, `field_await()` | Poll through `Pin<&mut Self>` |
+| `Box<dyn Future<Output=T>>` | `field()`, `field_pinned()`, `field_await()` | Same for boxed futures |
+
+Enable with `pin_project` feature and add `#[pin_project]` to your struct:
+
+```rust
+#[pin_project]
+#[derive(Kp)]
+struct WithPinnedFuture {
+    fair: bool,
+    #[pin]
+    fut: Pin<Box<dyn Future<Output = String> + Send>>,
+}
+```
+
+Examples: `pin_project_example`, `pin_project_fair_race` (FairRaceFuture use case).
+
+## Performance: Kp vs direct unwrap
+
+Benchmark: nested `Option` chains and enum case paths (`cargo bench --bench keypath_vs_unwrap`).
+
+| Scenario | Keypath | Direct unwrap | Overhead |
+|----------|---------|---------------|----------|
+| 100× reuse (3-level) | ~36.6 ns | ~36.7 ns | ~1x |
+| 100× reuse (5-level) | ~52.3 ns | ~52.5 ns | ~1x |
+
+Access overhead comes from closure indirection in the composed chain. **Reusing a keypath** (build once, use many times) matches direct unwrap; building the chain each time adds ~1–2 ns.
+
+### Would static keypaths help?
+
+Yes. Static/const keypaths would:
+- Remove creation cost entirely (no closure chain construction per use)
+- Allow the compiler to inline the full traversal
+- Likely close the gap to near-zero overhead vs manual unwrap
+
+Currently, `Kp::then()` composes via closures that capture the previous step, so each access goes through a chain of function calls. A static keypath could flatten this to direct field offsets.
+
+---
+
+## Performance: LockKp (Arc&lt;Mutex&gt;, Arc&lt;RwLock&gt;)
+
 | Operation | Keypath | Direct Locks | Overhead |
 |-----------|---------|--------------|----------|
 | **Read**  | ~241 ns | ~117 ns      | ~2.1x    |
 | **Write** | ~239 ns | ~114 ns      | ~2.1x    |
 
-The keypath approach builds the chain each iteration and traverses through `LockKp.then().then().then_async().then()`; direct locks use `sync_mutex.lock()` then `tokio_mutex.lock().await`. The keypath overhead reflects chain construction plus composed traversal vs. manual lock nesting. Hot-path functions are annotated with `#[inline]` for improved performance.
+The keypath approach builds the chain each iteration and traverses through `LockKp.then().then().then_async().then()`; direct locks use `sync_mutex.lock()` then `tokio_mutex.lock().await`. Hot-path functions are annotated with `#[inline]` for improved performance.
+
+### 10-level deep Arc&lt;RwLock&gt; benchmarks (leaf: f64)
+
+Benchmark: 10 levels of nested `Arc<RwLock<Next>>`, reading/writing leaf `f64`. Run with:
+- `cargo bench --features parking_lot --bench ten_level_arc_rwlock`
+- `cargo bench --bench ten_level_std_rwlock`
+- `cargo bench --features tokio --bench ten_level_tokio_rwlock`
+
+**Incr** (write: leaf += 0.25):
+
+| RwLock implementation | keypath_static | keypath_dynamic | direct_lock |
+|-----------------------|----------------|-----------------|-------------|
+| **parking_lot**       | ~34 ns         | ~41 ns          | ~39 ns      |
+| **std::sync**         | ~46 ns         | ~54 ns          | ~46 ns      |
+| **tokio::sync**       | ~1.79 µs       | ~1.78 µs        | ~278 ns     |
+
+Static keypath (chain built once, reused) matches or beats direct lock for sync RwLocks. For tokio, async keypath has higher overhead than direct `.read().await`/`.write().await`; direct lock is fastest.
 
 ---
 
 ## 📜 License
 
-* Mozilla Public License 2.0
+* Mozilla Public License 2.0