pt.ua.concurrent
Class 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

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

RWEx()
Constructs a new non-recursive RWEx with WRITER priority and registering waiting threads.

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.

Method Summary

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	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.
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(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

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

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()

Postcondition:

readerLockIsMine()

tryToChangeToWriter

public boolean tryToChangeToWriter()

Attempts to change from a reader lock to a writer lock.

Precondition:

readerLockIsMine()

Postcondition:

result && writerLockIsMine() || !result && readerLockIsMine()

Returns:

true, if lock change succeeds, false otherwise