TfSpinMutex Class Reference

This class implements a simple spin lock that emphasizes throughput when there is little to no contention. More...

#include <spinMutex.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
	TfSpinMutex ()
	Construct a mutex, initially unlocked.
bool	TryAcquire ()
	Acquire a lock on this mutex if it is not currently held by another thread.
void	Acquire ()
	Acquire a lock on this mutex.
void	Release ()
	Release this thread's lock on this mutex.

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

Detailed Description

This class implements a simple spin lock that emphasizes throughput when there is little to no contention.

Like all spin locks, any contention performs poorly; consider a different algorithm design or synchronization strategy in that case.

This class provides a nested TfSpinMutex::ScopedLock that makes it easy to acquire locks and have those locks automatically release when the ScopedLock is destroyed.

TfSpinMutex is observed to compile to the same instruction sequence as tbb::spin_mutex on x86-64 for uncontended lock/unlock. The main difference between TfSpinMutex and tbb:spin_mutex is that, for contended lock operations, TfSpinMutex calls an out-of-line function to handle spinning & backoff, while the tbb::spin_mutex inlines that code. This translates to 4 instructions inlined to take a TfSpinMutex lock, compared to 28 instructions inlined for tbb:spin_mutex at the time of this writing. Correspondingly tbb::spin_mutex offers ~2% better throughput under high contention. But again, avoid spin locks if you have contention.

Definition at line 42 of file spinMutex.h.

---

Class Documentation

TfSpinMutex::DeferAcquire

struct TfSpinMutex::DeferAcquire

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

Use with TfSpinMutex::deferAcquire.

Definition at line 51 of file spinMutex.h.

Constructor & Destructor Documentation

TfSpinMutex()

TfSpinMutex ( )

inline

Construct a mutex, initially unlocked.

Definition at line 47 of file spinMutex.h.

Member Function Documentation

Acquire()

void Acquire ( )

inline

Acquire a lock on this mutex.

If another thread holds a lock on this mutex, wait until it is released and this thread successfully acquires it. This thread must not already hold a lock on this mutex.

Definition at line 163 of file spinMutex.h.

Release()

void Release ( )

inline

Release this thread's lock on this mutex.

Definition at line 171 of file spinMutex.h.

TryAcquire()

bool TryAcquire ( )

inline

Acquire a lock on this mutex if it is not currently held by another thread.

Return true if the lock was acquired, or false if it was not because another thread held the lock. This thread must not already hold a lock on this mutex.

Definition at line 156 of file spinMutex.h.

Member Data Documentation

deferAcquire

constexpr DeferAcquire deferAcquire {}

staticconstexpr

Tag value for deferred-acquisition ScopedLock construction.

Definition at line 54 of file spinMutex.h.

---

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

• pxr/base/tf/spinMutex.h