Enhance ReaderWriterLock with detailed documentation and add support for non-blocking write lock acquisition

Author: JunaMeinhold

CMakeLists.txt

@@ -22,10 +22,12 @@ target_include_directories(${PROJECT_NAME}
     PUBLIC 
         $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
         $<INSTALL_INTERFACE:include>
-    PRIVATE
-        ${OPENSSL_INCLUDE_DIR}
 )
 
+if (BUILD_SHARED_LIBS)
+    target_compile_definitions(${PROJECT_NAME} PUBLIC HEXA_UTILS_BUILD_SHARED=1)
+endif()
+
 install(TARGETS ${PROJECT_NAME}
         EXPORT ${PROJECT_NAME}Config
         ARCHIVE DESTINATION lib

README.md

@@ -0,0 +1,56 @@
+# Hexa.NET.Utilities.Native
+
+The native C/C++ side of [Hexa.NET.Utilities](https://github.com/HexaEngine/Hexa.NET.Utilities), providing low-level synchronization primitives with a C-compatible API for P/Invoke interop from .NET.
+
+## Features
+
+- **ReaderWriterLock** — A high-performance, lock-free reader-writer lock built on C++20 atomics with:
+  - Multiple concurrent readers
+  - Exclusive writer access
+  - Writer fairness (writers are not starved by incoming readers)
+  - Try-lock variants for non-blocking acquisition
+  - C-compatible ABI for use from C or via P/Invoke
+
+## Requirements
+
+- CMake 3.20 or later
+- A C++20-capable compiler (GCC, Clang, or MSVC)
+- C99 compiler support
+
+## Building
+
+```bash
+cmake -B build -DBUILD_SHARED_LIBS=ON
+cmake --build build
+```
+
+To build as a static library:
+
+```bash
+cmake -B build -DBUILD_SHARED_LIBS=OFF
+cmake --build build
+```
+
+## Installation
+
+```bash
+cmake --install build
+```
+
+This installs the library to `lib/` and headers to `include/`.
+
+## Project Structure
+
+```
+include/
+  common.h           — Export macros and calling convention definitions
+  ReaderWriterLock.h — ReaderWriterLock C API
+  utils.h            — Umbrella header (includes all public headers)
+src/
+  ReaderWriterLock.cpp — C++20 atomic-based implementation
+CMakeLists.txt
+```
+
+## License
+
+MIT License — Copyright (c) 2024 Juna Meinhold. See [LICENSE.txt](LICENSE.txt) for details.

include/ReaderWriterLock.h

@@ -5,18 +5,75 @@
 #include <stdio.h>
 
 
+/**
+ * @brief A lock-free reader-writer lock.
+ *
+ * Allows multiple concurrent readers or a single exclusive writer.
+ * Writers are given fairness: once a writer is waiting, new readers
+ * will block until the writer has acquired and released the lock.
+ *
+ * Must be initialized with ReaderWriterLock_Init() before use.
+ */
 typedef struct ReaderWriterLock_t
 {
     size_t storage;
 } ReaderWriterLock;
 
 
+/**
+ * @brief Initializes a ReaderWriterLock.
+ * @param cLock Pointer to the lock to initialize.
+ */
 HEXA_UTILS_API(void) ReaderWriterLock_Init(ReaderWriterLock* cLock);
+
+/**
+ * @brief Acquires a read lock, blocking until it is available.
+ *
+ * Blocks if a writer currently holds or is waiting for the lock.
+ *
+ * @param cLock Pointer to the lock.
+ * @return 1 on success, -1 if the reader count would overflow.
+ */
 HEXA_UTILS_API(int) ReaderWriterLock_LockRead(ReaderWriterLock* cLock);
+
+/**
+ * @brief Attempts to acquire a read lock without blocking.
+ *
+ * @param cLock Pointer to the lock.
+ * @return 1 if the read lock was acquired, 0 if a writer holds or is waiting
+ *         for the lock, -1 if the reader count would overflow.
+ */
 HEXA_UTILS_API(int) ReaderWriterLock_TryLockRead(ReaderWriterLock* cLock);
+
+/**
+ * @brief Releases a previously acquired read lock.
+ * @param cLock Pointer to the lock.
+ */
 HEXA_UTILS_API(void) ReaderWriterLock_UnlockRead(ReaderWriterLock* cLock);
+
+/**
+ * @brief Acquires a write lock, blocking until all readers and other writers
+ *        have released the lock.
+ * @param cLock Pointer to the lock.
+ */
 HEXA_UTILS_API(void) ReaderWriterLock_LockWrite(ReaderWriterLock* cLock);
-HEXA_UTILS_API(int) ReaderWriterLock_TryLockWrite(ReaderWriterLock* cLock);
+
+/**
+ * @brief Attempts to acquire a write lock without blocking.
+ *
+ * @param cLock Pointer to the lock.
+ * @param preserveWriterFairness If true, the call blocks until all active
+ *        readers drain before returning success, preventing writer starvation.
+ *        If false, the call returns 0 immediately when readers are active.
+ * @return 1 if the write lock was acquired, 0 if another writer already holds
+ *         the lock (or readers are active and @p preserveWriterFairness is false).
+ */
+HEXA_UTILS_API(int) ReaderWriterLock_TryLockWrite(ReaderWriterLock* cLock, bool preserveWriterFairness);
+
+/**
+ * @brief Releases a previously acquired write lock.
+ * @param cLock Pointer to the lock.
+ */
 HEXA_UTILS_API(void) ReaderWriterLock_UnlockWrite(ReaderWriterLock* cLock);
 
 #endif

src/ReaderWriterLock.cpp

@@ -156,10 +156,10 @@ HEXA_UTILS_API_INTERNAL(void) ReaderWriterLock_LockWrite(ReaderWriterLock* cLock
     lock->LockWrite();
 }
 
-HEXA_UTILS_API_INTERNAL(int) ReaderWriterLock_TryLockWrite(ReaderWriterLock* cLock)
+HEXA_UTILS_API_INTERNAL(int) ReaderWriterLock_TryLockWrite(ReaderWriterLock* cLock, bool preserveWriterFairness)
 {
     ReaderWriterLockCpp* lock = reinterpret_cast<ReaderWriterLockCpp*>(cLock);
-    return lock->TryLockWrite();
+    return lock->TryLockWrite(preserveWriterFairness);
 }
 
 HEXA_UTILS_API_INTERNAL(void) ReaderWriterLock_UnlockWrite(ReaderWriterLock* cLock)