Intel(R) Threading Building Blocks Doxygen Documentation  version 4.2.3
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 42 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 211 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 74 of file spin_rw_mutex.h.

74  : state(0) {
75 #if TBB_USE_THREADING_TOOLS
77 #endif
78  }
void __TBB_EXPORTED_METHOD internal_construct()
state_t state
State of lock.

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 66 of file spin_rw_mutex.cpp.

67 {
68  ITT_NOTIFY(sync_prepare, this);
69  for( internal::atomic_backoff b;;b.pause() ){
70  state_t s = const_cast<volatile state_t&>(state); // ensure reloading
71  if( !(s & (WRITER|WRITER_PENDING)) ) { // no writer or write requests
72  state_t t = (state_t)__TBB_FetchAndAddW( &state, (intptr_t) ONE_READER );
73  if( !( t&WRITER ))
74  break; // successfully stored increased number of readers
75  // writer got there first, undo the increment
76  __TBB_FetchAndAddW( &state, -(intptr_t)ONE_READER );
77  }
78  }
79 
80  ITT_NOTIFY(sync_acquired, this);
81  __TBB_ASSERT( state & READERS, "invalid state of a read lock: no readers" );
82 }
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:169
static const state_t ONE_READER
static const state_t WRITER
static const state_t WRITER_PENDING
state_t state
State of lock.
#define ITT_NOTIFY(name, obj)
Definition: itt_notify.h:120
void const char const char int ITT_FORMAT __itt_group_sync s
static const state_t READERS

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

Referenced by lock_read().

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 41 of file spin_rw_mutex.cpp.

42 {
43  ITT_NOTIFY(sync_prepare, this);
44  for( internal::atomic_backoff backoff;;backoff.pause() ){
45  state_t s = const_cast<volatile state_t&>(state); // ensure reloading
46  if( !(s & BUSY) ) { // no readers, no writers
47  if( CAS(state, WRITER, s)==s )
48  break; // successfully stored writer flag
49  backoff.reset(); // we could be very close to complete op.
50  } else if( !(s & WRITER_PENDING) ) { // no pending writers
52  }
53  }
54  ITT_NOTIFY(sync_acquired, this);
55  return false;
56 }
static const state_t BUSY
static T CAS(volatile T &addr, T newv, T oldv)
static const state_t WRITER
static const state_t WRITER_PENDING
state_t state
State of lock.
#define ITT_NOTIFY(name, obj)
Definition: itt_notify.h:120
void const char const char int ITT_FORMAT __itt_group_sync s
void __TBB_AtomicOR(volatile void *operand, uintptr_t addend)
Definition: tbb_machine.h:882

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

Referenced by 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 156 of file spin_rw_mutex.cpp.

156  {
157  ITT_SYNC_CREATE(this, _T("tbb::spin_rw_mutex"), _T(""));
158 }
#define ITT_SYNC_CREATE(obj, type, name)
Definition: itt_notify.h:123
#define _T(string_literal)
Standard Windows style macro to markup the string literals.
Definition: itt_notify.h:66

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 112 of file spin_rw_mutex.cpp.

112  {
113  ITT_NOTIFY(sync_releasing, this);
114  __TBB_FetchAndAddW( &state, (intptr_t)(ONE_READER-WRITER));
115  __TBB_ASSERT( state & READERS, "invalid state after downgrade: no readers" );
116 }
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:169
static const state_t ONE_READER
static const state_t WRITER
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
state_t state
State of lock.
#define ITT_NOTIFY(name, obj)
Definition: itt_notify.h:120
static const state_t READERS

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

◆ 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 119 of file spin_rw_mutex.cpp.

120 {
121  __TBB_ASSERT( state & READERS, "invalid state of a read lock: no readers" );
122  ITT_NOTIFY(sync_releasing, this); // release reader
124 }
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:169
#define __TBB_FetchAndAddWrelease(P, V)
Definition: tbb_machine.h:313
static const state_t ONE_READER
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
state_t state
State of lock.
#define ITT_NOTIFY(name, obj)
Definition: itt_notify.h:120
static const state_t READERS

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 59 of file spin_rw_mutex.cpp.

60 {
63 }
void __TBB_AtomicAND(volatile void *operand, uintptr_t addend)
Definition: tbb_machine.h:892
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
state_t state
State of lock.
#define ITT_NOTIFY(name, obj)
Definition: itt_notify.h:120
static const state_t 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 140 of file spin_rw_mutex.cpp.

141 {
142  // for a reader: acquire if no active or waiting writers
143  state_t s = state;
144  if( !(s & (WRITER|WRITER_PENDING)) ) { // no writers
145  state_t t = (state_t)__TBB_FetchAndAddW( &state, (intptr_t) ONE_READER );
146  if( !( t&WRITER )) { // got the lock
147  ITT_NOTIFY(sync_acquired, this);
148  return true; // successfully stored increased number of readers
149  }
150  // writer got there first, undo the increment
151  __TBB_FetchAndAddW( &state, -(intptr_t)ONE_READER );
152  }
153  return false;
154 }
static const state_t ONE_READER
static const state_t WRITER
static const state_t WRITER_PENDING
state_t state
State of lock.
#define ITT_NOTIFY(name, obj)
Definition: itt_notify.h:120
void const char const char int ITT_FORMAT __itt_group_sync s

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 127 of file spin_rw_mutex.cpp.

128 {
129  // for a writer: only possible to acquire if no active readers or writers
130  state_t s = state;
131  if( !(s & BUSY) ) // no readers, no writers; mask is 1..1101
132  if( CAS(state, WRITER, s)==s ) {
133  ITT_NOTIFY(sync_acquired, this);
134  return true; // successfully stored writer flag
135  }
136  return false;
137 }
static const state_t BUSY
static T CAS(volatile T &addr, T newv, T oldv)
static const state_t WRITER
state_t state
State of lock.
#define ITT_NOTIFY(name, obj)
Definition: itt_notify.h:120
void const char const char int ITT_FORMAT __itt_group_sync s

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 86 of file spin_rw_mutex.cpp.

87 {
88  state_t s = state;
89  __TBB_ASSERT( s & READERS, "invalid state before upgrade: no readers " );
90  // check and set writer-pending flag
91  // required conditions: either no pending writers, or we are the only reader
92  // (with multiple readers and pending writer, another upgrade could have been requested)
93  while( (s & READERS)==ONE_READER || !(s & WRITER_PENDING) ) {
94  state_t old_s = s;
95  if( (s=CAS(state, s | WRITER | WRITER_PENDING, s))==old_s ) {
96  ITT_NOTIFY(sync_prepare, this);
97  internal::atomic_backoff backoff;
98  while( (state & READERS) != ONE_READER ) backoff.pause();
99  __TBB_ASSERT((state&(WRITER_PENDING|WRITER))==(WRITER_PENDING|WRITER),"invalid state when upgrading to writer");
100  // both new readers and writers are blocked at this time
101  __TBB_FetchAndAddW( &state, - (intptr_t)(ONE_READER+WRITER_PENDING));
102  ITT_NOTIFY(sync_acquired, this);
103  return true; // successfully upgraded
104  }
105  }
106  // slow reacquire
108  return internal_acquire_writer(); // always returns false
109 }
void __TBB_EXPORTED_METHOD internal_release_reader()
Internal release read lock.
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:169
bool __TBB_EXPORTED_METHOD internal_acquire_writer()
Internal acquire write lock.
static T CAS(volatile T &addr, T newv, T oldv)
static const state_t ONE_READER
static const state_t WRITER
static const state_t WRITER_PENDING
state_t state
State of lock.
#define ITT_NOTIFY(name, obj)
Definition: itt_notify.h:120
void const char const char int ITT_FORMAT __itt_group_sync s
static const state_t READERS

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

Here is the call graph for this function:

◆ lock()

void tbb::spin_rw_mutex_v3::lock ( )
inline

Acquire writer lock.

Definition at line 184 of file spin_rw_mutex.h.

bool __TBB_EXPORTED_METHOD internal_acquire_writer()
Internal acquire write lock.

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 204 of file spin_rw_mutex.h.

void __TBB_EXPORTED_METHOD internal_acquire_reader()
Internal acquire read lock.

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 188 of file spin_rw_mutex.h.

188 {return internal_try_acquire_writer();}
bool __TBB_EXPORTED_METHOD internal_try_acquire_writer()
Internal try_acquire write lock.

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 208 of file spin_rw_mutex.h.

208 {return internal_try_acquire_reader();}
bool __TBB_EXPORTED_METHOD internal_try_acquire_reader()
Internal try_acquire read lock.

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 191 of file spin_rw_mutex.h.

191  {
192 #if TBB_USE_THREADING_TOOLS||TBB_USE_ASSERT
195 #else
197  else __TBB_FetchAndAddWrelease( &state, -(intptr_t)ONE_READER);
198 #endif /* TBB_USE_THREADING_TOOLS||TBB_USE_ASSERT */
199  }
void __TBB_EXPORTED_METHOD internal_release_reader()
Internal release read lock.
#define __TBB_FetchAndAddWrelease(P, V)
Definition: tbb_machine.h:313
void __TBB_AtomicAND(volatile void *operand, uintptr_t addend)
Definition: tbb_machine.h:892
static const state_t ONE_READER
static const state_t WRITER
state_t state
State of lock.
void __TBB_EXPORTED_METHOD internal_release_writer()
Out of line code for releasing a write lock.
static const state_t READERS

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 216 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 179 of file spin_rw_mutex.h.

◆ is_recursive_mutex

const bool tbb::spin_rw_mutex_v3::is_recursive_mutex = false
static

Definition at line 178 of file spin_rw_mutex.h.

◆ is_rw_mutex

const bool tbb::spin_rw_mutex_v3::is_rw_mutex = true
static

Definition at line 177 of file spin_rw_mutex.h.

◆ ONE_READER

◆ READERS

◆ 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 221 of file spin_rw_mutex.h.

Referenced by 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

◆ WRITER_PENDING

const state_t tbb::spin_rw_mutex_v3::WRITER_PENDING = 2
staticprotected

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

Copyright © 2005-2019 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.