chore: added tests and FAQ in readme, also added macOS to test scenario

Author: kyr0

.github/workflows/build_and_test.yml

@@ -10,12 +10,15 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, windows-latest]
+        os: [ubuntu-latest, macos-latest, windows-latest]
         build_type: [Release]
         include:
           - os: ubuntu-latest
             cc: gcc
             cxx: g++
+          - os: macos-latest
+            cc: clang
+            cxx: clang++
           - os: windows-latest
             cc: cl
             cxx: cl
@@ -35,6 +38,8 @@ jobs:
 
       - name: Test
         run: cmake --build build --config Release --target run_test
+        env:
+          LSM_NOFLAKE: 1
 
   release:
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -10,8 +10,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Makefile with `build`, `test`, `clean`, and `setup` targets wrapping CMake
 - Re-verified current macOS aarch64 (Apple Silicon) support on Sequoia 15.7.3
-- 6 new test cases: `Memory` accessors, `getWriteFlags` logic, `std::span` write overloads, segment overwrite, queue capacity=1 edge case, `maxMessageSize` boundary
+- New test case on `Memory` accessors, `getWriteFlags` logic, `std::span` write overloads, segment overwrite, queue capacity=1 edge case, `maxMessageSize` boundary and concurrent writing; also added docs to understand the tests better
 - `.vscode/c_cpp_properties.json` for C++20 IntelliSense on macOS (arm64/aarch64)
+- No-flake stability test: re-runs the full suite 1000 times as subprocesses to catch timing-dependent failures (cross-platform, skips itself via `LSM_NOFLAKE` env var)
+- Added `macos-latest` to GitHub Actions CI matrix with `LSM_NOFLAKE=1` to skip the 1000-iteration flake test in CI
 
 ### Changed
 - Improved README: added supported platforms table, building instructions, tightened examples and documentation

README.md

@@ -1,6 +1,6 @@
 # libsharedmemory
 
-A lightweight, header-only C++20 library for inter-process communication via shared memory. Transfer data between isolated OS processes — or between modules written in different programming languages — with a simple, cross-platform API.
+A lightweight, header-only C++20 library for inter-process communication via shared memory. Transfer data between isolated OS processes - or between modules written in different programming languages - with a simple, cross-platform API.
 
 **Key capabilities:**
 - Stream-based read/write transfer (`std::string`, `float*`, `double*`, scalars)
@@ -51,7 +51,7 @@ writer.write(data);
 std::string result = reader.readString();
 ```
 
-### Message Queue
+### Message Queue (C++20)
 
 ```cpp
 SharedMemoryQueue writer{"queue", /*capacity*/ 10, /*maxMessageSize*/ 256, /*persistent*/ true, /*isWriter*/ true};
@@ -88,7 +88,7 @@ std::cout << "Size: " << reader.size() << ", Empty: " << reader.isEmpty() << std
 
 ## Installation
 
-Copy `include/libsharedmemory/libsharedmemory.hpp` into your project's include path — it's a single header.
+Copy `include/libsharedmemory/libsharedmemory.hpp` into your project's include path - it's a single header.
 
 Alternatively, use `npm` for dependency management:
 
@@ -121,11 +121,24 @@ enum DataType {
 
 `kMemoryChanged` flips odd/even to signal data changes, allowing continuous readers to detect every update.
 
-## Limits
+## Limits and Frequently Asked Questions
+
+### Can I use this for cross-platform network communication?
+
+No. **Endianness** is not handled. This is fine for local shared memory but requires attention if copying buffers to a network protocol.
+
+### What about cross compiler compatibility?
+
+**Cross-compiler** behavior for the binary memory layout is undefined. The library is designed for C++20 compliant compilers on the same platform. For cross-compiler or cross-language interoperability, you must ensure consistent data type sizes, alignment, and endianness.
+
+### Can I use this with multiple writers?
+
+Maybe for slow writers, **if you are lucky**.
+**Concurrent writers**(`SharedMemoryWriteStream`) are currently not safely supported. `write()` performs 3 non-atomic `memcpy` calls (flags, size, data). Two threads writing to the same segment can interleave these operations, producing torn reads with mixed content or incorrect sizes. Use a single writer per segment or add external synchronization.
+
+### Are multiple producers supported for `SharedMemoryQueue`?
 
-- **Endianness** is not handled. This is fine for local shared memory but requires attention if copying buffers to a network protocol.
-- **Cross-compiler** behavior for the binary memory layout is undefined.
-- **SharedMemoryQueue** works best with a single producer. Multiple concurrent producers require external synchronization.
+Not yet. `enqueue()` uses a non-atomic read-modify-write on the write index. Two threads calling `enqueue()` on the same queue will read the same slot index, overwrite each other's data, and advance the index only once - causing **message corruption** in testing (up to 45% on macOS 15.7, aarch64, Macbook Air M4, 1000 messages, 2 producers). Use a single producer per queue or add a mutex around `enqueue()`.
 
 ## Roadmap
 
@@ -134,4 +147,4 @@ enum DataType {
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT - see [LICENSE](LICENSE).