Intel(R) Threading Building Blocks Doxygen Documentation
version 4.2.3
|
Writer-preference reader-writer lock with local-only spinning on readers. More...
#include <reader_writer_lock.h>
Classes | |
class | scoped_lock |
The scoped lock pattern for write locks. More... | |
class | scoped_lock_read |
The scoped lock pattern for read locks. More... | |
Public Types | |
enum | status_t { waiting_nonblocking, waiting, active, invalid } |
Status type for nodes associated with lock instances. More... | |
Public Member Functions | |
reader_writer_lock () | |
Constructs a new reader_writer_lock. More... | |
~reader_writer_lock () | |
Destructs a reader_writer_lock object. More... | |
void __TBB_EXPORTED_METHOD | lock () |
Acquires the reader_writer_lock for write. More... | |
bool __TBB_EXPORTED_METHOD | try_lock () |
Tries to acquire the reader_writer_lock for write. More... | |
void __TBB_EXPORTED_METHOD | lock_read () |
Acquires the reader_writer_lock for read. More... | |
bool __TBB_EXPORTED_METHOD | try_lock_read () |
Tries to acquire the reader_writer_lock for read. More... | |
void __TBB_EXPORTED_METHOD | unlock () |
Releases the reader_writer_lock. More... | |
Private Member Functions | |
void __TBB_EXPORTED_METHOD | internal_construct () |
void __TBB_EXPORTED_METHOD | internal_destroy () |
bool | start_write (scoped_lock *) |
Attempts to acquire write lock. More... | |
void | set_next_writer (scoped_lock *w) |
Sets writer_head to w and attempts to unblock. More... | |
void | end_write (scoped_lock *) |
Relinquishes write lock to next waiting writer or group of readers. More... | |
bool | is_current_writer () |
Checks if current thread holds write lock. More... | |
void | start_read (scoped_lock_read *) |
Attempts to acquire read lock. More... | |
void | unblock_readers () |
Unblocks pending readers. More... | |
void | end_read () |
Relinquishes read lock by decrementing counter; last reader wakes pending writer. More... | |
![]() | |
no_copy () | |
Allow default construction. More... | |
Private Attributes | |
atomic< scoped_lock_read * > | reader_head |
The list of pending readers. More... | |
atomic< scoped_lock * > | writer_head |
The list of pending writers. More... | |
atomic< scoped_lock * > | writer_tail |
The last node in the list of pending writers. More... | |
tbb_thread::id | my_current_writer |
Writer that owns the mutex; tbb_thread::id() otherwise. More... | |
atomic< uintptr_t > | rdr_count_and_flags |
Status of mutex. More... | |
Friends | |
class | scoped_lock |
class | scoped_lock_read |
Writer-preference reader-writer lock with local-only spinning on readers.
Loosely adapted from Mellor-Crummey and Scott pseudocode at http://www.cs.rochester.edu/research/synchronization/pseudocode/rw.html#s_wp
Definition at line 30 of file reader_writer_lock.h.
Status type for nodes associated with lock instances.
waiting_nonblocking: the wait state for nonblocking lock instances; for writes, these transition straight to active states; for reads, these are unused.
waiting: the start and spin state for all lock instances; these will transition to active state when appropriate. Non-blocking write locks transition from this state to waiting_nonblocking immediately.
active: the active state means that the lock instance holds the lock; it will transition to invalid state during node deletion
invalid: the end state for all nodes; this is set in the destructor so if we encounter this state, we are looking at memory that has already been freed
The state diagrams below describe the status transitions. Single arrows indicate that the thread that owns the node is responsible for the transition; double arrows indicate that any thread could make the transition.
State diagram for scoped_lock status:
waiting -------—> waiting_nonblocking | _____________/ | V V V active --------------—> invalid
State diagram for scoped_lock_read status:
waiting | V active --------------—>invalid
Enumerator | |
---|---|
waiting_nonblocking | |
waiting | |
active | |
invalid |
Definition at line 70 of file reader_writer_lock.h.
|
inline |
Constructs a new reader_writer_lock.
Definition at line 73 of file reader_writer_lock.h.
References internal_construct().
|
inline |
Destructs a reader_writer_lock object.
Definition at line 78 of file reader_writer_lock.h.
References internal_destroy().
|
private |
Relinquishes read lock by decrementing counter; last reader wakes pending writer.
Definition at line 282 of file reader_writer_lock.cpp.
References __TBB_ASSERT, ITT_NOTIFY, tbb::interface5::RC_INCR, rdr_count_and_flags, and sync_releasing.
Referenced by unlock().
|
private |
Relinquishes write lock to next waiting writer or group of readers.
Definition at line 260 of file reader_writer_lock.cpp.
References __TBB_ASSERT, active, tbb::interface5::fetch_and_and(), id, ITT_NOTIFY, my_current_writer, tbb::interface5::reader_writer_lock::scoped_lock::next, rdr_count_and_flags, set_next_writer(), tbb::internal::spin_wait_while_eq(), sync_releasing, unblock_readers(), writer_head, and writer_tail.
Referenced by unlock().
|
private |
Definition at line 71 of file reader_writer_lock.cpp.
References _T, id, ITT_SYNC_CREATE, my_current_writer, rdr_count_and_flags, reader_head, writer_head, and writer_tail.
Referenced by reader_writer_lock().
|
private |
Definition at line 82 of file reader_writer_lock.cpp.
References __TBB_ASSERT, rdr_count_and_flags, reader_head, writer_head, and writer_tail.
Referenced by ~reader_writer_lock().
|
inlineprivate |
Checks if current thread holds write lock.
Definition at line 288 of file reader_writer_lock.cpp.
References tbb::this_tbb_thread::get_id(), and my_current_writer.
Referenced by lock(), lock_read(), try_lock(), try_lock_read(), and unlock().
void tbb::interface5::reader_writer_lock::lock | ( | ) |
Acquires the reader_writer_lock for write.
If the lock is currently held in write mode by another context, the writer will block by spinning on a local variable. Exceptions thrown: improper_lock The context tries to acquire a reader_writer_lock that it already has write ownership of.
Definition at line 93 of file reader_writer_lock.cpp.
References tbb::internal::eid_improper_lock, is_current_writer(), scoped_lock, start_write(), tbb::internal::throw_exception(), and void.
Referenced by tbb::interface5::reader_writer_lock::scoped_lock::internal_construct(), and tbb::interface5::reader_writer_lock::scoped_lock_read::internal_construct().
void tbb::interface5::reader_writer_lock::lock_read | ( | ) |
Acquires the reader_writer_lock for read.
If the lock is currently held by a writer, this reader will block and wait until the writers are done. Exceptions thrown: improper_lock The context tries to acquire a reader_writer_lock that it already has write ownership of.
Definition at line 180 of file reader_writer_lock.cpp.
References tbb::internal::eid_improper_lock, is_current_writer(), start_read(), and tbb::internal::throw_exception().
|
private |
Sets writer_head to w and attempts to unblock.
Definition at line 157 of file reader_writer_lock.cpp.
References __TBB_AtomicOR(), active, tbb::internal::atomic_impl< T >::compare_and_swap(), tbb::interface5::fetch_and_or(), rdr_count_and_flags, tbb::interface5::RFLAG, tbb::interface5::spin_wait_until_and(), tbb::interface5::spin_wait_while_geq(), tbb::interface5::reader_writer_lock::scoped_lock::status, waiting_nonblocking, and writer_head.
Referenced by end_write(), and start_write().
|
private |
Attempts to acquire read lock.
If unavailable, spins in blocking case, returns false in non-blocking case.
Definition at line 209 of file reader_writer_lock.cpp.
References __TBB_ASSERT, active, tbb::interface5::fetch_and_or(), ITT_NOTIFY, tbb::interface5::reader_writer_lock::scoped_lock_read::next, tbb::interface5::RC_INCR, rdr_count_and_flags, reader_head, tbb::internal::spin_wait_while_eq(), tbb::interface5::reader_writer_lock::scoped_lock_read::status, unblock_readers(), and waiting.
Referenced by lock_read().
|
private |
Attempts to acquire write lock.
If unavailable, spins in blocking case, returns false in non-blocking case.
Definition at line 118 of file reader_writer_lock.cpp.
References __TBB_ASSERT, tbb::this_tbb_thread::get_id(), id, ITT_NOTIFY, my_current_writer, tbb::interface5::reader_writer_lock::scoped_lock::next, set_next_writer(), tbb::internal::spin_wait_while_eq(), tbb::interface5::reader_writer_lock::scoped_lock::status, waiting, waiting_nonblocking, writer_head, and writer_tail.
Referenced by lock(), and try_lock().
bool tbb::interface5::reader_writer_lock::try_lock | ( | ) |
Tries to acquire the reader_writer_lock for write.
This function does not block. Return Value: True or false, depending on whether the lock is acquired or not. If the lock is already held by this acquiring context, try_lock() returns false.
Definition at line 107 of file reader_writer_lock.cpp.
References is_current_writer(), scoped_lock, start_write(), tbb::interface5::reader_writer_lock::scoped_lock::status, and waiting_nonblocking.
bool tbb::interface5::reader_writer_lock::try_lock_read | ( | ) |
Tries to acquire the reader_writer_lock for read.
This function does not block. Return Value: True or false, depending on whether the lock is acquired or not.
Definition at line 193 of file reader_writer_lock.cpp.
References is_current_writer(), ITT_NOTIFY, tbb::interface5::RC_INCR, rdr_count_and_flags, and tbb::interface5::WFLAG2.
|
private |
Unblocks pending readers.
Definition at line 228 of file reader_writer_lock.cpp.
References __TBB_ASSERT, __TBB_AtomicOR(), active, head, rdr_count_and_flags, reader_head, tbb::interface5::RFLAG, tbb::interface5::reader_writer_lock::scoped_lock_read::status, and waiting.
Referenced by end_write(), and start_read().
void tbb::interface5::reader_writer_lock::unlock | ( | ) |
Releases the reader_writer_lock.
Definition at line 245 of file reader_writer_lock.cpp.
References __TBB_ASSERT, active, end_read(), end_write(), id, is_current_writer(), my_current_writer, and writer_head.
|
friend |
Definition at line 32 of file reader_writer_lock.h.
Referenced by lock(), and try_lock().
|
friend |
Definition at line 33 of file reader_writer_lock.h.
|
private |
Writer that owns the mutex; tbb_thread::id() otherwise.
Definition at line 217 of file reader_writer_lock.h.
Referenced by end_write(), internal_construct(), is_current_writer(), start_write(), and unlock().
|
private |
Status of mutex.
Definition at line 219 of file reader_writer_lock.h.
Referenced by end_read(), end_write(), internal_construct(), internal_destroy(), set_next_writer(), start_read(), try_lock_read(), and unblock_readers().
|
private |
The list of pending readers.
Definition at line 211 of file reader_writer_lock.h.
Referenced by internal_construct(), internal_destroy(), start_read(), and unblock_readers().
|
private |
The list of pending writers.
Definition at line 213 of file reader_writer_lock.h.
Referenced by end_write(), internal_construct(), internal_destroy(), set_next_writer(), start_write(), and unlock().
|
private |
The last node in the list of pending writers.
Definition at line 215 of file reader_writer_lock.h.
Referenced by end_write(), internal_construct(), internal_destroy(), and start_write().