pt.ua.concurrent
Class GroupMutex

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

All Implemented Interfaces:

InterruptibleAwaitingThreads, Sync, SyncCV

public class GroupMutex
extends CObject
implements Sync

Group mutex.

This class implements a group mutual exclusion scheme in which threads within the same (active) group can proceed concurrently, and threads from other groups are required to wait until their group becomes active.

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

    gmtx.lock(group);
    try
    {
       ...
    }
    finally
    {
       gmtx.unlock(group);
    }
 

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

Author:

Miguel Oliveira e Silva (mos@ua.pt)

Nested Class Summary

static class

GroupMutex.Priority Locking priority choices: CURRENT_ACTIVE_GROUP: active group is always preferred; GROUP_NUMBER_INCREASING: the higher the group number the higher its priority; GROUP_NUMBER_DECREASING: the lower the group number the higher its priority; TIME_OF_ARRIVAL: priority ordered by decreasing waiting time (not yet implemented!).

Constructor Summary

GroupMutex(int numberOfGroups)
Constructs a new GroupMutex with numberOfGroups groups and CURRENT_ACTIVE_GROUP priority.

GroupMutex(int numberOfGroups, GroupMutex.Priority priority)
Constructs a new GroupMutex with numberOfGroups groups and with a selected priority.

GroupMutex(int numberOfGroups, GroupMutex.Priority priority, boolean registerAwaitingThreads)
Constructs a new GroupMutex with numberOfGroups groups and with a selected priority.

Method Summary

int	activeGroup() Current active group (unsafe operation if lock is owned by the caller thread).
void	changePriority(GroupMutex.Priority priority) Change current lock priority.
SyncState	getStateAndUnlock() Get current Sync state, and unlock it (if applicable).
void	lock(int group) Lock to a group waiting until succeeds, or is interrupted.
boolean	lockIsMine() Is lock owned by me?
GroupMutexCV	newCV() Create and return a new condition variable attached to current GroupMutex.
GroupMutexComposedCV	newCV(Sync[] list) Create and return a new composed condition variable attached to current GroupMutex and to an array of Sync's.
int	numberOfGroups() Number of groups.
GroupMutex.Priority	priority() Current lock priority.
void	recoverState(SyncState state) Recover Sync state.
boolean	tryLock(int group) Attempt to lock a group (no waiting involved).
void	unlock(int group) Unlocks from a group.

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

GroupMutex

public GroupMutex(int numberOfGroups)

Constructs a new GroupMutex with numberOfGroups groups and CURRENT_ACTIVE_GROUP priority.

Precondition:

numberOfGroups >= 2

Parameters:

numberOfGroups - number of groups

GroupMutex

public GroupMutex(int numberOfGroups,
                  GroupMutex.Priority priority)

Constructs a new GroupMutex with numberOfGroups groups and with a selected priority.

Precondition:

numberOfGroups >= 2

Parameters:

numberOfGroups - number of groups

priority - locking priority

GroupMutex

public GroupMutex(int numberOfGroups,
                  GroupMutex.Priority priority,
                  boolean registerAwaitingThreads)

Constructs a new GroupMutex with numberOfGroups groups and with a selected priority.

Precondition:

numberOfGroups >= 2

Parameters:

numberOfGroups - number of groups

priority - locking priority

registerAwaitingThreads - if true, threads are registered when waiting

Method Detail

priority

public GroupMutex.Priority priority()

Current lock priority.

Returns:

lock priority

changePriority

public void changePriority(GroupMutex.Priority priority)

Change current lock priority.

Parameters:

priority - locking priority

numberOfGroups

public int numberOfGroups()

Number of groups.

Returns:

number of groups

activeGroup

public int activeGroup()

Current active group (unsafe operation if lock is owned by the caller thread).

Precondition:

lockIsMine()

Returns:

current lock group

lock

public void lock(int group)

Lock to a group waiting until succeeds, or is interrupted.

Precondition:

group >= 1 && group <= numberOfGroups()

!lockIsMine()

Postcondition:

lockIsMine() && activeGroup() == group

Parameters:

group - group number

tryLock

public boolean tryLock(int group)

Attempt to lock a group (no waiting involved).

Precondition:

group >= 1 && group <= numberOfGroups()

!lockIsMine()

Postcondition:

!result || (lockIsMine() && activeGroup() == group)

Parameters:

group - group number

Returns:

true if lock succeeds, otherwise it returns false

unlock

public void unlock(int group)

Unlocks from a group.

Precondition:

group >= 1 && group <= numberOfGroups()

lockIsMine() && activeGroup() == group

Postcondition:

!lockIsMine()

Parameters:

group - group number

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

newCV

public GroupMutexCV newCV()

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

Specified by:

newCV in interface Sync

Returns:

the new condition variable

newCV

public GroupMutexComposedCV newCV(Sync[] list)

Create and return a new composed condition variable attached to current GroupMutex and to an array of Sync's.

Precondition:

GroupMutexComposedCV.validList(list)

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