TfSpinRWMutex Class Reference

#include <spinRWMutex.h>

Classes
struct	ScopedLock

Public Member Functions
	TfSpinRWMutex ()
	Construct a mutex, initially unlocked. More...
bool	TryAcquireRead ()
void	AcquireRead ()
void	ReleaseRead ()
	Release this thread's read lock on this mutex. More...
bool	TryAcquireWrite ()
void	AcquireWrite ()
void	ReleaseWrite ()
	Release this thread's write lock on this mutex. More...
bool	UpgradeToWriter ()
bool	DowngradeToReader ()

Friends
class	TfBigRWMutex

Detailed Description

This class implements a readers-writer spin lock that emphasizes throughput when there is light contention or moderate contention dominated by readers. Like all spin locks, significant contention performs poorly; consider a different algorithm design or synchronization strategy in that case.

In the best case, acquiring a read lock is an atomic add followed by a conditional branch, and acquiring a write lock is an atomic bitwise-or followed by a conditional branch.

When contended by only readers, acquiring a read lock is the same: an atomic add followed by a conditional branch. Of course the shared cache line being concurrently read and modified will affect performance.

In the worst case, acquiring a read lock does the atomic add and conditional branch, but the condition shows writer activity, so the add must be undone by a subtraction, and then the thread must wait to see no writer activity before trying again.

Similarly in the worst case for acquiring a write lock, the thread does the atomic bitwise-or, but sees another active writer, and then must wait to see no writer activity before trying again. Once the exclusive-or is done successfully, then the writer must wait for any pending readers to clear out before it can proceed.

This class provides a nested TfSpinRWMutex::ScopedLock that makes it easy to acquire locks, upgrade reader to writer, downgrade writer to reader, and have those locks automatically release when the ScopedLock is destroyed.

Definition at line 67 of file spinRWMutex.h.

Constructor & Destructor Documentation

TfSpinRWMutex::TfSpinRWMutex ( )

inline

Construct a mutex, initially unlocked.

Definition at line 75 of file spinRWMutex.h.

Member Function Documentation

void TfSpinRWMutex::AcquireRead ( )

inline

Acquire a read lock on this mutex. This thread must not already hold a lock on this mutex (either read or write). Consider calling DowngradeToReader() if this thread holds a write lock.

Definition at line 217 of file spinRWMutex.h.

void TfSpinRWMutex::AcquireWrite ( )

inline

Acquire a write lock on this mutex. This thread must not already hold a lock on this mutex (either read or write). Consider calling UpgradeToWriter() if this thread holds a read lock.

Definition at line 253 of file spinRWMutex.h.

bool TfSpinRWMutex::DowngradeToReader ( )

inline

Downgrade this mutex, which must be locked for write by this thread, to being locked for read by this thread. Return true if the downgrade happened "atomically", meaning that the write lock was not released (and thus possibly acquired by another thread). This implementation currently always returns true.

Definition at line 303 of file spinRWMutex.h.

void TfSpinRWMutex::ReleaseRead ( )

inline

Release this thread's read lock on this mutex.

Definition at line 229 of file spinRWMutex.h.

void TfSpinRWMutex::ReleaseWrite ( )

inline

Release this thread's write lock on this mutex.

Definition at line 265 of file spinRWMutex.h.

bool TfSpinRWMutex::TryAcquireRead ( )

inline

Attempt to acquire a read lock on this mutex without waiting for writers. This thread must not already hold a lock on this mutex (either read or write). Return true if the lock is acquired, false otherwise.

Definition at line 200 of file spinRWMutex.h.

bool TfSpinRWMutex::TryAcquireWrite ( )

inline

Attempt to acquire a write lock on this mutex without waiting for other writers. This thread must not already hold a lock on this mutex (either read or write). Return true if the lock is acquired, false otherwise.

Definition at line 237 of file spinRWMutex.h.

bool TfSpinRWMutex::UpgradeToWriter ( )

inline

Upgrade this thread's lock on this mutex (which must be a read lock) to a write lock. Return true if the upgrade is done "atomically" meaning that the read lock was not released (and thus no other writer could have acquired the lock in the interim). Return false if this lock was released and thus another writer could have taken the lock in the interim.

Definition at line 275 of file spinRWMutex.h.

Friends And Related Function Documentation

friend class TfBigRWMutex

friend

Definition at line 311 of file spinRWMutex.h.

---

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

• pxr/base/tf/spinRWMutex.h