TfSpinRWMutex Class Reference

This class implements a readers-writer spin lock that emphasizes throughput when there is light contention or moderate contention dominated by readers. More...

#include <spinRWMutex.h>

Classes
struct	DeferAcquire
	Tag type for constructing a ScopedLock associated with a mutex but not yet acquired. More...
struct	ScopedLock
	Scoped lock utility class. More...

Public Member Functions
	TfSpinRWMutex ()
	Construct a mutex, initially unlocked.
bool	TryAcquireRead ()
	Attempt to acquire a read lock on this mutex without waiting for writers.
void	AcquireRead ()
	Acquire a read lock on this mutex.
void	ReleaseRead ()
	Release this thread's read lock on this mutex.
bool	TryAcquireWrite ()
	Attempt to acquire a write lock on this mutex without waiting for other writers, but waiting for any currently active readers to release.
bool	TryAcquireWriteIfReleased ()
	Attempt to acquire a write lock on this mutex only if the mutex is in the fully released state (no readers, no writers).
void	AcquireWrite ()
	Acquire a write lock on this mutex.
void	ReleaseWrite ()
	Release this thread's write lock on this mutex.
bool	UpgradeToWriter ()
	Upgrade this thread's lock on this mutex (which must be a read lock) to a write lock.
bool	DowngradeToReader ()
	Downgrade this mutex, which must be locked for write by this thread, to being locked for read by this thread.

Static Public Attributes
static constexpr DeferAcquire	deferAcquire {}
	Tag value for deferred-acquisition ScopedLock construction.

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 bitwise-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 51 of file spinRWMutex.h.

---

Class Documentation

TfSpinRWMutex::DeferAcquire

struct TfSpinRWMutex::DeferAcquire

Tag type for constructing a ScopedLock associated with a mutex but not yet acquired.

Use with TfSpinRWMutex::deferAcquire.

Definition at line 63 of file spinRWMutex.h.

Constructor & Destructor Documentation

TfSpinRWMutex()

TfSpinRWMutex ( )

inline

Construct a mutex, initially unlocked.

Definition at line 59 of file spinRWMutex.h.

Member Function Documentation

AcquireRead()

void 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 305 of file spinRWMutex.h.

AcquireWrite()

void 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 358 of file spinRWMutex.h.

DowngradeToReader()

bool 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 411 of file spinRWMutex.h.

ReleaseRead()

void ReleaseRead ( )

inline

Release this thread's read lock on this mutex.

Definition at line 317 of file spinRWMutex.h.

ReleaseWrite()

void ReleaseWrite ( )

inline

Release this thread's write lock on this mutex.

Definition at line 370 of file spinRWMutex.h.

TryAcquireRead()

bool 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 286 of file spinRWMutex.h.

TryAcquireWrite()

bool TryAcquireWrite ( )

inline

Attempt to acquire a write lock on this mutex without waiting for other writers, but waiting for any currently active readers to release.

This thread must not already hold a lock on this mutex (either read or write). Return true if the lock is acquired (no other writer was active), false otherwise. Note: if readers are present but no other writer is active, this call will block until those readers have released.

Definition at line 330 of file spinRWMutex.h.

TryAcquireWriteIfReleased()

bool TryAcquireWriteIfReleased ( )

inline

Attempt to acquire a write lock on this mutex only if the mutex is in the fully released state (no readers, no 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. Never blocks.

Definition at line 347 of file spinRWMutex.h.

UpgradeToWriter()

bool 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 380 of file spinRWMutex.h.

Friends And Related Function Documentation

TfBigRWMutex

friend class TfBigRWMutex

friend

Definition at line 427 of file spinRWMutex.h.

Member Data Documentation

deferAcquire

constexpr DeferAcquire deferAcquire {}

staticconstexpr

Tag value for deferred-acquisition ScopedLock construction.

Definition at line 66 of file spinRWMutex.h.

---

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

• pxr/base/tf/spinRWMutex.h