class Concurrent::ReentrantReadWriteLock

Re-entrant read-write lock implementation

Allows any number of concurrent readers, but only one concurrent writer (And while the “write” lock is taken, no read locks can be obtained either. Hence, the write lock can also be called an “exclusive” lock.)

If another thread has taken a read lock, any thread which wants a write lock will block until all the readers release their locks. However, once a thread starts waiting to obtain a write lock, any additional readers that come along will also wait (so writers are not starved).

A thread can acquire both a read and write lock at the same time. A thread can also acquire a read lock OR a write lock more than once. Only when the read (or write) lock is released as many times as it was acquired, will the thread actually let it go, allowing other threads which might have been waiting to proceed. Therefore the lock can be upgraded by first acquiring read lock and then write lock and that the lock can be downgraded by first having both read and write lock a releasing just the write lock.

If both read and write locks are acquired by the same thread, it is not strictly necessary to release them in the same order they were acquired. In other words, the following code is legal:

@example

lock = Concurrent::ReentrantReadWriteLock.new
lock.acquire_write_lock
lock.acquire_read_lock
lock.release_write_lock
# At this point, the current thread is holding only a read lock, not a write
# lock. So other threads can take read locks, but not a write lock.
lock.release_read_lock
# Now the current thread is not holding either a read or write lock, so
# another thread could potentially acquire a write lock.

This implementation was inspired by ‘java.util.concurrent.ReentrantReadWriteLock`.

@example

lock = Concurrent::ReentrantReadWriteLock.new
lock.with_read_lock  { data.retrieve }
lock.with_write_lock { data.modify! }

@see docs.oracle.com/javase/7/docs/api/java/util/concurrent/locks/ReentrantReadWriteLock.html java.util.concurrent.ReentrantReadWriteLock