v3.0

[3.0] - 04.03.2026

The "Zero Friction & Drop-in Replacement" update. This version marks a major architectural leap by bypassing internal library overheads, introducing true O(1) broadcast clearing, and achieving 100% API parity with Python's standard concurrency primitives.

Added

• High-Performance Micro-Queues (_ThreadWaitQueue, _AsyncWaitQueue):
  • Replaced heavy standard threading.Condition and asyncio.Condition internals with lean, custom-built O(1) wait queues.
  • These queues operate directly under the parent lock’s protection, eliminating nested lock overhead and minimizing OS-level context switching.
• 100% Drop-in Replacement Architecture:
  • RWLockBase, RWConditionBase, AsyncRWLockBase, and AsyncRWConditionBase now natively implement the complete standard Lockable and ConditionLockable (and their async counterparts) protocols directly.
  • Calling standard methods directly on the core object (e.g., lock.acquire(), await cond.wait(), __enter__, __aenter__) now automatically and safely routes to the exclusive .write proxy.
  • This allows custom locks (Fair, Read-Pref, Write-Pref) to be seamlessly passed into third-party libraries (e.g., SQLAlchemy, requests) expecting standard threading.Lock or asyncio.Lock instances.
• Standard Adapters (Lock, Condition, AsyncLock, AsyncCondition):
  • Added specific adapter classes that encapsulate standard threading and asyncio primitives while conforming strictly to the RWLockBase API signature (.read and .write attributes). Ideal for dependency injection workflows.

Updated

• Class Naming Standardization (FIFO to Fair):
  • Renamed all FIFO scheduling classes to Fair (e.g., RWLockFIFO -> RWLockFair, AsyncRWLockFIFO -> AsyncRWLockFair and their Reentrant variants) to better align with standard computer science terminology for phase-ordered, starvation-free scheduling.
• "Happy Path" Performance Isolation (Thread & Async):
  • Re-engineered the wait logic in both environments to completely skip O(N) remove() operations upon successful wake-ups.
  • Async Environment: _AsyncWaitQueue.wait() and AsyncRWConditionProxy.wait() now utilize except asyncio.CancelledError for cleanup, ensuring zero execution cost on successful executions.
  • Thread Environment: _ThreadWaitQueue.wait() implements a strict gotit boolean flag, executing the cleanup block if not gotit only upon timeouts or external OS interrupts, bypassing list traversal on standard wake-ups.
• Pure O(1) Broadcast / Cache Stampede Eradication:
  • Upgraded notify_all() and _notify_all_core() methods across both Thread and Async wait queues (_ThreadWaitQueue, _AsyncWaitQueue, RWCondition, AsyncRWCondition).
  • Replaced the hallowed O(N) while loop and popleft() element extraction with a high-speed for loop iteration followed by a C-level deque.clear() operation, resolving CPU locking during massive (100+ tasks/threads) wake-ups.
• Dot-Lookup Elimination (Micro-optimization):
  • Applied local variable caching (waiters = self._waiters) inside highly concurrent loops (notify, notify_all) to bypass Python Virtual Machine (PVM) attribute lookup overhead.
• Documentation:
  • Appended "Drop-in Replacement" details to the Architecture Notes.
  • Added comprehensive Example 2 (Drop-in Replacement) blocks inside docstrings for every single primitive, guiding developers on direct standard API usage.
• Adapter Test Suites:
  • Integrated the newly introduced standard adapter classes (Lock, AsyncLock, Condition, AsyncCondition) into the testing pipeline to ensure 100% behavioral compliance with the standard Python library.

Fixed

• Thread Timeout and OS-Interrupt Resilience:
  • Hardened the _ThreadWaitQueue.wait(timeout) mechanics. Replaced standard exception wrapping with an absolute finally: self._lock.acquire() guarantee coupled with the gotit flag. This prevents infinite deadlocks even if the Operating System violently interrupts the thread (e.g., KeyboardInterrupt) precisely during a timeout expiration.
• Precise Partial Notifications (notify_core):
  • Distinctly separated the partial wake-up logic (notify(n)) from the broadcast logic (notify_all). Ensured notify(n) correctly decrements n only on successful, non-interrupted, or non-cancelled thread/task wake-ups using else blocks and .done() validations.
• Test Infrastructure Overhaul:
  • Completely redesigned and fortified the testing architecture to handle the new drop-in replacement patterns and micro-queue structures.
  • The testing suite has been expanded to a massive 266 unit tests, validating concurrency safety, cancellation shielding, and edge cases, executing flawlessly in a blistering 8.5 seconds.