pt.ua.concurrent
Class Mutex

java.lang.Object
  pt.ua.concurrent.CObject
      pt.ua.concurrent.Mutex

All Implemented Interfaces:

InterruptibleAwaitingThreads, Sync, SyncCV

public class Mutex
extends CObject
implements Sync

Mutual exclusion lock.

This class implements a mutual exclusion scheme between threads.

The correct algorithm pattern to use Mutex objects should use try/finally blocks:

    mtx.lock();
    try
    {
       ...
    }
    finally
    {
       mtx.unlock();
    }
 

This class follows DbC(tm) methodology (Wikipedia). Where possible, contracts are implement with native's Java assert.

Version:

0.5, November 2011, 0.6, October 2013

Author:

Miguel Oliveira e Silva (mos@ua.pt)

Nested Class Summary

static class

Mutex.Priority Locking priority choices: UNDEFINED: undefined priority (default); TIME_OF_ARRIVAL: priority ordered by decreasing waiting time (not yet implemented!).

Constructor Summary

Mutex()
Constructs a new non-recursive Mutex with UNDEFINED priority and registering waiting threads.

Mutex(boolean recursive)
Constructs a new Mutex with UNDEFINED priority and registering waiting threads.

Mutex(boolean recursive, boolean registerAwaitingThreads)
Constructs a new Mutex with UNDEFINED priority.

Method Summary

SyncState	getStateAndUnlock() Get current Sync state, and unlock it (if applicable).
void	lock() Locks mutex.
int	lockCount() Lock count of current mutex.
boolean	lockIsMine() Is lock owned by me?
MutexCV	newCV() Create and return a new condition variable attached to current Mutex.
void	recoverState(SyncState state) Recover Sync state.
boolean	recursive() Is current mutex recursive?
boolean	trylock() Try to lock mutex (without waiting).
void	unlock() Unlocks mutex.

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

Mutex

public Mutex()

Constructs a new non-recursive Mutex with UNDEFINED priority and registering waiting threads.

Mutex

public Mutex(boolean recursive)

Constructs a new Mutex with UNDEFINED priority and registering waiting threads.

Parameters:

recursive - if true, the created mutex will be recursive (non-recursive, if false)

Mutex

public Mutex(boolean recursive,
             boolean registerAwaitingThreads)

Constructs a new Mutex with UNDEFINED priority.

Parameters:

recursive - if true, the created mutex will be recursive (non-recursive, if false)

registerAwaitingThreads - if true, threads are registered when waiting

Method Detail

lock

public void lock()

Locks mutex.

Precondition:

!lockIsMine() || recursive() - not own lock unless if recursive

Postcondition:

lockIsMine() - lock is mine

trylock

public boolean trylock()

Try to lock mutex (without waiting).

Precondition:

!lockIsMine() || recursive() - not own lock unless if recursive

Postcondition:

result && lockIsMine() || !result && !lockIsMine()

Returns:

true, if mutex locked, false otherwise

unlock

public void unlock()

Unlocks mutex.

Precondition:

lockIsMine()

Postcondition:

!lockIsMine() || lockCount() > 0

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

recursive

public boolean recursive()

Is current mutex recursive?

Returns:

true, if mutex is recursive

lockCount

public int lockCount()

Lock count of current mutex.

Precondition:

lockIsMine()

Returns:

the count value

newCV

public MutexCV newCV()

Create and return a new condition variable attached to current Mutex.

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