https://github.com/siddiqsoft/rwlcontainer
Small thread-safe read-writer locked container support class.
https://github.com/siddiqsoft/rwlcontainer
container cpp20 header-only-library nuget reader-writer threadsafe waitable-queue
Last synced: about 4 hours ago
JSON representation
Small thread-safe read-writer locked container support class.
- Host: GitHub
- URL: https://github.com/siddiqsoft/rwlcontainer
- Owner: SiddiqSoft
- License: bsd-3-clause
- Created: 2021-07-22T23:22:12.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2026-06-27T23:02:22.000Z (about 12 hours ago)
- Last Synced: 2026-06-27T23:19:23.058Z (about 12 hours ago)
- Topics: container, cpp20, header-only-library, nuget, reader-writer, threadsafe, waitable-queue
- Language: C++
- Homepage:
- Size: 172 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
RWLContainer : Reader-writer protected containers
-------------------------------------------
[](https://dev.azure.com/siddiqsoft/siddiqsoft/_build/latest?definitionId=8&branchName=main)
# Overview
This library provides convenient, production-ready wrappers around C++20 standard library synchronization primitives:
- **RWLContainer**: A reader-writer lock protected dictionary that wraps `std::unordered_map` with `std::shared_mutex` for safe concurrent access
- **WaitableQueue**: A thread-safe queue that augments `std::queue` with `std::shared_mutex` and `std::counting_semaphore` for efficient producer-consumer patterns
These classes eliminate boilerplate synchronization code and provide a simple, type-safe API for common concurrent programming scenarios.
## Requirements
- C++20 or later
- [``](https://en.cppreference.com/w/cpp/thread/shared_mutex) and [``](https://en.cppreference.com/w/cpp/thread/mutex) support
- CMake 3.20+
## Platform Support
Tested and built on:
- **Windows** (Visual Studio 2022)
- **Linux** (Fedora)
- **macOS**
All platforms are tested in the CI/CD pipeline with comprehensive test coverage.
## Testing
- Unit tests using Google Test (gtest)
- Code coverage reporting (Linux builds)
- Automated testing on all supported platforms via Azure Pipelines
- Stress testing included in test suite
### Known Test Behavior
**ConcurrentScanAndWrite Test**: This stress test exercises concurrent scanning and writing operations on the RWLContainer. Due to platform-specific differences in `std::shared_mutex` implementations:
- **Linux (x86_64 and ARM64)**: The test includes a timeout mechanism (100ms) to prevent potential deadlocks. The scan callback will exit early if it exceeds the timeout, allowing the test to complete successfully.
- **Windows (ARM64)** and **macOS**: The test runs without timeout restrictions and completes normally without deadlock issues.
This difference is due to variations in how different platforms implement reader-writer lock fairness and priority inversion handling. The timeout mechanism ensures the test remains robust across all platforms while still validating the thread-safety of concurrent operations.
**WaitUntilEmptyTightLoopContention Test**: This stress test for WaitableQueue exercises tight-loop contention between multiple threads calling `waitUntilEmpty()` while concurrent push/pop operations occur. Due to platform-specific differences in `std::shared_mutex` implementations:
- **Linux (x86_64 and ARM64)**: The test is skipped or may experience deadlocks due to lock fairness issues under extreme contention. The tight loop with minimal timeouts (1ms) can cause priority inversion on Linux's shared_mutex implementation.
- **Windows (ARM64)** and **macOS**: The test runs without issues and completes normally, demonstrating robust handling of concurrent wait and mutation operations.
This difference reflects variations in how different platforms prioritize reader vs. writer threads in shared_mutex implementations. The library's core functionality remains thread-safe on all platforms; this test specifically stresses an edge case that manifests differently across platforms.
## Versioning
Uses [GitVersion](https://gitversion.net/) for semantic versioning (`MAJOR.MINOR.PATCH`). Version is automatically determined from git history.
# API Documentation
For detailed API documentation, method signatures, and comprehensive examples, see [API.md](API.md).
# Usage
- Use the nuget [SiddiqSoft.RWLContainer](https://www.nuget.org/packages/SiddiqSoft.RWLContainer/)
- Use CPM to integrate into your CMake project
## Quick Example
```cpp
#include "gtest/gtest.h"
#include "nlohmann/json.hpp"
#include "siddiqsoft/RWLContainer.hpp"
TEST(examples, Example1)
{
try
{
siddiqsoft::RWLContainer myContainer;
auto item = myContainer.add("foo", "bar");
ASSERT_TRUE(item);
EXPECT_EQ("bar", *item);
}
catch (...)
{
EXPECT_TRUE(false); // if we throw then the test fails.
}
}
```
© 2021 Siddiq Software LLC. All rights reserved.