docs: update documentation for v1.1.0 MPSC release

Author: codenimja

README.md

@@ -2,25 +2,27 @@
 
 [![CI](https://github.com/codenimja/nimsync/actions/workflows/ci.yml/badge.svg)](https://github.com/codenimja/nimsync/actions/workflows/ci.yml)
 [![Benchmark](https://github.com/codenimja/nimsync/actions/workflows/benchmark.yml/badge.svg)](https://github.com/codenimja/nimsync/actions/workflows/benchmark.yml)
-[![Nimble](https://img.shields.io/badge/nimble-v1.0.0-orange.svg)](https://nimble.directory/pkg/nimsync)
+[![Nimble](https://img.shields.io/badge/nimble-v1.1.0-orange.svg)](https://nimble.directory/pkg/nimsync)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Nim](https://img.shields.io/badge/nim-2.0.0%2B-yellow.svg?style=flat&logo=nim)](https://nim-lang.org)
 ![Peak](https://img.shields.io/badge/peak-615M_ops/sec-success)
 ![P99](https://img.shields.io/badge/p99_latency-31ns-blue)
 ![Contention](https://img.shields.io/badge/contention-0%25-brightgreen)
 
-**Lock-free SPSC channels for Nim with production-grade performance validation**
+**Lock-free SPSC and MPSC channels for Nim with production-grade performance validation**
 
-nimsync v1.0.0 is production-ready for SPSC channels with comprehensive benchmarking following industry standards (Tokio, Go, LMAX Disruptor, Redis). Performance: 615M ops/sec peak throughput, 31ns P99 latency, stable under burst loads. This is verified, tested, real code.
+nimsync v1.1.0 is production-ready for both SPSC and MPSC channels with comprehensive benchmarking following industry standards (Tokio, Go, LMAX Disruptor, Redis). Performance: 615M ops/sec SPSC peak, 16M ops/sec MPSC (2 producers), 31ns P99 latency, stable under burst loads. This is verified, tested, real code.
 
 ## Features
 
-- **High throughput**: 615M ops/sec (raw), 512K ops/sec (async) - [See all 7 benchmarks](#performance)
+- **High throughput**: 615M ops/sec SPSC (raw), 16M ops/sec MPSC (2 producers), 512K ops/sec (async) - [See benchmarks](#performance)
 - **Production-validated**: Comprehensive benchmark suite (throughput, latency, burst, stress, sustained)
 - **Industry-standard testing**: Following Tokio, Go, Rust Criterion, LMAX Disruptor methodologies
+- **SPSC and MPSC modes**: Single-producer or multi-producer with single consumer
 - Lock-free ring buffer with atomic operations
 - Zero GC pressure with ORC memory management
 - Cache-line aligned (64 bytes) to prevent false sharing
+- Wait-free MPSC algorithm (based on dbittman + JCTools patterns)
 - Power-of-2 sizing for efficient operations
 - Non-blocking `trySend`/`tryReceive`
 - Async `send`/`recv` wrappers for Chronos
@@ -45,7 +47,7 @@ nimble install
 
 ## Quick Start
 
-### Basic Usage
+### Basic Usage (SPSC)
 ```nim
 import nimsync
 
@@ -61,6 +63,36 @@ if chan.tryReceive(value):
   echo "Received: ", value
 ```
 
+### Multi-Producer Usage (MPSC)
+```nim
+import nimsync
+import std/[os, threadpool]
+
+# Create MPSC channel for multiple producers
+let chan = newChannel[int](1024, ChannelMode.MPSC)
+
+# Multiple producer threads
+proc producer(ch: Channel[int], id: int) =
+  for i in 0..<1000:
+    while not ch.trySend(id * 1000 + i):
+      discard  # Spin until space available
+
+# Start multiple producers
+spawn producer(chan, 1)
+spawn producer(chan, 2)
+spawn producer(chan, 3)
+
+# Single consumer
+var count = 0
+var value: int
+while count < 3000:
+  if chan.tryReceive(value):
+    echo "Received: ", value
+    count.inc
+
+sync()
+```
+
 ### Async Operations
 ```nim
 import nimsync
@@ -89,7 +121,10 @@ waitFor main()
 proc newChannel[T](size: int, mode: ChannelMode): Channel[T]
 ```
 Creates a channel with specified size (rounded to next power of 2).
-Only `ChannelMode.SPSC` is implemented.
+
+**Modes**:
+- `ChannelMode.SPSC`: Single Producer Single Consumer (fastest)
+- `ChannelMode.MPSC`: Multi-Producer Single Consumer (wait-free producers)
 
 ### Non-Blocking Operations
 ```nim
@@ -115,7 +150,9 @@ proc isFull[T](channel: Channel[T]): bool
 
 ### Comprehensive Benchmark Suite
 
-nimsync includes 7 official benchmarks following industry best practices:
+nimsync includes benchmarks for both SPSC and MPSC modes following industry best practices:
+
+#### SPSC Benchmarks (Single Producer Single Consumer)
 
 | Benchmark | Metric | Result | Industry Reference |
 |-----------|--------|--------|--------------------|
@@ -127,18 +164,36 @@ nimsync includes 7 official benchmarks following industry best practices:
 | **Sustained** | Long-duration | Stable over 10s | Cassandra/ScyllaDB |
 | **Async** | Overhead | 512K ops/sec | Standard async benchmarking |
 
+#### MPSC Benchmarks (Multi-Producer Single Consumer)
+
+| Producers | Throughput | Latency (avg) | Notes |
+|-----------|-----------|---------------|-------|
+| 1P | 33M ops/sec | 30ns | Comparable to SPSC |
+| 2P | 16M ops/sec | 62ns | Optimal sweet spot |
+| 4P | 9M ops/sec | 111ns | Good scalability |
+| 8P | 4M ops/sec | 250ns | Contention limited |
+
+**Key Findings**:
+- Wait-free MPSC algorithm: No CAS retry loops
+- Best performance: 2 producers (16M ops/sec)
+- Stress test: 1M items across 8 producers (5.65M ops/sec)
+- Latency stable: 96-117ns across 1-4 producers
+
 ### Quick Run
 ```bash
-# Run complete benchmark suite (~18 seconds)
+# Run SPSC benchmark suite (~18 seconds)
 ./tests/performance/run_all_benchmarks.sh
 
-# Run individual benchmarks
+# Run MPSC benchmarks
+nim c -d:danger --opt:speed --mm:orc tests/performance/benchmark_mpsc.nim
+./tests/performance/benchmark_mpsc
+
+# Run individual SPSC benchmarks
 nim c -d:danger --opt:speed --mm:orc tests/performance/benchmark_latency.nim
 ./tests/performance/benchmark_latency
 ```
 
 **Full Documentation**: See [`tests/performance/README.md`](tests/performance/README.md) for detailed explanations of each benchmark.
-```
 
 ### Third-Party Verification
 
@@ -150,9 +205,10 @@ Want to verify these claims yourself?
 
 ## Limitations
 
-1. **SPSC Only** - Single Producer Single Consumer only
-   - Each channel: ONE sender, ONE receiver
-   - MPSC/SPMC/MPMC will raise `ValueError`
+1. **Single Consumer Only** - All modes require single consumer
+   - SPSC: ONE sender, ONE receiver (fastest)
+   - MPSC: MULTIPLE senders, ONE receiver (wait-free)
+   - SPMC/MPMC not implemented
 
 2. **No close()** - Channels don't have close operation
    - Use sentinel values for shutdown signaling
@@ -164,12 +220,16 @@ Want to verify these claims yourself?
    - Starts at 1ms, backs off to 100ms max
    - Use `trySend`/`tryReceive` for zero-latency
 
+5. **MPSC contention** - Best performance with 2-4 producers
+   - 8+ producers experience diminishing returns due to contention
+
 ## Development
 
 ### Testing
 ```bash
-nim c -r tests/unit/test_channel.nim  # Basic tests
-nim c -r tests/unit/test_basic.nim    # Version check
+nim c -r tests/unit/test_channel.nim              # Basic SPSC tests
+nim c -r tests/unit/channels/test_mpsc_channel.nim  # MPSC tests
+nim c -r tests/unit/test_basic.nim                # Version check
 ```
 
 ### Benchmarking
@@ -198,8 +258,8 @@ This repository contains experimental implementations of:
 ## Roadmap
 
 - ✅ **v1.0.0**: Production SPSC channels (DONE!)
-- **v1.1.0**: MPSC channels + TaskGroup fixes
-- **v1.2.0**: Production-ready Streams
+- ✅ **v1.1.0**: MPSC channels (DONE!)
+- **v1.2.0**: TaskGroup fixes + Production-ready Streams
 - **v2.0.0**: Full async runtime with actors
 
 ## Known Issues
@@ -208,18 +268,17 @@ See [GitHub Issues](.github/) for experimental features and known limitations:
 
 - **Async wrappers use polling** - exponential backoff (1ms-100ms), use `trySend`/`tryReceive` for zero-latency
 - **TaskGroup has bugs** - nested async macros fail (not exported) - [See issue template](.github/ISSUE_TASKGROUP_BUG.md)
-- **MPSC not implemented** - multi-producer channels needed for actors - [See issue template](.github/ISSUE_MPSC_CHANNELS.md)
 - **NUMA untested** - cross-socket performance unknown - [See issue template](.github/ISSUE_NUMA_VALIDATION.md)
 
 **These are documented limitations, not intentional behavior.** Contributions to fix welcome!
 
 ## Contributing
 
 Contributions welcome! Priority areas:
-1. Fix TaskGroup nested async bug (blocking v0.3.0) - [Details](.github/ISSUE_TASKGROUP_BUG.md)
-2. Implement MPSC channels (enables actors) - [Details](.github/ISSUE_MPSC_CHANNELS.md)
-3. Validate NUMA performance - [Details](.github/ISSUE_NUMA_VALIDATION.md)
-4. Cross-platform support (macOS/Windows)
+1. Fix TaskGroup nested async bug - [Details](.github/ISSUE_TASKGROUP_BUG.md)
+2. Validate NUMA performance - [Details](.github/ISSUE_NUMA_VALIDATION.md)
+3. Cross-platform support (macOS/Windows)
+4. SPMC/MPMC channel implementations
 
 See [issue templates](.github/) for detailed specifications and acceptance criteria.
 
@@ -229,16 +288,17 @@ MIT License - see LICENSE for details.
 
 ---
 
-**Status**: Production-ready SPSC channels with comprehensive validation. Other features (TaskGroup, MPSC, actors) are experimental - see [GitHub Issues](.github/) for contributor opportunities.
+**Status**: Production-ready SPSC and MPSC channels with comprehensive validation. Other features (TaskGroup, actors, streams) are experimental - see [GitHub Issues](.github/) for contributor opportunities.
 
 ---
 
 ## Disclaimer
 
-**nimsync v1.0.0 is production-ready for SPSC channels.**
+**nimsync v1.1.0 is production-ready for SPSC and MPSC channels.**
 
-✅ **SPSC channels verified** - 615M ops/sec peak, 31ns P99 latency, 7-benchmark suite validation  
-⚠️ **Experimental features** - TaskGroup, MPSC, actors not yet production-ready ([help wanted](.github/))
+✅ **SPSC channels verified** - 615M ops/sec peak, 31ns P99 latency, 7-benchmark suite validation
+✅ **MPSC channels verified** - 16M ops/sec (2 producers), wait-free algorithm, comprehensive stress testing
+⚠️ **Experimental features** - TaskGroup, actors, streams not yet production-ready ([help wanted](.github/))
 
 We document performance honestly. We benchmark rigorously. We're transparent about limitations.
 

tests/performance/README.md

@@ -5,16 +5,22 @@ Official benchmark suite following industry best practices from Tokio, Go, and R
 ## Quick Start
 
 ```bash
-# Run all benchmarks
+# Run all SPSC benchmarks
 ./tests/performance/run_all_benchmarks.sh
 
-# Or run individually
+# Run MPSC benchmarks
+nim c -d:danger --opt:speed --mm:orc tests/performance/benchmark_mpsc.nim
+./tests/performance/benchmark_mpsc
+
+# Or run SPSC benchmarks individually
 nim c -d:danger --opt:speed --mm:orc tests/performance/benchmark_latency.nim
 ./tests/performance/benchmark_latency
 ```
 
 ## Benchmark Suite
 
+## SPSC Benchmarks (Single Producer Single Consumer)
+
 ### 1. benchmark_spsc_simple.nim - Throughput (Baseline)
 **What it measures**: Raw SPSC channel throughput  
 **Industry reference**: Standard practice for lock-free queue benchmarking  
@@ -114,6 +120,32 @@ nim c -r tests/performance/benchmark_concurrent.nim
 
 **Key insight**: Channel itself is 600M+ ops/sec, async wrapper adds polling overhead
 
+## MPSC Benchmarks (Multi-Producer Single Consumer)
+
+### 8. benchmark_mpsc.nim - Multi-Producer Performance
+**What it measures**: MPSC channel throughput, latency, and scalability
+**Industry reference**: JCTools MPSC queue benchmarking, Disruptor patterns
+**Results**: 16M ops/sec (2 producers), 9M ops/sec (4 producers), wait-free algorithm
+**Use case**: Concurrent producer scenarios (worker threads, event aggregation)
+
+```bash
+nim c -d:danger --opt:speed --mm:orc tests/performance/benchmark_mpsc.nim
+./tests/performance/benchmark_mpsc
+```
+
+**Benchmark suite includes**:
+- **Throughput comparison**: SPSC vs MPSC with 1/2/4/8 producers
+- **Latency measurement**: Average latency across different producer counts
+- **Scalability analysis**: Fixed items per producer, measuring scalability
+- **Size impact**: Performance across buffer sizes (64/256/1024/4096)
+- **Burst workload**: Handling bursty traffic patterns
+
+**Key findings**:
+- **2 producers**: Optimal sweet spot (16M ops/sec)
+- **Wait-free algorithm**: No CAS retry loops, predictable latency
+- **Stress tested**: 1M items across 8 producers (5.65M ops/sec)
+- **Latency stability**: 96-117ns across 1-4 producers
+
 ## Design Principles
 
 ✅ **Non-redundant**: Each benchmark measures a different aspect  
@@ -126,11 +158,12 @@ nim c -r tests/performance/benchmark_concurrent.nim
 
 | Category | Benchmarks | Purpose |
 |----------|-----------|---------|
-| **Throughput** | simple, concurrent | Raw performance numbers |
-| **Latency** | latency | Tail latency analysis |
-| **Stability** | burst, sustained | Real-world behavior |
-| **Tuning** | sizes | Optimization guidance |
-| **Limits** | stress | Breaking point analysis |
+| **Throughput** | simple, concurrent, mpsc | Raw performance numbers |
+| **Latency** | latency, mpsc | Tail latency analysis |
+| **Stability** | burst, sustained, mpsc | Real-world behavior |
+| **Tuning** | sizes, mpsc | Optimization guidance |
+| **Limits** | stress, mpsc | Breaking point analysis |
+| **Scalability** | mpsc | Multi-producer scaling |
 
 ## CI Integration