Improve README

kzhdev · kzhdev · commit b9aab8c513d7 · 2025-10-04T16:15:50.000-05:00
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,9 +1,13 @@
-# v1.0.2.2 - 2025-10-04
+# v1.1.0.0 - 2025-10-04
 - Fixed size calculation in shared memory mapping to use reserved_info struct
 - Added server-client shared memory test case
 - Added GitHub CI workflow for automated testing across Ubuntu, Windows, and macOS
 - Added CI status badge to README
 - Added CTest integration for automated test discovery
+- Added read() overload with atomic cursor for work-stealing/load-balancing patterns
+- Added work-stealing test cases for both in-process and shared memory modes
+- Enhanced README with work-stealing example and updated API documentation
+- Fixed MSBuild MSB8028 warnings for custom targets
 
 # v1.0.2.1 - 2025-10-01
 - Fixed buffer wrap read logic to properly retry from wrapped position
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.10)
 
-set(BUILD_VERSION 1.0.2.2)
+set(BUILD_VERSION 1.1.0.0)
 
 project(slick_queue
         VERSION ${BUILD_VERSION}
@@ -48,13 +48,25 @@ if(CMAKE_BUILD_TYPE STREQUAL "Release")
         VERBATIM
     )
 
+    if (MSVC)
+        set_target_properties(dist_slick_queue PROPERTIES
+            VS_GLOBAL_IntDir "$(Platform)\\$(Configuration)\\dist_slick_queue\\"
+        )
+    endif()
+
     if (PROJECT_IS_TOP_LEVEL)
         add_custom_target(package_slick_queue ALL
             COMMAND ${CMAKE_COMMAND} -E tar "cfv" "${CMAKE_BINARY_DIR}/dist/slick_queue_${BUILD_VERSION}.zip" --format=zip "${CMAKE_CURRENT_SOURCE_DIR}/include"
             WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
             COMMENT "Creating zip archive"
         )
         add_dependencies(package_slick_queue dist_slick_queue)
+
+        if (MSVC)
+            set_target_properties(package_slick_queue PROPERTIES
+                VS_GLOBAL_IntDir "$(Platform)\\$(Configuration)\\package_slick_queue\\"
+            )
+        endif()
     endif()
 endif()
 
diff --git a/README.md b/README.md
@@ -9,39 +9,223 @@ over shared memory for inter-process communication.
 
 ## Features
 
-- Lock-free operations for multiple producers and consumers
-- Header-only implementation
-- Optional shared-memory mode
-- No dynamic allocation on the hot path
+- **Lock-free operations** for multiple producers and consumers
+- **Header-only implementation** - just include and go
+- **Zero dynamic allocation** on the hot path for predictable performance
+- **Shared memory support** for inter-process communication
+- **Cross-platform** - supports Windows, Linux, and macOS
+- **Modern C++20** implementation
 
-## Getting Started
+## Requirements
 
-Simply add the `include` directory to your project's include path and include
-the header:
+- C++20 compatible compiler
+- CMake 3.10+ (for building tests)
+
+## Installation
+
+SlickQueue is header-only. Simply add the `include` directory to your project's include path:
 
 ```cpp
-#include "slick_queue.h"
+#include "slick_queue/slick_queue.h"
+```
+
+### Using CMake
 
+```cmake
+include(FetchContent)
+
+# Disable tests for slick_queue
+set(BUILD_SLICK_QUEUE_TESTS OFF CACHE BOOL "" FORCE)
+FetchContent_Declare(
+    slick_queue
+    GIT_REPOSITORY https://github.com/SlickQuant/slick_queue.git
+    GIT_TAG v1.0.2.1
+)
+FetchContent_MakeAvailable(slick_queue)
+
+target_link_libraries(your_target PRIVATE slick_queue)
+```
+
+## Usage
+
+### Basic Example
+
+```cpp
+#include "slick_queue/slick_queue.h"
+
+// Create a queue with 1024 slots (must be power of 2)
 slick::SlickQueue<int> queue(1024);
+
+// Producer: reserve a slot, write data, and publish
 auto slot = queue.reserve();
 *queue[slot] = 42;
 queue.publish(slot);
 
+// Consumer: read from queue using a cursor
 uint64_t cursor = 0;
 auto result = queue.read(cursor);
+if (result.first != nullptr) {
+    int value = *result.first;  // value == 42
+}
+```
+
+### Shared Memory Example (IPC)
+
+```cpp
+#include "slick_queue/slick_queue.h"
+
+// Process 1 (Server/Writer)
+slick::SlickQueue<int> server(1024, "my_queue");
+auto slot = server.reserve();
+*server[slot] = 100;
+server.publish(slot);
+
+// Process 2 (Client/Reader)
+slick::SlickQueue<int> client("my_queue");
+uint64_t cursor = 0;
+auto result = client.read(cursor);
+if (result.first != nullptr) {
+    int value = *result.first;  // value == 100
+}
+```
+
+### Multi-Producer Multi-Consumer
+
+```cpp
+#include "slick_queue/slick_queue.h"
+#include <thread>
+
+slick::SlickQueue<int> queue(1024);
+
+// Multiple producers
+auto producer = [&](int id) {
+    for (int i = 0; i < 100; ++i) {
+        auto slot = queue.reserve();
+        *queue[slot] = id * 1000 + i;
+        queue.publish(slot);
+    }
+};
+
+// Multiple consumers (each maintains independent cursor)
+// Note: Each consumer will see ALL published items (broadcast pattern)
+auto consumer = [&](int id) {
+    uint64_t cursor = 0;
+    int count = 0;
+    while (count < 200) {  // 2 producers × 100 items each
+        auto result = queue.read(cursor);
+        if (result.first != nullptr) {
+            int value = *result.first;
+            ++count;
+        }
+    }
+};
+
+std::thread p1(producer, 1);
+std::thread p2(producer, 2);
+std::thread c1(consumer, 1);
+std::thread c2(consumer, 2);
+
+p1.join(); p2.join();
+c1.join(); c2.join();
 ```
 
-## Building Tests
+### Work-Stealing with Shared Atomic Cursor
+
+```cpp
+#include "slick_queue/slick_queue.h"
+#include <thread>
+#include <atomic>
+
+slick::SlickQueue<int> queue(1024);
+std::atomic<uint64_t> shared_cursor{0};
+
+// Multiple producers
+auto producer = [&](int id) {
+    for (int i = 0; i < 100; ++i) {
+        auto slot = queue.reserve();
+        *queue[slot] = id * 1000 + i;
+        queue.publish(slot);
+    }
+};
+
+// Multiple consumers sharing atomic cursor (work-stealing/load-balancing)
+// Each item is consumed by exactly ONE consumer
+auto consumer = [&]() {
+    int count = 0;
+    for (int i = 0; i < 100; ++i) {
+        auto result = queue.read(shared_cursor);
+        if (result.first != nullptr) {
+            int value = *result.first;
+            ++count;
+        }
+    }
+    return count;
+};
+
+std::thread p1(producer, 1);
+std::thread p2(producer, 2);
+std::thread c1(consumer);
+std::thread c2(consumer);
+
+p1.join(); p2.join();
+c1.join(); c2.join();
+// Total items consumed: 200 (each item consumed exactly once)
+```
+
+## API Overview
+
+### Constructor
+
+```cpp
+// In-process queue
+SlickQueue(uint32_t size);
+
+// Shared memory queue
+SlickQueue(uint32_t size, const char* shm_name);  // Writer/Creator
+SlickQueue(const char* shm_name);                  // Reader/Attacher
+```
 
-A small test suite is provided using CMake and Catch. Build and run the tests
-with:
+### Core Methods
+
+- `uint64_t reserve()` - Reserve a slot for writing (blocks if queue is full)
+- `T* operator[](uint64_t slot)` - Access reserved slot
+- `void publish(uint64_t slot)` - Publish written data to consumers
+- `std::pair<T*, uint32_t> read(uint64_t& cursor)` - Read next available item (independent cursor)
+- `std::pair<T*, uint32_t> read(std::atomic<uint64_t>& cursor)` - Read next available item (shared atomic cursor for work-stealing)
+- `uint32_t size()` - Get queue capacity
+
+## Performance Characteristics
+
+- **Lock-free**: No mutex contention between producers/consumers
+- **Wait-free reads**: Consumers never block each other
+- **Cache-friendly**: Ring buffer design with power-of-2 sizing
+- **Predictable**: No allocations or system calls on hot path (except for initial reserve when full)
+
+## Building and Testing
+
+### Build Tests
 
 ```bash
 cmake -S . -B build
-cmake --build build --target slick_queue_tests
+cmake --build build
+```
+
+### Run Tests
+
+```bash
+# Using CTest
+cd build
+ctest --output-on-failure
+
+# Or run directly
 ./build/tests/slick_queue_tests
 ```
 
+### Build Options
+
+- `BUILD_SLICK_QUEUE_TESTS` - Enable/disable test building (default: ON)
+- `CMAKE_BUILD_TYPE` - Set to `Release` or `Debug`
+
 ## License
 
 SlickQueue is released under the [MIT License](LICENSE).
diff --git a/include/slick_queue/slick_queue.h b/include/slick_queue/slick_queue.h
@@ -276,6 +276,47 @@ class SlickQueue {
         return std::make_pair(&data, current_slot->size);
     }
 
+    /**
+     * @brief Read data from the queue using a shared atomic cursor
+     * @param read_index Reference to the atomic reading index, will be atomically updated after reading
+     * @return Pair of pointer to the data and the size of the data, or nullptr and 0 if no data is available
+     *
+     * This overload allows multiple consumers to share a single atomic cursor for load-balancing/work-stealing patterns.
+     * Each consumer atomically claims the next item to process.
+     */
+    std::pair<T*, uint32_t> read(std::atomic<uint64_t>& read_index) noexcept {
+        while (true) {
+            uint64_t current_index = read_index.load(std::memory_order_acquire);
+            auto idx = current_index & mask_;
+            slot* current_slot = &control_[idx];
+            uint64_t index = current_slot->data_index.load(std::memory_order_acquire);
+
+            if (index != std::numeric_limits<uint64_t>::max() && reserved_->load(std::memory_order_relaxed).index_ < index) [[unlikely]] {
+                // queue has been reset
+                read_index.store(0, std::memory_order_release);
+                continue;
+            }
+
+            if (index == std::numeric_limits<uint64_t>::max() || index < current_index) {
+                // data not ready yet
+                return std::make_pair(nullptr, 0);
+            }
+            else if (index > current_index && ((index & mask_) != idx)) {
+                // queue wrapped, skip the unused slots
+                read_index.compare_exchange_weak(current_index, index, std::memory_order_release, std::memory_order_relaxed);
+                continue;
+            }
+
+            // Try to atomically claim this item
+            uint64_t next_index = index + current_slot->size;
+            if (read_index.compare_exchange_weak(current_index, next_index, std::memory_order_release, std::memory_order_relaxed)) {
+                // Successfully claimed the item
+                return std::make_pair(&data_[current_index & mask_], current_slot->size);
+            }
+            // CAS failed, another consumer claimed it, retry
+        }
+    }
+
     /**
     * @brief Read the last published data in the queue
     * @return Pointer to the last published data, or nullptr if no data is available
diff --git a/tests/shm_tests.cpp b/tests/shm_tests.cpp
@@ -1,6 +1,7 @@
 #define CATCH_CONFIG_NO_POSIX_SIGNALS
 #include "catch.hh"
 #include <slick_queue/slick_queue.h>
+#include <thread>
 
 using namespace slick;
 
@@ -107,3 +108,45 @@ TEST_CASE( "Server Client - shm" ) {
   REQUIRE(read_cursor == 3);
   REQUIRE(*read.first == 23);
 }
+
+TEST_CASE( "Atomic cursor - shared memory work-stealing" ) {
+  SlickQueue<int> server(1024, "sq_atomic_cursor_shm");
+  SlickQueue<int> client1("sq_atomic_cursor_shm");
+  SlickQueue<int> client2("sq_atomic_cursor_shm");
+
+  std::atomic<uint64_t> shared_cursor{0};
+  std::atomic<int> total_consumed{0};
+
+  // Server: publish 100 items
+  std::thread producer([&]() {
+    for (int i = 0; i < 100; ++i) {
+      auto slot = server.reserve();
+      *server[slot] = i;
+      server.publish(slot);
+    }
+  });
+
+  // Multiple clients sharing atomic cursor via shared memory
+  auto consumer = [&](SlickQueue<int>& client) {
+    int local_count = 0;
+    while (total_consumed.load() < 100) {
+      auto result = client.read(shared_cursor);
+      if (result.first != nullptr) {
+        local_count++;
+        total_consumed.fetch_add(1);
+      }
+    }
+    return local_count;
+  };
+
+  std::thread c1([&]() { consumer(client1); });
+  std::thread c2([&]() { consumer(client2); });
+
+  producer.join();
+  c1.join();
+  c2.join();
+
+  // Verify all 100 items were consumed exactly once
+  REQUIRE(total_consumed.load() == 100);
+  REQUIRE(shared_cursor.load() == 100);
+}
diff --git a/tests/tests.cpp b/tests/tests.cpp
