Range-Based API

joz-k · joz-k · commit 487827f9ce54 · 2025-08-18T17:54:44.000+02:00
diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
@@ -13,3 +13,8 @@ add_executable(advanced_usage advanced_usage.cpp)
 # Link the example to our queue library and the threading library.
 target_link_libraries(advanced_usage PRIVATE spsc_queue Threads::Threads)
 
+# --- Example for Ranges API ---
+add_executable(ranges_example ranges_example.cpp)
+
+target_link_libraries(ranges_example PRIVATE spsc_queue Threads::Threads)
+
diff --git a/examples/README.md b/examples/README.md
@@ -181,3 +181,73 @@ void low_level_batch_consumer(LockFreeSpscQueue<Message>& queue)
     // The read is automatically committed when `read_scope` is destroyed.
 }
 ```
+
+## 4. Range-Based API (`std::ranges`)
+
+For maximum convenience and compatibility with modern C++ algorithms, both the `WriteScope` and `ReadScope` objects are fully compliant with the C++20 `std::ranges` library. This allows for direct, elegant iteration, completely abstracting away the two-block nature of the circular buffer.
+
+### Writing with a Range-Based `for` Loop
+
+This is a clear and idiomatic way to fill the reserved slots in a write transaction.
+
+```cpp
+void range_based_producer(LockFreeSpscQueue<int>& queue)
+{
+    // Ask to reserve space for 10 items.
+    if (auto write_scope = queue.prepare_write(10)) {
+        // The WriteScope object is directly iterable.
+        // We can iterate over the empty slots and write to them.
+        int i = 0;
+        for (int& slot : write_scope) {
+            slot = i++;
+        }
+    }
+    // The write is automatically committed when `write_scope` is destroyed.
+}
+```
+
+### Reading with a Range-Based `for` Loop
+
+This is the simplest way to consume data from the queue. The custom iterator handles the jump between the two memory blocks transparently.
+
+```cpp
+void range_based_consumer(LockFreeSpscQueue<int>& queue)
+{
+    // Ask to read up to 16 items at a time.
+    if (auto read_scope = queue.prepare_read(16))
+    {
+        // The ReadScope object is a C++20 range.
+        // The for loop will seamlessly iterate over block1 and then block2.
+        for (const int& item : read_scope)
+        {
+            std::cout << "Consumer: Got " << item << "\n";
+        }
+    }
+    // The read is automatically committed when `read_scope` is destroyed.
+}
+```
+
+### Using with `std::ranges` Algorithms
+
+Because the `Scope` objects are proper ranges, you can use them with the powerful algorithms from the `<algorithm>` and `<numeric>` headers.
+
+```cpp
+#include <numeric>   // For std::accumulate
+#include <algorithm> // For std::ranges::copy
+
+void algorithm_example(LockFreeSpscQueue<int>& queue)
+{
+    // Use std::ranges::copy to fill a write scope from another container.
+    if (auto write_scope = queue.prepare_write(10)) {
+        std::vector<int> source_data(write_scope.get_items_written(), 42); // Fill with 42s
+        std::ranges::copy(source_data, write_scope.begin());
+    }
+
+    // Use std::accumulate to sum all the items in a read scope.
+    if (auto read_scope = queue.prepare_read(10)) {
+        long long sum = std::accumulate(read_scope.begin(), read_scope.end(), 0LL);
+        std::cout << "Sum of items in queue: " << sum << "\n";
+    }
+}
+```
+
diff --git a/examples/ranges_example.cpp b/examples/ranges_example.cpp
@@ -0,0 +1,111 @@
+#include "LockFreeSpscQueue.h"
+
+#include <iostream>
+#include <vector>
+#include <thread>
+#include <atomic>
+#include <chrono>
+#include <numeric>   // For std::iota
+#include <algorithm> // For std::ranges::copy
+
+// This example demonstrates the `std::ranges` integration of the WriteScope
+// and ReadScope objects. It shows how to use modern, idiomatic C++ to interact
+// with the queue, abstracting away the underlying two-block nature of the
+// circular buffer.
+
+// --- Producer Thread ---
+void producer_thread(LockFreeSpscQueue<int>& queue)
+{
+    std::cout << "Producer: Starting...\n";
+
+    // --- Method 1: Writing with a range-based for loop ---
+    std::cout << "Producer: Preparing to write items 0-9 using a for loop...\n";
+    while (true) {
+        auto write_scope = queue.prepare_write(10);
+        // Check if the scope is valid by checking the number of items.
+        if (write_scope.get_items_written() > 0)
+        {
+            int i = 0;
+            for (int& slot : write_scope) {
+                slot = i++;
+            }
+            std::cout << "Producer:   Wrote " << write_scope.get_items_written() << " items.\n";
+            break;
+        }
+        std::this_thread::yield();
+    }
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(200));
+
+    // --- Method 2: Batch Writing with a std::ranges algorithm ---
+    std::cout << "Producer: Preparing to write items 100-115 using std::ranges::copy...\n";
+    std::vector<int> source_data(16);
+    std::iota(source_data.begin(), source_data.end(), 100);
+
+    size_t total_written = 0;
+    while (total_written < source_data.size())
+    {
+        auto write_scope = queue.prepare_write(source_data.size() - total_written);
+        // Check if the scope is valid.
+        if (write_scope.get_items_written() > 0)
+        {
+            const size_t can_write_count = write_scope.get_items_written();
+            std::span<const int> source_sub_batch(source_data.data() + total_written,
+                                                  can_write_count);
+            std::ranges::copy(source_sub_batch, write_scope.begin());
+            total_written += can_write_count;
+            std::cout << "Producer:   Copied " << can_write_count << " items. ("
+                      << total_written << "/" << source_data.size() << " total)\n";
+        }
+        else {
+            std::this_thread::yield();
+        }
+    }
+
+    std::cout << "Producer: Finished.\n";
+}
+
+// --- Consumer Thread ---
+void consumer_thread(LockFreeSpscQueue<int>& queue, std::atomic<bool>& producer_is_done)
+{
+    std::cout << "Consumer: Waiting for items...\n";
+    while (true)
+    {
+        auto read_scope = queue.prepare_read(32);
+        // Check if the scope is valid.
+        if (read_scope.get_items_read() > 0)
+        {
+            std::cout << "Consumer: Reading a batch of " << read_scope.get_items_read() << " items...\n";
+            for (const int& item : read_scope) {
+                std::cout << "Consumer:   Got " << item << "\n";
+            }
+        }
+        else
+        {
+            if (producer_is_done.load(std::memory_order_acquire)) {
+                if (queue.get_num_items_ready() == 0) {
+                    break;
+                }
+            } else {
+                std::this_thread::sleep_for(std::chrono::milliseconds(10));
+            }
+        }
+    }
+    std::cout << "Consumer: Finished.\n";
+}
+
+
+int main()
+{
+    const size_t QUEUE_CAPACITY = 128;
+    std::vector<int> shared_data_buffer(QUEUE_CAPACITY);
+    LockFreeSpscQueue<int> queue(shared_data_buffer);
+    std::atomic<bool> producer_is_done = false;
+
+    std::jthread producer(producer_thread, std::ref(queue));
+    std::jthread consumer(consumer_thread, std::ref(queue), std::ref(producer_is_done));
+
+    producer.join();
+    producer_is_done.store(true, std::memory_order_release);
+}
+
diff --git a/include/LockFreeSpscQueue.h b/include/LockFreeSpscQueue.h
@@ -62,13 +62,81 @@ class LockFreeSpscQueue
      * @brief An RAII scope object representing a prepared write operation.
      * @details Provides direct `std::span` access to the writable blocks in the
      *          underlying buffer. The transaction is committed when this object
-     *          is destroyed. It is move-only.
+     *          is destroyed. This object also satisfies the `std::ranges::range`
+     *          concept, allowing for direct iteration over the writable slots.
+     *          It is move-only.
      * @warning The user MUST write a number of items exactly equal to the value
      *          returned by `get_items_written()`. Failure to do so will result
      *          in the consumer reading uninitialized/garbage data.
      */
     struct WriteScope
     {
+        // --- Custom Iterator for WriteScope ---
+        class iterator
+        {
+        public:
+            using iterator_category = std::forward_iterator_tag;
+            using value_type        = T;
+            using difference_type   = std::ptrdiff_t;
+            using pointer           = T*;
+            using reference         = T&;
+            using SpanIterator      = typename std::span<T>::iterator;
+
+            iterator() = default;
+            reference operator*() const { return *m_current_iter; }
+            pointer operator->() const { return &(*m_current_iter); }
+
+            iterator& operator++() {
+                ++m_current_iter;
+                if (m_in_block1 && m_current_iter == m_block1_end) {
+                    m_current_iter = m_block2_begin;
+                    m_in_block1 = false;
+                }
+                return *this;
+            }
+            iterator operator++(int) { iterator tmp = *this; ++(*this); return tmp; }
+            bool operator==(const iterator& other) const = default;
+
+        private:
+            friend struct WriteScope;
+            iterator(SpanIterator b1_begin, SpanIterator b1_end,
+                     SpanIterator b2_begin, SpanIterator b2_end,
+                     bool is_begin)
+                : m_block1_end(b1_end), m_block2_begin(b2_begin), m_block2_end(b2_end)
+            {
+                if (is_begin) {
+                    if (b1_begin != b1_end) { // If block1 is not empty, start there.
+                        m_current_iter = b1_begin;
+                        m_in_block1    = true;
+                    } else { // Otherwise, start at block2.
+                        m_current_iter = b2_begin;
+                        m_in_block1    = false;
+                    }
+                } else { // This is the end() sentinel iterator.
+                    m_current_iter = m_block2_end; // The end is always the end of block2.
+                    m_in_block1    = false;
+                }
+            }
+
+            SpanIterator m_current_iter;
+            SpanIterator m_block1_end;
+            SpanIterator m_block2_begin;
+            SpanIterator m_block2_end;
+            bool m_in_block1 = false;
+        };
+
+        // --- Making WriteScope a C++20 Range ---
+        [[nodiscard]] iterator begin() {
+            auto b1 = get_block1();
+            auto b2 = get_block2();
+            return iterator(b1.begin(), b1.end(), b2.begin(), b2.end(), true);
+        }
+        [[nodiscard]] iterator end() {
+            auto b1 = get_block1();
+            auto b2 = get_block2();
+            return iterator(b1.begin(), b1.end(), b2.begin(), b2.end(), false);
+        }
+
         /** @brief Returns a span representing the first contiguous block to write to. */
         [[nodiscard]] std::span<T> get_block1() const
         {
@@ -103,9 +171,9 @@ class LockFreeSpscQueue
         WriteScope& operator=(const WriteScope&) = delete;
 
         WriteScope(WriteScope&& other) noexcept
-            : start_index1(other.start_index1), block_size1(other.block_size1),
-              start_index2(other.start_index2), block_size2(other.block_size2),
-              m_owner_queue(other.m_owner_queue)
+            : start_index1(other.start_index1), block_size1(other.block_size1)
+            , start_index2(other.start_index2), block_size2(other.block_size2)
+            , m_owner_queue(other.m_owner_queue)
         { other.m_owner_queue = nullptr; }
 
         // Move assignment is deleted. It is not possible to assign to the const members,
@@ -131,13 +199,80 @@ class LockFreeSpscQueue
      * @brief An RAII scope object representing a prepared read operation.
      * @details Provides direct `std::span` access to the readable blocks in the
      *          underlying buffer. The transaction is committed when this object
-     *          is destroyed. It is move-only.
+     *          is destroyed. This object also satisfies the `std::ranges::range`
+     *          concept, allowing direct iteration. It is move-only.
      * @warning The user MUST treat all data within the returned spans as read.
      *          The full `get_items_read()` amount will be committed, advancing
      *          the read pointer and making the space available for future writes.
      */
     struct ReadScope
     {
+        // --- Custom Iterator for ReadScope ---
+        class iterator
+        {
+        public:
+            using iterator_category = std::forward_iterator_tag;
+            using value_type        = const T;
+            using difference_type   = std::ptrdiff_t;
+            using pointer           = const T*;
+            using reference         = const T&;
+            using SpanConstIterator = typename std::span<const T>::iterator;
+
+            iterator() = default;
+            reference operator*() const { return *m_current_iter; }
+            pointer operator->() const { return &(*m_current_iter); }
+
+            iterator& operator++() {
+                ++m_current_iter;
+                if (m_in_block1 && m_current_iter == m_block1_end) {
+                    m_current_iter = m_block2_begin;
+                    m_in_block1    = false;
+                }
+                return *this;
+            }
+            iterator operator++(int) { iterator tmp = *this; ++(*this); return tmp; }
+            bool operator==(const iterator& other) const = default;
+
+        private:
+            friend struct ReadScope;
+            iterator(SpanConstIterator b1_begin, SpanConstIterator b1_end,
+                     SpanConstIterator b2_begin, SpanConstIterator b2_end,
+                     bool is_begin)
+                : m_block1_end(b1_end), m_block2_begin(b2_begin), m_block2_end(b2_end)
+            {
+                if (is_begin) {
+                    if (b1_begin != b1_end) {
+                        m_current_iter = b1_begin;
+                        m_in_block1    = true;
+                    } else {
+                        m_current_iter = b2_begin;
+                        m_in_block1    = false;
+                    }
+                } else {
+                    m_current_iter = m_block2_end;
+                    m_in_block1    = false;
+                }
+            }
+
+            SpanConstIterator m_current_iter;
+            SpanConstIterator m_block1_end;
+            SpanConstIterator m_block2_begin;
+            SpanConstIterator m_block2_end;
+            bool m_in_block1 = false;
+        };
+
+        // --- Making ReadScope a C++20 Range ---
+        [[nodiscard]] iterator begin() const {
+            auto b1 = get_block1();
+            auto b2 = get_block2();
+            return iterator(b1.begin(), b1.end(), b2.begin(), b2.end(), true);
+        }
+        [[nodiscard]] iterator end() const {
+            auto b1 = get_block1();
+            auto b2 = get_block2();
+            return iterator(b1.begin(), b1.end(), b2.begin(), b2.end(), false);
+        }
+
         /** @brief Returns a span representing the first contiguous block to read from. */
         [[nodiscard]] std::span<const T> get_block1() const
         {
