org.iges.util
Class ExclusiveLock

java.lang.Object
  |
  +--org.iges.util.ExclusiveLock

All Implemented Interfaces:

Lock

public class ExclusiveLock

extends java.lang.Object

implements Lock

An extension of the thread-lock concept which supports the concept of exclusive vs non-exclusive locking. This concept is a way to eliminate unnecessary thread blocks on operations that do not modify an object's state.

Non-exclusive locks may be simultaneously held on the same Locker by any number of threads.

In contrast, only one thread at a time may hold an exclusive lock, and the granting of an exclusive lock guarantees that all non-exclusive locks have been released.

Furthermore, requests for exclusive locks take priority over requests for non-exclusive locks.

The envisioned use of this system is to require exclusive locks for all state-change operations on an object, and non-exclusive locks for all state-query operations. It is then possible to guarantee that:

1) any number of threads may simultaneously query the object's state
2) no two threads can simultaneously attempt to change the object's state
3) the object will never change state while it is being queried
4) any thread can temporarily block the initiation of new query operations in order to change the Object's state

One important difference between the ExclusiveLock mechanism and Java's synchronized blocks is that for efficiency reasons, ExclusiveLock does not keep track of nested of lock/release operations.

It is therefore important to avoid redundant locking. For instance the following code will not work as desired: protected ExclusiveLock synch = new ExclusiveLock(); public void foo() { synch.lock(); // do something synch.release(); } public void bar() { synch.lock(); // do op 1 foo(); // lock has been released when foo returns! // do op 2 // op 2 is operating without a lock synch.release(); // not what we wanted.. }

Field Summary

protected java.lang.Thread	exclusive
protected java.util.Set	locks

Constructor Summary

ExclusiveLock()
Creates a new ExclusiveLock

ExclusiveLock(int expectedMaxLocks)
Creates a new ExclusiveLock with sufficient storage for the expected maximum number of non-exclusive locks, to prevent frequent reallocation of internal storage.

Method Summary

boolean	isLocked()
boolean	isLockedExclusive()
void	lock() Obtains a non-exclusive lock for the current thread, blocking until the lock is available.
void	lockExclusive() Obtains an exclusive lock for the current thread, blocking until the lock is available.
void	release() Releases the current thread's lock.
java.lang.String	toString() Prints a list of the threads that currently own locks on this object.
boolean	tryLock() Tries to obtain a non-exclusive lock for the current thread.
boolean	tryLockExclusive() Tries to obtain an exclusive lock for the current thread.
boolean	tryLockExclusive(long timeout) Tries to obtain an exclusive lock for the current thread.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

exclusive

protected java.lang.Thread exclusive

locks

protected java.util.Set locks

Constructor Detail

ExclusiveLock

public ExclusiveLock()

Creates a new ExclusiveLock

ExclusiveLock

public ExclusiveLock(int expectedMaxLocks)

Creates a new ExclusiveLock with sufficient storage for the expected maximum number of non-exclusive locks, to prevent frequent reallocation of internal storage.

Method Detail

lockExclusive

public void lockExclusive()

Obtains an exclusive lock for the current thread, blocking until the lock is available. Requests for non-exclusive locks will block starting from when this method is called (not from when it returns), until the resulting exclusive lock is released. If the current thread already owns an exclusive lock, does nothing.

isLockedExclusive

public boolean isLockedExclusive()

Returns:

True if the current thread owns an exclusive lock.

tryLockExclusive

public boolean tryLockExclusive()

Tries to obtain an exclusive lock for the current thread. This method always returns immediately but does not guarantee that the lock will be obtained. If the current thread already owns an exclusive lock, does nothing.

Returns:

True if the exclusive lock was succesfully obtained.

tryLockExclusive

public boolean tryLockExclusive(long timeout)

Tries to obtain an exclusive lock for the current thread. This method will return within the timeout given, more or less, but does not guarantee that the lock will be obtained. If the current thread already owns an exclusive lock, does nothing.

Parameters:

timeout - Maximum time in milliseconds to wait for an exclusive lock

Returns:

True if the exclusive lock was succesfully obtained.

isLocked

public boolean isLocked()

Specified by:

isLocked in interface Lock

Returns:

True if the current thread owns a non-exclusive lock.

lock

public void lock()

Obtains a non-exclusive lock for the current thread, blocking until the lock is available. If the current thread already owns a non-exclusive lock, does nothing.

Specified by:

lock in interface Lock

release

public void release()

Releases the current thread's lock. If the current thread does not own a lock, does nothing.

Specified by:

release in interface Lock

tryLock

public boolean tryLock()

Tries to obtain a non-exclusive lock for the current thread. This method always returns immediately but does not guarantee that the lock will be obtained. If the current thread already owns a non-exclusive lock, does nothing.

Specified by:

tryLock in interface Lock

Returns:

True if a non-exclusive was succesfully obtained.

toString

public java.lang.String toString()

Prints a list of the threads that currently own locks on this object.

Overrides:

toString in class java.lang.Object