curator-recipes/src/site/confluence/shared-reentrant-read-write-lock.confluence

h1. Shared Reentrant Read Write Lock

h2. Description
A re\-entrant read/write mutex that works across JVMs. Uses Zookeeper to hold the lock. All processes in all
JVMs that use the same lock path will achieve an inter\-process critical section. Further, this mutex is "fair" -
each user will get the mutex in the order requested (from ZK's point of view).

A read write lock maintains a pair of associated locks, one for read\-only operations and one for writing. The read
lock may be held simultaneously by multiple reader processes, so long as there are no writers. The write lock is exclusive.

_Reentrancy_
This lock allows both readers and writers to reacquire read or write locks in the style of a re\-entrant lock.
Non\-re\-entrant readers are not allowed until all write locks held by the writing thread/process have been released.
Additionally, a writer can acquire the read lock, but not vice\-versa. If a reader tries to acquire the write lock it will never succeed.

_Lock Downgrading_
Re\-entrancy also allows downgrading from the write lock to a read lock, by acquiring the write lock, then the read
lock and then releasing the write lock. However, upgrading from a read lock to the write lock is not possible.

h2. Participating Classes
* InterProcessReadWriteLock
* InterProcessLock

h2. Usage
h3. Create an InterProcessReadWriteLock
{code}
public InterProcessReadWriteLock(CuratorFramework client,
                                 String basePath)
Parameters:
client - the client
basePath - path to use for locking
{code}

h3. General Usage
Access either the read lock or the write lock and then use the methods as described for [[Shared lock|shared-lock.html]].

{code}
public InterProcessLock readLock()

public InterProcessLock writeLock()
{code}

h2. Error Handling
It is strongly recommended that you add a {{ConnectionStateListener}} and watch for SUSPENDED and
LOST state changes. If a SUSPENDED state is reported you cannot be certain that you still hold the lock unless you
subsequently receive a RECONNECTED state. If a LOST state is reported it is certain that you no longer hold the lock.