MutexRW Struct Reference

#include <evo/thread.h>

Detailed Description

Read/Write Mutex for thread synchronization.

• Shared mutex used to synchronize read/write access to shared data by multiple threads
  • This allows multiple concurrent read (shared) locks while not locked for writing
  • Write access requires a full normal lock (same interface as Mutex), blocks all reader locks and other write locks – see Lock
  • Read access requires a read (aka shared) lock, blocks write locks but doesn't block other reader locks – see LockRead
  • Write locks take priority so this doesn't have a "writer starvation" problem with constant reads
• Thread safe
• Linking:
  • Linux/Unix: -pthread
  • Cygwin: -lpthread
  • Windows: Usually multithreaded by default – MSVC project settings: C/C++ -> Code Generation -> Runtime Library

Public Types
typedef SmartLock< MutexRW >	Lock
	Write Lock object type, general Mutex interface (Mutex::Lock will also work) – see SmartLock. More...
typedef SmartLockRead< MutexRW >	LockRead
	Read Lock object type – see SmartLockRead. More...
typedef SmartLock< MutexRW >	LockWrite
	Write Lock object type – see SmartLock. More...

Public Member Functions
	MutexRW ()
	Constructor. More...
	~MutexRW ()
	Destructor. More...
void	lock ()
	Write-Lock mutex. More...
void	lock_read ()
	Read-Lock mutex. More...
bool	trylock ()
	Try to Write-Lock mutex without blocking. More...
bool	trylock (ulong timeout_ms)
	Try to Write-Lock mutex with a timeout. More...
bool	trylock_read ()
	Try to Read-Lock mutex without blocking. More...
void	unlock ()
	Write-Unlock mutex. More...
void	unlock_read ()
	Read-Unlock mutex. More...

Member Typedef Documentation

Lock

typedef SmartLock<MutexRW> Lock

Write Lock object type, general Mutex interface (Mutex::Lock will also work) – see SmartLock.

LockRead

typedef SmartLockRead<MutexRW> LockRead

Read Lock object type – see SmartLockRead.

LockWrite

typedef SmartLock<MutexRW> LockWrite

Write Lock object type – see SmartLock.

Constructor & Destructor Documentation

MutexRW()

MutexRW ( )

inline

Constructor.

~MutexRW()

~MutexRW ( )

inline

Destructor.

Member Function Documentation

lock()

void lock ( )

inline

Write-Lock mutex.

• Must call unlock() after each lock(), otherwise results are undefined
• Results are undefined if already write-locked by current thread

lock_read()

void lock_read ( )

inline

Read-Lock mutex.

• Must call unlock_read() after each lock_read(), otherwise results are undefined
• Results are undefined if already read-locked by current thread

trylock() [1/2]

bool trylock ( )

inline

Try to Write-Lock mutex without blocking.

• This allows polling for a write-lock without blocking
• If current thread already has a lock, whether this succeeds is platform dependent – some platforms (Windows) allow nested locks, others don't
• Caution: Polling with this can starve (never lock) under high load (constant read/write locks)

Returns

Whether successful, false if write-lock not available

trylock() [2/2]

bool trylock ( ulong  timeout_ms )

inline

Try to Write-Lock mutex with a timeout.

• This allows polling for a write-lock until timeout
• If current thread already has a lock, whether this succeeds is platform dependent – some platforms (Windows) allow nested locks, others don't
• OSX: This does a spin wait (which consumes CPU) since OSX doesn't support timeout on pthread mutex lock
• Windows: This does a spin wait (which consumes CPU) since Windows doesn't support timeout on Critical Section lock
• Caution: This can starve (never lock) in Windows or OSX under high load (constant locks)

Parameters

timeout_ms

Timeout in milliseconds

Returns

Whether successful, false on timeout

trylock_read()

bool trylock_read ( )

inline

Try to Read-Lock mutex without blocking.

• This allows polling for a read-lock without blocking
• If current thread already has a lock, whether this succeeds is platform dependent – some platforms (Windows) allow nested locks, others don't
• Caution: Polling with this can starve (never lock) under high load (constant read/write locks)

Returns

Whether successful, false if read-lock not available

unlock()

void unlock ( )

inline

Write-Unlock mutex.

• Results are undefined if called while mutex not write-locked

unlock_read()

void unlock_read ( )

inline

Read-Unlock mutex.

• Results are undefined if called while mutex not read-locked

---

The documentation for this struct was generated from the following file:

• evo/thread.h