The ReadWriteLock class defines a non-promotable lock that is very fast when only readers try to obtain the lock, but slower than a Mutex when there are writers. More...

#include "readwritelock.h"

Public Member Functions
	ReadWriteLock ()
	The semaphore is initialized to 1 so that the first Wait() succeeds. More...

	~ReadWriteLock ()

void	LockForRead ()
	Locks the ReadWriteLock for reading. More...

void	UnlockForRead ()
	Unlocks the ReadWriteLock for reading, which will allow writers to obtain a lock once the last reader has exited. More...

void	LockForWrite ()
	Locks the ReadWriteLock for writing. More...

void	UnlockForWrite ()
	Unlocks the ReadWriteLock for writing. More...

int	GetReaderCount () const
	Returns the number of readers in this lock. More...

int	GetWriterCount () const
	Returns the number of writers in this lock. More...

Detailed Description

The ReadWriteLock class defines a non-promotable lock that is very fast when only readers try to obtain the lock, but slower than a Mutex when there are writers.

A ReadWriteLock allows any number of readers to enter the lock as long as there are no writers, but each writer obtains exclusive access to the lock. At a high level, a ReadWriteLock behaves like an atomic integer under no or reader-only contention, and like a Mutex when there are any writers.

Note: since this implementation is non-promotable, attempting to acquire a write lock while holding a read lock will block the caller.

This implementation is based on sections 4.2.5 of The Little Book of Semaphores by Allen B. Downey. http://greenteapress.com/semaphores/downey08semaphores.pdf

This particular implementation has the following behaviors:

If there are no writers, then only the first reader to obtain the read lock Wait()s on a Semaphore.
If there are no writers, then only the last reader to unlock the read lock actually Post()s a Semaphore.
Writers cannot obtain a lock until all readers have exited, but while writers are waiting readers Lock() and Unlock() a Mutex in addition to the above semaphore behavior. This prevents writers them from starving at the expense of readers. If writing is more common than reading, however, it is faster to use a regular Mutex.

Definition at line 51 of file readwritelock.h.

Constructor & Destructor Documentation

ion::base::ReadWriteLock::ReadWriteLock ( )

The semaphore is initialized to 1 so that the first Wait() succeeds.

Definition at line 24 of file readwritelock.cc.

ion::base::ReadWriteLock::~ReadWriteLock ( )

Definition at line 27 of file readwritelock.cc.

Member Function Documentation

int ion::base::ReadWriteLock::GetReaderCount ( ) const

inline

Returns the number of readers in this lock.

Definition at line 71 of file readwritelock.h.

int ion::base::ReadWriteLock::GetWriterCount ( ) const

inline

Returns the number of writers in this lock.

Definition at line 73 of file readwritelock.h.

void ion::base::ReadWriteLock::LockForRead ( )

Locks the ReadWriteLock for reading.

This will block other readers if there is a writer is in the lock, and will cause LockForWrite() to block until the last reader that has entered the lock calls UnlockForRead().

Definition at line 29 of file readwritelock.cc.

References ion::port::Mutex::Lock(), ion::port::Mutex::Unlock(), and ion::port::Semaphore::Wait().

void ion::base::ReadWriteLock::LockForWrite ( )

Locks the ReadWriteLock for writing.

This will cause any callers of LockFor*() to block until the caller calls UnlockForWrite().

Definition at line 48 of file readwritelock.cc.

References ion::port::Mutex::Lock(), and ion::port::Semaphore::Wait().

void ion::base::ReadWriteLock::UnlockForRead ( )

Unlocks the ReadWriteLock for reading, which will allow writers to obtain a lock once the last reader has exited.

Definition at line 42 of file readwritelock.cc.

References ion::port::Semaphore::Post().

void ion::base::ReadWriteLock::UnlockForWrite ( )