tbb::spin_rw_mutex_v3 Class Reference
Synchronization

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
}
tbb::spin_rw_mutex_v3::internal_construct
void __TBB_EXPORTED_METHOD internal_construct()
Definition: spin_rw_mutex.cpp:152
tbb::spin_rw_mutex_v3::state
state_t state
State of lock.
Definition: spin_rw_mutex.h:217

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" );
}
__TBB_ASSERT
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:165
ITT_NOTIFY
#define ITT_NOTIFY(name, obj)
Definition: itt_notify.h:112
s
void const char const char int ITT_FORMAT __itt_group_sync s
Definition: ittnotify_static.h:91
tbb::spin_rw_mutex_v3::state_t
intptr_t state_t
Definition: spin_rw_mutex.h:207
tbb::spin_rw_mutex_v3::WRITER_PENDING
static const state_t WRITER_PENDING
Definition: spin_rw_mutex.h:209
tbb::spin_rw_mutex_v3::READERS
static const state_t READERS
Definition: spin_rw_mutex.h:210
tbb::spin_rw_mutex_v3::WRITER
static const state_t WRITER
Definition: spin_rw_mutex.h:208
tbb::spin_rw_mutex_v3::ONE_READER
static const state_t ONE_READER
Definition: spin_rw_mutex.h:211

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;
}
__TBB_AtomicOR
void __TBB_AtomicOR(volatile void *operand, uintptr_t addend)
Definition: tbb_machine.h:881
tbb::CAS
static T CAS(volatile T &addr, T newv, T oldv)
Definition: spin_rw_mutex.cpp:30
tbb::spin_rw_mutex_v3::BUSY
static const state_t BUSY
Definition: spin_rw_mutex.h:212

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(""));
}
_T
#define _T(string_literal)
Standard Windows style macro to markup the string literals.
Definition: itt_notify.h:59
ITT_SYNC_CREATE
#define ITT_SYNC_CREATE(obj, type, name)
Definition: itt_notify.h:115

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" );
}
sync_releasing
void const char const char int ITT_FORMAT __itt_group_sync x void const char ITT_FORMAT __itt_group_sync s void ITT_FORMAT __itt_group_sync p void ITT_FORMAT p sync_releasing
Definition: ittnotify_static.h:104

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);
}
__TBB_FetchAndAddWrelease
#define __TBB_FetchAndAddWrelease(P, V)
Definition: tbb_machine.h:312

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 );
}
__TBB_AtomicAND
void __TBB_AtomicAND(volatile void *operand, uintptr_t addend)
Definition: tbb_machine.h:891

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
}
tbb::spin_rw_mutex_v3::internal_acquire_writer
bool __TBB_EXPORTED_METHOD internal_acquire_writer()
Internal acquire write lock.
Definition: spin_rw_mutex.cpp:37
tbb::spin_rw_mutex_v3::internal_release_reader
void __TBB_EXPORTED_METHOD internal_release_reader()
Internal release read lock.
Definition: spin_rw_mutex.cpp:115

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();}
tbb::spin_rw_mutex_v3::internal_acquire_reader
void __TBB_EXPORTED_METHOD internal_acquire_reader()
Internal acquire read lock.
Definition: spin_rw_mutex.cpp:62

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();}
tbb::spin_rw_mutex_v3::internal_try_acquire_writer
bool __TBB_EXPORTED_METHOD internal_try_acquire_writer()
Internal try_acquire write lock.
Definition: spin_rw_mutex.cpp:123

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();}
tbb::spin_rw_mutex_v3::internal_try_acquire_reader
bool __TBB_EXPORTED_METHOD internal_try_acquire_reader()
Internal try_acquire read lock.
Definition: spin_rw_mutex.cpp:136

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 */
}
tbb::spin_rw_mutex_v3::internal_release_writer
void __TBB_EXPORTED_METHOD internal_release_writer()
Out of line code for releasing a write lock.
Definition: spin_rw_mutex.cpp:55

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

static protected

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

static protected

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)

static protected

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

static protected

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

static protected

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

Copyright © 2005-2020 Intel Corporation. All Rights Reserved.

Intel, Pentium, Intel Xeon, Itanium, Intel XScale and VTune are registered trademarks or trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

* Other names and brands may be claimed as the property of others.