SiddiqSoft.RWLContainer 1.4.4

RWLContainer : Reader-writer protected containers

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
• <shared_mutex> and <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 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.

Usage

• Use the nuget SiddiqSoft.RWLContainer
• Use CPM to integrate into your CMake project

Quick Example

#include "gtest/gtest.h"
#include "nlohmann/json.hpp"
#include "siddiqsoft/RWLContainer.hpp"

TEST(examples, Example1)
{
    try
    {
        siddiqsoft::RWLContainer<std::string, std::string> 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.
    }
}

<small align="right">

© 2021 Siddiq Software LLC. All rights reserved.

</small>