feat: add lock-free type checking and CI improvements

Add compile-time safety checks:
- Queue item types checked with isLockFree on arc/orc
- ref types error by default (use spinlocks for refcounting)
- Use -d:allowNonLockFreeQueueItems to opt-out

Update CI/test infrastructure:
- Test with arc, orc, refc memory managers
- Test with -d:nimEnforceLockFreeAtomics flag
- Stress tests updated with MM variants

Add documentation:
- Thread safety section in README
- Slot-ownership typestates documentation

Bump version to 3.2.0.

Author: elijahr

.github/workflows/build.yml

@@ -60,8 +60,12 @@ jobs:
           export SANITIZE_ADDRESS=${{ matrix.sanitize-address }}
           . "${HOME}/.asdf/asdf.sh"
           nimble develop -y
+          echo "::group::Run test suite (includes arc, orc, refc, lock-free enforcement)"
           nimble test
+          echo "::endgroup::"
+          echo "::group::Run examples"
           nimble examples
+          echo "::endgroup::"
 
   test_non_x86:
     name: Test nim-${{ matrix.nim-version }} / debian-buster / ${{ matrix.arch }}

CHANGELOG.md

@@ -7,11 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.2.0] - 2025-12-18
+
 ### Added
 
+- Unbounded queue implementations with DEBRA epoch-based reclamation
+  - `UnboundedSipsic` - Single-producer, single-consumer (no DEBRA needed)
+  - `UnboundedSipmuc` - Single-producer, multi-consumer
+  - `UnboundedMupsic` - Multi-producer, single-consumer
+  - `UnboundedMupmuc` - Multi-producer, multi-consumer
+- Typestate-enforced push/pop operations for all unbounded queues
+- Compile-time lock-free type checking for queue item types
+  - Errors on `ref` types with arc/orc (uses spinlocks for refcounting)
+  - Use `-d:allowNonLockFreeQueueItems` to opt-out
+- Thread safety documentation in README
+- Slot-ownership typestates documentation
+- CI testing with multiple memory managers (arc, orc, refc)
+- CI testing with `-d:nimEnforceLockFreeAtomics` flag
+
 ### Changed
 
-### Removed
+- Test suite now runs with arc, orc, refc memory managers
+- Test suite now verifies lock-free enforcement
+- Stress tests updated with MM variants
+- Dependencies updated: `typestates >= 0.3.1`, `debra >= 0.2.0`
 
 ## [3.1.0] - 2024-09-28
 

README.md

@@ -26,6 +26,61 @@ API documentation: https://elijahr.github.io/lockfreequeues
 nimble install lockfreequeues
 ```
 
+## Thread Safety and Lock-Free Guarantees
+
+### Item Type Requirements
+
+By default, lockfreequeues requires that queue item types are lock-free:
+
+```nim
+import lockfreequeues
+
+# These work - lock-free types
+var queue1 = newUnboundedSipsic[64, int]()
+var queue2 = newUnboundedSipsic[64, uint64]()
+var queue3 = newUnboundedSipsic[64, pointer]()
+
+type NodeObj = object
+  value: int
+var queue4 = newUnboundedSipsic[64, ptr NodeObj]()
+
+# This fails on arc/orc - ref uses spinlocks for refcounting
+type Node = ref object
+  value: int
+var queue5 = newUnboundedSipsic[64, Node]()  # Compile error!
+```
+
+### Why This Matters
+
+On arc/orc memory managers, `ref` types use reference counting. While the queue's CAS operations correctly serialize slot access, reference counting operations on ref types may use spinlock-based atomics on some platforms, potentially introducing subtle issues.
+
+### Allowing Non-Lock-Free Types
+
+If you understand the trade-offs and need to use non-lock-free types:
+
+```bash
+nim c -d:allowNonLockFreeQueueItems your_program.nim
+```
+
+### Recommended Patterns
+
+For maximum safety and portability:
+
+- **Value types**: Use int, uint64, float, enums, simple objects
+- **Pointers**: Use `ptr T` when you need indirection (you manage lifetime)
+- **Avoid ref types**: On arc/orc, prefer `ptr T` with manual memory management
+- **Test on target platform**: Always verify lock-free status on your deployment target
+
+### Testing Lock-Free Behavior
+
+Include tests with multiple memory managers:
+
+```bash
+nim c -r --mm:refc tests/mytest.nim
+nim c -r --mm:arc tests/mytest.nim
+nim c -r --mm:orc tests/mytest.nim
+```
+
 ## Examples
 
 Examples are located in the [examples](https://github.com/elijahr/lockfreequeues/tree/master/examples) directory and can be compiled and run with:

docs/slot-ownership-typestates.md

@@ -0,0 +1,214 @@
+# Slot Ownership Typestates
+
+## Overview
+
+Slot ownership typestates make data races structurally impossible by tracking slot ownership through the type system. Each state transition enforces critical invariants at compile-time.
+
+## Producer-Side Flow
+
+```
+tryClaimSlot()
+    |
+    v
+SlotClaimed ----[writeItem]----> SlotWritten ----[commitSlot]----> SlotCommitted
+    |                                |
+    v                                v
+ SegmentFull                      [data ready]
+```
+
+### States
+
+- **SlotClaimed**: Exclusive write access after winning CAS
+  - Guarantees: This thread owns the slot index
+  - Linear type: Can only use once (via `sink` parameter)
+
+- **SlotWritten**: Data written but not visible yet
+  - Guarantees: Data in slot, but consumers blocked
+
+- **SlotCommitted**: Data visible to consumers
+  - Guarantees: Consumers can now read
+
+### Transitions
+
+```nim
+# Try to claim a slot
+let result = tryClaimSlot(segment)
+
+case result.kind:
+of ckClaimed:
+  # Won CAS - have exclusive access
+  let claimed = result.claimed
+
+  # Write data (consumes claimed token)
+  let written = writeItem(claimed, myData)
+
+  # Commit (make visible to consumers)
+  let committed = commitSlot(written)
+
+of ckSegmentFull:
+  # Allocate new segment and retry
+  discard
+
+of ckRetry:
+  # Lost CAS race, try again
+  discard
+```
+
+## Consumer-Side Flow
+
+```
+tryClaimForRead()
+    |
+    v
+SlotAvailable ----[readItem]----> T (data)
+    |
+    v
+SlotPending ----[waitForCommit]----> SlotAvailable
+```
+
+### States
+
+- **SlotAvailable**: Slot ready to read
+  - Guarantees: Producer has committed, data is valid
+
+- **SlotPending**: Claimed but not committed (MPSC only)
+  - Need to wait for producer to commit
+
+### Transitions
+
+```nim
+# Try to claim a slot for reading
+let result = tryClaimForRead(segment)
+
+case result.kind:
+of pkAvailable:
+  # Data ready - can read immediately
+  let data = readItem(result.available)
+
+of pkPending:
+  # Producer hasn't committed yet - wait
+  let available = waitForCommit(result.pending)
+  let data = readItem(available)
+
+of pkExhausted:
+  # Segment empty, advance to next
+  discard
+
+of pkEmpty:
+  # Queue empty
+  discard
+```
+
+## Safety Guarantees
+
+| Guarantee | How Enforced |
+|-----------|--------------|
+| No write without CAS | `writeItem` requires `SlotClaimed`, only from successful CAS |
+| No double write | `sink` parameter consumes `SlotClaimed` token |
+| No commit without write | `commitSlot` requires `SlotWritten` |
+| No read without CAS | `readItem` requires `SlotAvailable`, only from successful CAS |
+| No read uncommitted data | `SlotAvailable` only when committed flag set (MPSC) |
+
+## Type System Enforcement
+
+The type system makes these errors impossible:
+
+```nim
+# ERROR: Cannot write without claiming
+let written = writeItem(segment, data)  # No SlotClaimed token!
+
+# ERROR: Cannot reuse claimed token
+let claimed = tryClaimSlot(segment).claimed
+let written1 = writeItem(claimed, data1)
+let written2 = writeItem(claimed, data2)  # claimed already consumed!
+
+# ERROR: Cannot commit without writing
+let committed = commitSlot(claimed)  # Need SlotWritten, not SlotClaimed!
+
+# ERROR: Cannot read without claiming
+let data = readItem(segment, 0)  # No SlotAvailable token!
+```
+
+## Integration with DEBRA Typestates
+
+Slot ownership states compose with DEBRA pin/unpin states:
+
+```nim
+type
+  MPSCPushContext[T; S, MT: static int] = object
+    pinnedHandle: ThreadHandle[MT]
+    pinnedEpoch: uint64
+    queue: ptr UnboundedMupsicBase[S, T, MT]
+    slotOwnership: SlotClaimed[T, S]  # Embedded slot state
+```
+
+This ensures:
+- Must be pinned to push
+- Must claim slot to write
+- All invariants enforced together
+
+## MPSC Implementation Example
+
+The unbounded MPSC queue uses the following typestate progression:
+
+### Push Operation States
+
+1. **MPSCPushReady**: Initial state with pinned DEBRA context
+2. **MPSCPushSegmentLoaded**: Segment and tail position loaded
+3. **MPSCPushSlotClaimed**: Slot claimed via CAS (or SegmentFull/Retry)
+4. **MPSCPushItemWritten**: Data written to slot
+5. **MPSCPushComplete**: Committed flag set, data visible to consumers
+
+### Example Usage
+
+```nim
+import debra
+import lockfreequeues/typestates/unbounded_mpsc_push
+
+# Setup
+var manager = initDebraManager[4]()
+let handle = registerThread(manager)
+var queue: UnboundedMupsicBase[64, int, 4]
+# ... initialize queue ...
+
+# Push operation
+let pinned = unpinned(handle).pin()
+let ready = startPush(pinned, addr queue)
+let loaded = ready.loadSegment()
+
+let claimResult = loaded.tryClaimSlot()
+case claimResult.kind:
+of mMPSCPushSlotClaimed:
+  let claimed = claimResult.mpscpushslotclaimed
+  let written = claimed.writeItem(42)
+  let complete = written.markCommitted()
+  discard complete.extractPinned().unpin()
+
+of mMPSCPushSegmentFull:
+  # Handle segment allocation
+  let newSeg = newSegment()
+  let ready = claimResult.mpscpushsegmentfull.allocateNewSegment(newSeg)
+  # Retry...
+
+of mMPSCPushReady:
+  # CAS failed, retry
+  discard
+```
+
+## Performance
+
+Slot ownership typestates are **zero-cost abstractions**:
+
+- All types are compile-time only
+- No runtime overhead
+- Same assembly as hand-written CAS code
+- Just adds compile-time safety
+
+## Future Extensions
+
+Potential enhancements:
+
+- Batch operations: Claim multiple slots at once
+- Backpressure: SlotClaimFailed -> wait/retry logic
+- Priority: Different claim strategies based on priority
+- Monitoring: Track claim success rates

lockfreequeues.nimble

@@ -16,12 +16,20 @@ requires "debra >= 0.2.0"
 
 # Tasks
 task test, "Runs the test suite":
-  # C
+  # C with default MM (orc)
   exec "nim c --threads:on -r -f tests/test.nim"
 
   # C++
   exec "nim cpp --threads:on -r -f tests/test.nim"
 
+  # Test with different memory managers
+  exec "nim c --mm:arc --threads:on -r -f tests/test.nim"
+  exec "nim c --mm:refc --threads:on -r -f tests/test.nim"
+
+  # Test with lock-free enforcement (ensures no spinlock fallback)
+  exec "nim c --mm:arc -d:nimEnforceLockFreeAtomics --threads:on -r -f tests/test.nim"
+  exec "nim c --mm:orc -d:nimEnforceLockFreeAtomics --threads:on -r -f tests/test.nim"
+
   if getEnv("SANITIZE_THREADS") != "no":
     # C (with thread sanitization, requires atomicArc for thread-safe refcounting)
     exec "nim c --cc:clang --mm:atomicArc --passC:\"-fsanitize=thread\" --passL:\"-fsanitize=thread\" --threads:on -r -f tests/test.nim"
@@ -49,12 +57,19 @@ task benchmarks, "Runs the benchmark suite":
 
 
 task stresstests, "Runs the stress test suite (multi-threaded)":
-  # C
+  # C with default MM (orc)
   exec "nim c --path:src --threads:on -r -f stress-tests/stress_test.nim"
 
   # C++
   exec "nim cpp --path:src --threads:on -r -f stress-tests/stress_test.nim"
 
+  # Test with different memory managers
+  exec "nim c --mm:arc --path:src --threads:on -r -f stress-tests/stress_test.nim"
+  exec "nim c --mm:refc --path:src --threads:on -r -f stress-tests/stress_test.nim"
+
+  # Test with lock-free enforcement
+  exec "nim c --mm:arc -d:nimEnforceLockFreeAtomics --path:src --threads:on -r -f stress-tests/stress_test.nim"
+
   if getEnv("SANITIZE_THREADS") != "no":
     # C (with thread sanitization)
     exec "nim c --cc:clang --mm:atomicArc --path:src --passC:\"-fsanitize=thread\" --passL:\"-fsanitize=thread\" --threads:on -r -f stress-tests/stress_test.nim"