tbb::spin_rw_mutex_v3 Class Reference

Fast, unfair, spinning reader-writer lock with backoff and writer-preference. More...

#include <spin_rw_mutex.h>

Inheritance diagram for tbb::spin_rw_mutex_v3:

Collaboration diagram for tbb::spin_rw_mutex_v3:

Classes
class	scoped_lock
	The scoped locking pattern. More...

Public Member Functions
	spin_rw_mutex_v3 ()
	Construct unacquired mutex. More...
void	lock ()
	Acquire writer lock. More...
bool	try_lock ()
	Try acquiring writer lock (non-blocking) More...
void	unlock ()
	Release lock. More...
void	lock_read ()
	Acquire reader lock. More...
bool	try_lock_read ()
	Try acquiring reader lock (non-blocking) More...

Static Public Attributes
static const bool	is_rw_mutex = true
static const bool	is_recursive_mutex = false
static const bool	is_fair_mutex = false

Protected Types
typedef intptr_t	state_t

Protected Attributes
state_t	state
	State of lock. More...

Static Protected Attributes
static const state_t	WRITER = 1
static const state_t	WRITER_PENDING = 2
static const state_t	READERS = ~(WRITER | WRITER_PENDING)
static const state_t	ONE_READER = 4
static const state_t	BUSY = WRITER | READERS

Private Member Functions
bool __TBB_EXPORTED_METHOD	internal_acquire_writer ()
	Internal acquire write lock. More...
void __TBB_EXPORTED_METHOD	internal_release_writer ()
	Out of line code for releasing a write lock. More...
void __TBB_EXPORTED_METHOD	internal_acquire_reader ()
	Internal acquire read lock. More...
bool __TBB_EXPORTED_METHOD	internal_upgrade ()
	Internal upgrade reader to become a writer. More...
void __TBB_EXPORTED_METHOD	internal_downgrade ()
	Out of line code for downgrading a writer to a reader. More...
void __TBB_EXPORTED_METHOD	internal_release_reader ()
	Internal release read lock. More...
bool __TBB_EXPORTED_METHOD	internal_try_acquire_writer ()
	Internal try_acquire write lock. More...
bool __TBB_EXPORTED_METHOD	internal_try_acquire_reader ()
	Internal try_acquire read lock. More...
void __TBB_EXPORTED_METHOD	internal_construct ()

Detailed Description

Fast, unfair, spinning reader-writer lock with backoff and writer-preference.

Definition at line 38 of file spin_rw_mutex.h.

Member Typedef Documentation

state_t

typedef intptr_t tbb::spin_rw_mutex_v3::state_t

protected

Definition at line 207 of file spin_rw_mutex.h.

Constructor & Destructor Documentation

spin_rw_mutex_v3()

tbb::spin_rw_mutex_v3::spin_rw_mutex_v3 ( )

inline

Construct unacquired mutex.

Definition at line 70 of file spin_rw_mutex.h.

                       : state(0) {
#if TBB_USE_THREADING_TOOLS
        internal_construct();
#endif
    }

References internal_construct().

Here is the call graph for this function:

Member Function Documentation

internal_acquire_reader()

void tbb::spin_rw_mutex_v3::internal_acquire_reader ( )

private

Internal acquire read lock.

Acquire read lock on given mutex.

Definition at line 62 of file spin_rw_mutex.cpp.

{
    ITT_NOTIFY(sync_prepare, this);
    for( internal::atomic_backoff b;;b.pause() ){
        state_t s = const_cast<volatile state_t&>(state); // ensure reloading
        if( !(s & (WRITER|WRITER_PENDING)) ) { // no writer or write requests
            state_t t = (state_t)__TBB_FetchAndAddW( &state, (intptr_t) ONE_READER );
            if( !( t&WRITER ))
                break; // successfully stored increased number of readers
            // writer got there first, undo the increment
            __TBB_FetchAndAddW( &state, -(intptr_t)ONE_READER );
        }
    }

    ITT_NOTIFY(sync_acquired, this);
    __TBB_ASSERT( state & READERS, "invalid state of a read lock: no readers" );
}

References __TBB_ASSERT, ITT_NOTIFY, ONE_READER, tbb::internal::atomic_backoff::pause(), READERS, s, state, WRITER, and WRITER_PENDING.

Referenced by tbb::spin_rw_mutex_v3::scoped_lock::acquire(), and lock_read().

Here is the call graph for this function:

Here is the caller graph for this function:

internal_acquire_writer()

bool tbb::spin_rw_mutex_v3::internal_acquire_writer ( )

private

Internal acquire write lock.

Acquire write lock on the given mutex.

Definition at line 37 of file spin_rw_mutex.cpp.

{
    ITT_NOTIFY(sync_prepare, this);
    for( internal::atomic_backoff backoff;;backoff.pause() ){
        state_t s = const_cast<volatile state_t&>(state); // ensure reloading
        if( !(s & BUSY) ) { // no readers, no writers
            if( CAS(state, WRITER, s)==s )
                break; // successfully stored writer flag
            backoff.reset(); // we could be very close to complete op.
        } else if( !(s & WRITER_PENDING) ) { // no pending writers
            __TBB_AtomicOR(&state, WRITER_PENDING);
        }
    }
    ITT_NOTIFY(sync_acquired, this);
    return false;
}

References __TBB_AtomicOR(), BUSY, tbb::CAS(), ITT_NOTIFY, tbb::internal::atomic_backoff::pause(), s, state, WRITER, and WRITER_PENDING.

Referenced by tbb::spin_rw_mutex_v3::scoped_lock::acquire(), internal_upgrade(), and lock().

Here is the call graph for this function:

Here is the caller graph for this function:

internal_construct()

void tbb::spin_rw_mutex_v3::internal_construct ( )

private

Definition at line 152 of file spin_rw_mutex.cpp.

                                          {
    ITT_SYNC_CREATE(this, _T("tbb::spin_rw_mutex"), _T(""));
}

References _T, and ITT_SYNC_CREATE.

Referenced by spin_rw_mutex_v3().

Here is the caller graph for this function:

internal_downgrade()

void tbb::spin_rw_mutex_v3::internal_downgrade ( )

private

Out of line code for downgrading a writer to a reader.

Downgrade writer to a reader.

This code has debug checking and instrumentation for Intel(R) Thread Checker and Intel(R) Thread Profiler.

Definition at line 108 of file spin_rw_mutex.cpp.

                                          {
    ITT_NOTIFY(sync_releasing, this);
    __TBB_FetchAndAddW( &state, (intptr_t)(ONE_READER-WRITER));
    __TBB_ASSERT( state & READERS, "invalid state after downgrade: no readers" );
}

References __TBB_ASSERT, ITT_NOTIFY, ONE_READER, READERS, state, sync_releasing, and WRITER.

Referenced by tbb::spin_rw_mutex_v3::scoped_lock::downgrade_to_reader().

Here is the caller graph for this function:

internal_release_reader()

void tbb::spin_rw_mutex_v3::internal_release_reader ( )

private

Internal release read lock.

Release read lock on the given mutex.

Definition at line 115 of file spin_rw_mutex.cpp.

{
    __TBB_ASSERT( state & READERS, "invalid state of a read lock: no readers" );
    ITT_NOTIFY(sync_releasing, this); // release reader
    __TBB_FetchAndAddWrelease( &state,-(intptr_t)ONE_READER);
}

References __TBB_ASSERT, __TBB_FetchAndAddWrelease, ITT_NOTIFY, ONE_READER, READERS, state, and sync_releasing.

Referenced by internal_upgrade(), tbb::spin_rw_mutex_v3::scoped_lock::release(), and unlock().

Here is the caller graph for this function:

internal_release_writer()

void tbb::spin_rw_mutex_v3::internal_release_writer ( )

private

Out of line code for releasing a write lock.

Release writer lock on the given mutex.

This code has debug checking and instrumentation for Intel(R) Thread Checker and Intel(R) Thread Profiler.

Definition at line 55 of file spin_rw_mutex.cpp.

{
    ITT_NOTIFY(sync_releasing, this);
    __TBB_AtomicAND( &state, READERS );
}

References __TBB_AtomicAND(), ITT_NOTIFY, READERS, state, and sync_releasing.

Referenced by tbb::spin_rw_mutex_v3::scoped_lock::release(), and unlock().

Here is the call graph for this function:

Here is the caller graph for this function:

internal_try_acquire_reader()

bool tbb::spin_rw_mutex_v3::internal_try_acquire_reader ( )

private

Internal try_acquire read lock.

Try to acquire read lock on the given mutex.

Definition at line 136 of file spin_rw_mutex.cpp.

{
    // for a reader: acquire if no active or waiting writers
    state_t s = state;
    if( !(s & (WRITER|WRITER_PENDING)) ) { // no writers
        state_t t = (state_t)__TBB_FetchAndAddW( &state, (intptr_t) ONE_READER );
        if( !( t&WRITER )) {  // got the lock
            ITT_NOTIFY(sync_acquired, this);
            return true; // successfully stored increased number of readers
        }
        // writer got there first, undo the increment
        __TBB_FetchAndAddW( &state, -(intptr_t)ONE_READER );
    }
    return false;
}

References ITT_NOTIFY, ONE_READER, s, state, WRITER, and WRITER_PENDING.

Referenced by tbb::spin_rw_mutex_v3::scoped_lock::try_acquire(), and try_lock_read().

Here is the caller graph for this function:

internal_try_acquire_writer()

bool tbb::spin_rw_mutex_v3::internal_try_acquire_writer ( )

private

Internal try_acquire write lock.

Try to acquire write lock on the given mutex.

Definition at line 123 of file spin_rw_mutex.cpp.

{
    // for a writer: only possible to acquire if no active readers or writers
    state_t s = state;
    if( !(s & BUSY) ) // no readers, no writers; mask is 1..1101
        if( CAS(state, WRITER, s)==s ) {
            ITT_NOTIFY(sync_acquired, this);
            return true; // successfully stored writer flag
        }
    return false;
}

References BUSY, tbb::CAS(), ITT_NOTIFY, s, state, and WRITER.

Referenced by tbb::spin_rw_mutex_v3::scoped_lock::try_acquire(), and try_lock().

Here is the call graph for this function:

Here is the caller graph for this function:

internal_upgrade()

bool tbb::spin_rw_mutex_v3::internal_upgrade ( )

private

Internal upgrade reader to become a writer.

Upgrade reader to become a writer.

Returns whether the upgrade happened without releasing and re-acquiring the lock

Definition at line 82 of file spin_rw_mutex.cpp.

{
    state_t s = state;
    __TBB_ASSERT( s & READERS, "invalid state before upgrade: no readers " );
    // check and set writer-pending flag
    // required conditions: either no pending writers, or we are the only reader
    // (with multiple readers and pending writer, another upgrade could have been requested)
    while( (s & READERS)==ONE_READER || !(s & WRITER_PENDING) ) {
        state_t old_s = s;
        if( (s=CAS(state, s | WRITER | WRITER_PENDING, s))==old_s ) {
            ITT_NOTIFY(sync_prepare, this);
            internal::atomic_backoff backoff;
            while( (state & READERS) != ONE_READER ) backoff.pause();
            __TBB_ASSERT((state&(WRITER_PENDING|WRITER))==(WRITER_PENDING|WRITER),"invalid state when upgrading to writer");
            // both new readers and writers are blocked at this time
            __TBB_FetchAndAddW( &state,  - (intptr_t)(ONE_READER+WRITER_PENDING));
            ITT_NOTIFY(sync_acquired, this);
            return true; // successfully upgraded
        }
    }
    // slow reacquire
    internal_release_reader();
    return internal_acquire_writer(); // always returns false
}

References __TBB_ASSERT, tbb::CAS(), internal_acquire_writer(), internal_release_reader(), ITT_NOTIFY, ONE_READER, tbb::internal::atomic_backoff::pause(), READERS, s, state, WRITER, and WRITER_PENDING.

Referenced by tbb::spin_rw_mutex_v3::scoped_lock::upgrade_to_writer().

Here is the call graph for this function:

Here is the caller graph for this function:

lock()

void tbb::spin_rw_mutex_v3::lock ( )

inline

Acquire writer lock.

Definition at line 180 of file spin_rw_mutex.h.

{internal_acquire_writer();}

References internal_acquire_writer().

Referenced by tbb::internal::market::adjust_demand(), and tbb::internal::market::try_destroy_arena().

Here is the call graph for this function:

Here is the caller graph for this function:

lock_read()

void tbb::spin_rw_mutex_v3::lock_read ( )

inline

Acquire reader lock.

Definition at line 200 of file spin_rw_mutex.h.

{internal_acquire_reader();}

References internal_acquire_reader().

Here is the call graph for this function:

try_lock()

bool tbb::spin_rw_mutex_v3::try_lock ( )

inline

Try acquiring writer lock (non-blocking)

Return true if lock acquired; false otherwise.

Definition at line 184 of file spin_rw_mutex.h.

{return internal_try_acquire_writer();}

References internal_try_acquire_writer().

Here is the call graph for this function:

try_lock_read()

bool tbb::spin_rw_mutex_v3::try_lock_read ( )

inline

Try acquiring reader lock (non-blocking)

Return true if reader lock acquired; false otherwise.

Definition at line 204 of file spin_rw_mutex.h.

{return internal_try_acquire_reader();}

References internal_try_acquire_reader().

Here is the call graph for this function:

unlock()

void tbb::spin_rw_mutex_v3::unlock ( )

inline

Release lock.

Definition at line 187 of file spin_rw_mutex.h.

                  {
#if TBB_USE_THREADING_TOOLS||TBB_USE_ASSERT
        if( state&WRITER ) internal_release_writer();
        else               internal_release_reader();
#else
        if( state&WRITER ) __TBB_AtomicAND( &state, READERS );
        else               __TBB_FetchAndAddWrelease( &state, -(intptr_t)ONE_READER);
#endif /* TBB_USE_THREADING_TOOLS||TBB_USE_ASSERT */
    }

References __TBB_AtomicAND(), __TBB_FetchAndAddWrelease, internal_release_reader(), internal_release_writer(), ONE_READER, READERS, state, and WRITER.

Referenced by tbb::internal::market::adjust_demand(), and tbb::internal::market::try_destroy_arena().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

BUSY

const state_t tbb::spin_rw_mutex_v3::BUSY = WRITER | READERS

staticprotected

Definition at line 212 of file spin_rw_mutex.h.

Referenced by internal_acquire_writer(), and internal_try_acquire_writer().

is_fair_mutex

const bool tbb::spin_rw_mutex_v3::is_fair_mutex = false

static

Definition at line 175 of file spin_rw_mutex.h.

is_recursive_mutex

const bool tbb::spin_rw_mutex_v3::is_recursive_mutex = false

static

Definition at line 174 of file spin_rw_mutex.h.

is_rw_mutex

const bool tbb::spin_rw_mutex_v3::is_rw_mutex = true

static

Definition at line 173 of file spin_rw_mutex.h.

ONE_READER

const state_t tbb::spin_rw_mutex_v3::ONE_READER = 4

staticprotected

Definition at line 211 of file spin_rw_mutex.h.

Referenced by tbb::spin_rw_mutex_v3::scoped_lock::downgrade_to_reader(), internal_acquire_reader(), internal_downgrade(), internal_release_reader(), internal_try_acquire_reader(), internal_upgrade(), tbb::spin_rw_mutex_v3::scoped_lock::release(), and unlock().

READERS

const state_t tbb::spin_rw_mutex_v3::READERS = ~(WRITER | WRITER_PENDING)

staticprotected

Definition at line 210 of file spin_rw_mutex.h.

Referenced by internal_acquire_reader(), internal_downgrade(), internal_release_reader(), internal_release_writer(), internal_upgrade(), tbb::spin_rw_mutex_v3::scoped_lock::release(), and unlock().

state

state_t tbb::spin_rw_mutex_v3::state

protected

State of lock.

Bit 0 = writer is holding lock Bit 1 = request by a writer to acquire lock (hint to readers to wait) Bit 2..N = number of readers holding lock

Definition at line 217 of file spin_rw_mutex.h.

Referenced by tbb::spin_rw_mutex_v3::scoped_lock::downgrade_to_reader(), internal_acquire_reader(), internal_acquire_writer(), internal_downgrade(), internal_release_reader(), internal_release_writer(), internal_try_acquire_reader(), internal_try_acquire_writer(), internal_upgrade(), tbb::spin_rw_mutex_v3::scoped_lock::release(), and unlock().

WRITER

const state_t tbb::spin_rw_mutex_v3::WRITER = 1

staticprotected

Definition at line 208 of file spin_rw_mutex.h.

Referenced by tbb::spin_rw_mutex_v3::scoped_lock::downgrade_to_reader(), internal_acquire_reader(), internal_acquire_writer(), internal_downgrade(), internal_try_acquire_reader(), internal_try_acquire_writer(), internal_upgrade(), and unlock().

WRITER_PENDING

const state_t tbb::spin_rw_mutex_v3::WRITER_PENDING = 2

staticprotected

Definition at line 209 of file spin_rw_mutex.h.

Referenced by internal_acquire_reader(), internal_acquire_writer(), internal_try_acquire_reader(), and internal_upgrade().

---

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

• spin_rw_mutex.h
• spin_rw_mutex.cpp