mqudsi / rwlock Goto Github PK

RWLock is a C++ library meant to provide light-weight read-write locks
for Windows thread synchronization. RWLock is intended to be both
versatile and lightweight, and comes in a few different flavors.

RWLock is developed and maintained by Mahmoud Al-Qudsi
<[email protected]> of NeoSmart Technologies <http://neosmart.net/>

Pthread's rwlock objects provide a high-performance means of allowing
either multiple readers to access a resource simultaneously or a
single writer. Windows did not have an equivalent thread
synchronization primitive until Windows Vista was released. However,
most software developers still target Windows XP and above, so this
library should come in handy to fill in the gap.

Non-IPC RWLock() implementations will automatically use Microsoft's
SRW Locks behind the scene if run on Windows Vista or above.

Unlike pthread_rwlock_t and SRW Locks, RWLock can also be used for
interprocess read-write synchronization via placement of a single
intptr_t object memory-mapped or stored in a shared data segment.

Usage:

RWLock comes in four distinct flavors, each with different features
and different performance characteristics.

All four RWLock implementations share a common locking/unlocking API,
though they differ somewhat in initialization:

void StartRead();
void EndRead();
void StartWrite();
void EndWrite();

The usage is completely straight-forward. Readers call StartRead() to
access a shared resource for reading and EndRead() at the end of
accessing the shared resource. Writers do the same with StartWrite()
and EndWrite(). These functions take no parameters and return no
values.

The different RWLock flavors are listed below, from fastest to
slowest. You should use the fastest object that meets your
requirements:


1. RWLock()

* This is the fastest and lightest RWLock flavor 

* RWLock cannot be used for cross-process synchronization

* RWLock does not support reentrance(StartRead() being called multiple
  times by the same thread before EndRead() is called)

* RWLock does not support calling StartRead() after calling
  StartWrite() but before calling EndWrite()

* On Windows Vista/7/8, this RWLock implementation will dynamically
  switch to an SRW Lock underneath the hood for optimum performance.


2. RWLockReentrant()

* RWLockReentrant supports reentrance

* RWLockReentrant supports calling StartRead() after StartWrite()

* RWLockReentrant cannot be used for cross-process synchronization

* On Windows Vista/7/8, this RWLock implementation will dynamically
  switch to an SRW Lock underneath the hood for optimum performance.


3. RWLockIPC(intptr_t *lock, LPCTSTR guid)

lock: pointer to an intptr_t object located in a shared data segment

guid: unique string used to create the named synchronization objects

* RWLockIPC can be used for cross-process synchronization

* RWLockIPC does not support reentrance

* RWLockIPC does not support calling StartRead() after calling
  StartWrite()


4. RWLockIPCReentrant(intptr_t *lock, LPCTSTR guid)

lock: pointer to an intptr_t object located in a shared data segment

guid: unique string used to create the named synchronization objects

* RWLockIPCReentrant can be used for cross-process synchronization

* RWLockIPCReentrant supports reentrance

* RWLockIPCReentrant supports calling StartRead() after calling
  StartWrite()