spsc: fix potential overflows

Thanks Jannic for the find: #652 (comment)

If N == usize::MAX, there is the possibility of a panic in len()
If N >= usize::MAX, then in the iterator code, self.index + self.head
could overflow

The operations are now slightly more complex and a bit slower, but thanks
to compiler optimization they don't introduce branches, only conditional
instructions (cmov, csel, it).

All added tests fail without the fix

Author: sgued

CHANGELOG.md

@@ -14,6 +14,8 @@ of panicking drop implementations.
 - Added `pop_front_if` and `pop_back_if` to `Deque`
 - Made `Vec::from_array` const.
 - Fixed long division being instroduced by the const-erasure in spsc
+- spsc: Fix integer overflow in iterators when N > usize::MAX/2 and the queue loops.
+- spsc: Fix integer overflow leading to a panic in `len` when N == usize::MAX and debug assertions are enabled.
 
 ## [v0.9.2] 2025-11-12
 

src/spsc.rs

@@ -176,7 +176,10 @@ impl<T, S: Storage> QueueInner<T, S> {
 
     #[inline]
     fn increment(&self, val: usize) -> usize {
-        let val = val + 1;
+        // We know that self.n() <= usize::MAX
+        // So this can only overflow if N == usize::MAX
+        // and in this case the overflow will be equivalent to the modulo N operation
+        let val = val.wrapping_add(1);
         if val >= self.n() {
             val - self.n()
         } else {
@@ -628,8 +631,11 @@ impl<'a, T> Iterator for Iter<'a, T> {
         if self.index < self.len {
             let head = self.rb.head.load(Ordering::Relaxed);
 
-            let i = head + self.index;
-            let i = if i >= self.rb.n() { i - self.rb.n() } else { i };
+            let i = match head.checked_add(self.index) {
+                Some(i) if i >= self.rb.n() => i - self.rb.n(),
+                Some(i) => i,
+                None => head.wrapping_add(self.index).wrapping_sub(self.rb.n()),
+            };
             self.index += 1;
 
             Some(unsafe { &*(self.rb.buffer.borrow().get_unchecked(i).get() as *const T) })
@@ -646,8 +652,11 @@ impl<'a, T> Iterator for IterMut<'a, T> {
         if self.index < self.len {
             let head = self.rb.head.load(Ordering::Relaxed);
 
-            let i = head + self.index;
-            let i = if i >= self.rb.n() { i - self.rb.n() } else { i };
+            let i = match head.checked_add(self.index) {
+                Some(i) if i >= self.rb.n() => i - self.rb.n(),
+                Some(i) => i,
+                None => head.wrapping_add(self.index).wrapping_sub(self.rb.n()),
+            };
             self.index += 1;
 
             Some(unsafe { &mut *self.rb.buffer.borrow().get_unchecked(i).get().cast::<T>() })
@@ -663,8 +672,11 @@ impl<T> DoubleEndedIterator for Iter<'_, T> {
             let head = self.rb.head.load(Ordering::Relaxed);
 
             // self.len > 0, since it's larger than self.index > 0
-            let i = head + self.len - 1;
-            let i = if i >= self.rb.n() { i - self.rb.n() } else { i };
+            let i = match head.checked_add(self.len - 1) {
+                Some(i) if i >= self.rb.n() => i - self.rb.n(),
+                Some(i) => i,
+                None => head.wrapping_add(self.len - 1).wrapping_sub(self.rb.n()),
+            };
             self.len -= 1;
             Some(unsafe { &*(self.rb.buffer.borrow().get_unchecked(i).get() as *const T) })
         } else {
@@ -678,6 +690,7 @@ impl<T> DoubleEndedIterator for IterMut<'_, T> {
         if self.index < self.len {
             let head = self.rb.head.load(Ordering::Relaxed);
 
+            // TODO: fix usize overflow
             // self.len > 0, since it's larger than self.index > 0
             let i = head + self.len - 1;
             let i = if i >= self.rb.n() { i - self.rb.n() } else { i };
@@ -888,7 +901,12 @@ impl<T> Producer<'_, T> {
 
 #[cfg(test)]
 mod tests {
-    use std::hash::{Hash, Hasher};
+    use std::{
+        cell::UnsafeCell,
+        hash::{Hash, Hasher},
+        mem::MaybeUninit,
+        sync::atomic::AtomicUsize,
+    };
 
     use super::{Consumer, Producer, Queue};
 
@@ -1310,4 +1328,65 @@ mod tests {
         };
         assert_eq!(hash1, hash2);
     }
+
+    // Test for some integer overflow bugs. See
+    // https://github.com/rust-embedded/heapless/pull/652#discussion_r3046630717
+    // for more info
+    #[test]
+    fn test_len_overflow() {
+        let mut queue = Queue::<(), { usize::MAX }> {
+            head: AtomicUsize::new(usize::MAX),
+            tail: AtomicUsize::new(2),
+            buffer: [const { UnsafeCell::new(MaybeUninit::new(())) }; usize::MAX],
+        };
+        queue.enqueue(()).unwrap();
+        queue.enqueue(()).unwrap();
+
+        let collected: Vec<_> = queue.iter().collect();
+        assert_eq!(&collected, &[&(); 4]);
+    }
+    #[test]
+    fn test_usize_overflow_iter() {
+        let queue = Queue::<(), { usize::MAX - 1 }> {
+            head: AtomicUsize::new(usize::MAX - 3),
+            tail: AtomicUsize::new(2),
+            buffer: [const { UnsafeCell::new(MaybeUninit::new(())) }; usize::MAX - 1],
+        };
+
+        let collected: Vec<_> = queue.iter().collect();
+        assert_eq!(&collected, &[&(); 4]);
+    }
+    #[test]
+    fn test_usize_overflow_iter_mut() {
+        let mut queue = Queue::<(), { usize::MAX - 1 }> {
+            head: AtomicUsize::new(usize::MAX - 3),
+            tail: AtomicUsize::new(2),
+            buffer: [const { UnsafeCell::new(MaybeUninit::new(())) }; usize::MAX - 1],
+        };
+
+        let collected: Vec<_> = queue.iter_mut().collect();
+        assert_eq!(&collected, &[&(); 4]);
+    }
+    #[test]
+    fn test_usize_overflow_iter_rev() {
+        let queue = Queue::<(), { usize::MAX - 1 }> {
+            head: AtomicUsize::new(usize::MAX - 3),
+            tail: AtomicUsize::new(2),
+            buffer: [const { UnsafeCell::new(MaybeUninit::new(())) }; usize::MAX - 1],
+        };
+
+        let collected: Vec<_> = queue.iter().rev().collect();
+        assert_eq!(&collected, &[&(); 4]);
+    }
+    #[test]
+    fn test_usize_overflow_iter_mut_rev() {
+        let mut queue = Queue::<(), { usize::MAX - 1 }> {
+            head: AtomicUsize::new(usize::MAX - 3),
+            tail: AtomicUsize::new(2),
+            buffer: [const { UnsafeCell::new(MaybeUninit::new(())) }; usize::MAX - 1],
+        };
+
+        let collected: Vec<_> = queue.iter_mut().rev().collect();
+        assert_eq!(&collected, &[&(); 4]);
+    }
 }