AuroraRuntime/Include/Aurora/Threading/README.md

# AuThreading


# Features
* Thread synchronization primitives: condition ex, condition mutex, condition variable, critical section, event, mutex, rwlock, semaphore, and spinlock
* All primitives include a trylock and a nanosecond-resolution timed lock methods
* All lock-like primitives can be used with a AuFlexibleConditionVariable (noting AuConditionVariable binds to a single AuCondMutex)
* WakeOnAddress support on every operating system regardless of kernel support
* WakeOnAddress with various wake operations (eNotEqual, eEqual, eLessThanCompare, eGreaterThanCompare, eLessThanOrEqualsCompare, eGreaterThanOrEqualsCompare) of any size under 32 bytes
* Reference futex primitives: AuInitOnce, AuInitOnceSmall, AuFutexBarrier, AuFutexCond, AuFutexMutex, AuFutexSemaphore, FutexWaitable\*NoVTbl\*\*Movable\*Smallest (AuFutexMutexSmallest)
* No primitive will ever waste time syscalling or otherwise waking if not required
* Single core (thread check), Intel SMT (rdtsc), AARCH64 (rdtsc emu via CNTVCT_EL0), Intel Alderlake (umonitor/tpause), and AMD 2016+ (monitorx) optimized/aware spinning optimizations with in-process and CPU heuristics
* ...known good performance and low kernel stated CPU usage% on Windows 7, Windows 11, and Linux spanning a diverse range of processors.
* Timeline semaphores / completion barriers are supported via AuFutexSemaphore::LockUntilAtleastAbsNS/AcquireUntilAtleastAbsNS
* RWLock supports read-to-write upgrades when the decision to esclate is made based upon a shared resource, plus CheckSelfThreadIsWriter check
* RWLocks are read criticial section based and all writer threads are allowed to enter read critical sections. In addition, AuRWRenterableLock allows for write reentrancy. 
* Enchanced Win32 support with increased yield resolution and optimization around internal XP, internal Win8, and UWP APIs
* SleepNs function supporting higher resolution sleep available than in most APIs (^1)
* Thread Object per native OS thread
* Thread spawning with TLS handles and shutdown routines ~~dispatched under pseudo fibers. TODO: reimpl thread 'features' and NT-like APCs ~~
* Update thread affinity, throttle, name, and related attributes
* Lock Util: AU_LOCK_GUARD(pointer/reference/shared ptr)
* Lock Util: AU_TRY_LOCK_GUARD[...](pointer/reference/shared ptr)


^1: README SleepNote.txt