RWEx

java.lang.Object
- pt.ua.concurrent.CObject
- - pt.ua.concurrent.RWEx

All Implemented Interfaces:

InterruptibleAwaitingThreads, Sync, SyncCV
```
public class RWEx
extends CObject
implements Sync
```
Readers-writer exclusion class.
The correct algorithm pattern to use RWEx objects should use try/finally blocks:
```
    rwex.lockWriter(); // rwex.lockReader();
    try
    {
       ...
    }
    finally
    {
       rwex.unlockWriter(); // rwex.unlockReader(); // rwex.unlock();
    }
 
```
This class follows DbC(tm) methodology (Wikipedia). Where possible, contracts are implement with native's Java assert.
Version:

0.5, November 2011

Author:

Miguel Oliveira e Silva (mos@ua.pt)

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`RWEx.Priority` Locking priority choices: WRITER: priority to writers (a waiting writer prevents new readers from getting the lock); READERS: priority to readers (a waiting reader prevents new writers from getting the lock); TIME_OF_ARRIVAL: priority ordered by decreasing waiting time (not yet implemented!).

Constructor Summary

Constructors
Constructor and Description
`RWEx()` Constructs a new non-recursive RWEx with WRITER priority and registering waiting threads.
`RWEx(boolean recursive, boolean registerAwaitingThreads)` Constructs a new RWEx with WRITER priority.
`RWEx(RWEx.Priority priority)` Constructs a new non-recursive RWEx registering waiting threads.
`RWEx(RWEx.Priority priority, boolean registerAwaitingThreads)` Constructs a new non-recursive RWEx.
`RWEx(RWEx.Priority priority, boolean recursive, boolean registerAwaitingThreads)` Constructs a new RWEx.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`changePriority(RWEx.Priority priority)` Change current priority.
`void`	`changeToReader()` Change from a writer lock to a reader lock.
`SyncState`	`getStateAndUnlock()` Get current Sync state, and unlock it (if applicable).
`boolean`	`lockIsMine()` Is lock owned by me?
`void`	`lockReader()` Reader lock.
`void`	`lockWriter()` Writer lock.
`RWExCV`	`newCV()` Create and return a new condition variable attached to current RWEx.
`RWEx.Priority`	`priority()` Current priority.
`boolean`	`readerLockIsMine()` Is reader lock owned by me?
`void`	`recoverState(SyncState state)` Recover Sync state.
`boolean`	`recursive()` Is current rwex recursive?
`boolean`	`trylockReader()` Try to lock as a reader (without waiting).
`boolean`	`trylockWriter()` Try to lock as a writer (without waiting).
`boolean`	`tryToChangeToWriter()` Attempts to change from a reader lock to a writer lock.
`void`	`unlock()` Unlocks active lock (which might be either a reader or a writer lock).
`void`	`unlockReader()` Unlocks reader.
`void`	`unlockWriter()` Unlocks writer.
`int`	`writerLockCount()` Writer lock count of current lock.
`boolean`	`writerLockIsMine()` Is writer lock owned by me?

Methods inherited from class pt.ua.concurrent.CObject
await, await, await, broadcast, interruptWaitingThreads, registerAwaitingThreads, signal, syncronizedLockIsMine

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface pt.ua.concurrent.InterruptibleAwaitingThreads
interruptWaitingThreads, registerAwaitingThreads

- Constructor Detail
  - RWEx
```
public RWEx()
```
    Constructs a new non-recursive RWEx with WRITER priority and registering waiting threads.
  - RWEx
```
public RWEx(boolean recursive,
            boolean registerAwaitingThreads)
```
    Constructs a new RWEx with WRITER priority.
    
    Parameters:
    
    recursive - if true, the created rwex will be recursive (non-recursive, if false)
    
    registerAwaitingThreads - if true, threads are registered when waiting
  - RWEx
```
public RWEx(RWEx.Priority priority)
```
    Constructs a new non-recursive RWEx registering waiting threads.
    
    Parameters:
    
    priority - waiting priority (WRITER or READERS)
  - RWEx
```
public RWEx(RWEx.Priority priority,
            boolean registerAwaitingThreads)
```
    Constructs a new non-recursive RWEx.
    
    Parameters:
    
    priority - waiting priority (WRITER or READERS)
    
    registerAwaitingThreads - if true, threads are registered when waiting
  - RWEx
```
public RWEx(RWEx.Priority priority,
            boolean recursive,
            boolean registerAwaitingThreads)
```
    Constructs a new RWEx.
    
    Parameters:
    
    priority - waiting priority (WRITER or READERS)
    
    recursive - if true, the created rwex will be recursive (non-recursive, if false)
    
    registerAwaitingThreads - if true, threads are registered when waiting
- Method Detail
  - priority
```
public RWEx.Priority priority()
```
    Current priority.
    
    Returns:
    
    the priority value
  - changePriority
```
public void changePriority(RWEx.Priority priority)
```
    Change current priority.
    
    Parameters:
    
    priority - waiting priority (WRITER or READERS)
  - lockReader
```
public void lockReader()
```
    Reader lock.
    Precondition:
    
    !lockIsMine()
    
    Postcondition:
    
    readerLockIsMine()
  - lockWriter
```
public void lockWriter()
```
    Writer lock.
    Precondition:
    
    !lockIsMine()
    
    Postcondition:
    
    writerLockIsMine()
  - trylockReader
```
public boolean trylockReader()
```
    Try to lock as a reader (without waiting).
    Precondition:
    
    !lockIsMine()
    
    Postcondition:
    
    result && readerLockIsMine() || !result && !readerLockIsMine()
    
    Returns:
    
    true, if locked, false otherwise
  - trylockWriter
```
public boolean trylockWriter()
```
    Try to lock as a writer (without waiting).
    Precondition:
    
    !lockIsMine()
    
    Postcondition:
    
    result && writerLockIsMine() || !result && !writerLockIsMine()
    
    Returns:
    
    true, if locked, false otherwise
  - unlock
```
public void unlock()
```
    Unlocks active lock (which might be either a reader or a writer lock).
    Precondition:
    
    lockIsMine()
    
    Postcondition:
    
    !lockIsMine()
  - unlockReader
```
public void unlockReader()
```
    Unlocks reader.
    Precondition:
    
    readerLockIsMine()
    
    Postcondition:
    
    !lockIsMine()
  - unlockWriter
```
public void unlockWriter()
```
    Unlocks writer.
    Precondition:
    
    writerLockIsMine()
    
    Postcondition:
    
    !lockIsMine()
  - lockIsMine
```
public boolean lockIsMine()
```
    Description copied from class: CObject
    
    Is lock owned by me?
    
    Specified by:
    
    lockIsMine in interface Sync
    
    Specified by:
    
    lockIsMine in interface SyncCV
    
    Overrides:
    
    lockIsMine in class CObject
    
    Returns:
    
    true, if lock is mine
  - readerLockIsMine
```
public boolean readerLockIsMine()
```
    Is reader lock owned by me?
    
    Returns:
    
    true, if lock is mine
  - writerLockIsMine
```
public boolean writerLockIsMine()
```
    Is writer lock owned by me?
    
    Returns:
    
    true, if lock is mine
  - recursive
```
public boolean recursive()
```
    Is current rwex recursive?
    
    Returns:
    
    true, if rwex is recursive
  - writerLockCount
```
public int writerLockCount()
```
    Writer lock count of current lock.
    Precondition:
    
    writerLockIsMine()
    
    Returns:
    
    the count value
  - newCV
```
public RWExCV newCV()
```
    Create and return a new condition variable attached to current RWEx.
    
    Specified by:
    
    newCV in interface Sync
    
    Returns:
    
    the new condition variable
  - getStateAndUnlock
```
public SyncState getStateAndUnlock()
```
    Description copied from interface: Sync
    
    Get current Sync state, and unlock it (if applicable). (Internal service).
    Precondition:
    
    lockIsMine()
    
    Specified by:
    
    getStateAndUnlock in interface Sync
    
    Returns:
    
    the Sync state object.
  - recoverState
```
public void recoverState(SyncState state)
                  throws ThreadInterruptedException
```
    Description copied from interface: Sync
    
    Recover Sync state. (Internal service).
    Precondition:
    
    state != null && state.obj() == this - my state object required
    
    !lockIsMine()
    
    Specified by:
    
    recoverState in interface Sync
    
    Parameters:
    
    state - Sync state object (returned by getStateAndUnlock)
    
    Throws:
    
    ThreadInterruptedException
  - changeToReader
```
public void changeToReader()
```
    Change from a writer lock to a reader lock.
    Precondition:
    
    writerLockIsMine()
    
    !recursive() || writerLockCount() == 1
    
    Postcondition:
    
    readerLockIsMine()
  - tryToChangeToWriter
```
public boolean tryToChangeToWriter()
```
    Attempts to change from a reader lock to a writer lock.
    Precondition:
    
    readerLockIsMine()
    
    !recursive()
    
    Postcondition:
    
    result && writerLockIsMine() || !result && readerLockIsMine()
    
    Returns:
    
    true, if lock change succeeds, false otherwise

Class RWEx

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class pt.ua.concurrent.CObject

Methods inherited from class java.lang.Object

Methods inherited from interface pt.ua.concurrent.InterruptibleAwaitingThreads

Constructor Detail

RWEx

RWEx

RWEx

RWEx

RWEx

Method Detail

priority

changePriority

lockReader

lockWriter

trylockReader

trylockWriter

unlock

unlockReader

unlockWriter

lockIsMine

readerLockIsMine

writerLockIsMine

recursive

writerLockCount

newCV

getStateAndUnlock

recoverState

changeToReader

tryToChangeToWriter