ewe.sys
Class Lock

java.lang.Object
  ewe.sys.Lock

public class Lock

extends Object

This allows only a single mThread/Coroutine to hold a Lock at a time.

Field Summary

boolean

multipleEntry If this is true then a thread can call hold()/grab() on a lock multiple times - defaults to true.

Constructor Summary

Lock()

Method Summary

boolean	grab() This tries to get ownership of the lock, but will not wait if it cannot get ownership immediately.
boolean	grabAndNotify(boolean doNotifyAll) This grabs the lock, notifies waiting threads and then releases the lock.
boolean	hold() Deprecated. use lock() instead.
boolean	hold(TimeOut t) Deprecated. use lock(TimeOut t) instead.
boolean	holdAndNotify(TimeOut howLong, boolean doNotifyAll) This grabs the lock, notifies waiting threads and then releases the lock.
void	lock() Attempt to acquire ownership of the Lock, waiting indefinitely.
boolean	lock(TimeOut t) Attempt to acquire ownership of the Lock, waiting for a specific length of time.
void	notifyAllWaiting() This causes all Coroutines which are waiting on the lock to wakeup and attempt to reacquire ownership of the lock.
void	notifyWaiting() This causes one Coroutine which is waiting on the lock to wakeup and reacquire ownership of the lock.
boolean	release() Release the lock.
void	synchronize() This attempts to hold the lock, waiting an indefinite time to do so.
void	unlock() Release the lock.
boolean	wait(TimeOut howLong) Deprecated. - use waitOn(TimeOut howLong) instead.
void	waitOn() This causes the current mThread, which must own the lock, to release it and wait indefinitely until notifyWaiting() is called on the lock.
boolean	waitOn(int milliSeconds) This causes the current mThread, which must own the lock, to release it and wait until notifyWaiting() is called on the lock.
boolean	waitOn(TimeOut howLong) This causes the current mThread, which must own the lock, to release it and wait until notifyWaiting() is called on the lock.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

multipleEntry

public boolean multipleEntry

If this is true then a thread can call hold()/grab() on a lock multiple times - defaults to true. There must be a matching release() call for every hold()/grab() call.

Constructor Detail

Lock

public Lock()

Method Detail

synchronize

public void synchronize()

This attempts to hold the lock, waiting an indefinite time to do so. Unlike the hold/grab methods, this method returns no value and will throw a run-time exception if the lock could not be held for any reason (since this will represent a severe error).

grab

public boolean grab()

This tries to get ownership of the lock, but will not wait if it cannot get ownership immediately. It returns true if it got ownership, false if it did not. This method CAN be called by threads of execution which are NOT mThreads since it never attempts to wait for ownership. There must be a matching release() for every grab().

Returns:

true if the lock was acquired - false if not.

hold

public boolean hold(TimeOut t)

Deprecated. use lock(TimeOut t) instead.

Use this to get exclusive ownership of the Lock. It returns true if it managed to gain ownership within the TimOut period, false if it did not. If the calling mThread already owns the lock AND multipleEntry is set true, then it will immediately return true. There must be a matching release() call for every hold()/grab() call.

Parameters:

t - A Timeout specifying how long to wait to acquire the lock. Set to TimeOut.Forever to wait indefinitely.

Returns:

true if the lock was acquired - false if not.

hold

public boolean hold()

Deprecated. use lock() instead.

This does a hold() with a TimeOut of TimeOut.Forever. Use this to get exclusive ownership of the Lock. It returns true if it managed to gain ownership within the TimOut period, false if it did not. If the calling mThread already owns the lock AND multipleEntry is set true, then it will immediately return true. There must be a matching release() call for every hold()/grab() call.

Returns:

true if the lock was acquired - false if not.

lock

public boolean lock(TimeOut t)
             throws InterruptedException

Attempt to acquire ownership of the Lock, waiting for a specific length of time. A non-mThread thread can call this if the TimeOut is TimeOut.Immediate, in which case this acts as a grab() call.

Parameters:

t - The length of time to wait for.

Returns:

true if it acquired the lock, false if it did not.

Throws:

InterruptedException - If the Thread was interrupted.

lock

public void lock()
          throws InterruptedException

Attempt to acquire ownership of the Lock, waiting indefinitely.

Throws:

InterruptedException - If the Thread was interrupted while waiting for the lock.

release

public boolean release()

Release the lock. This can only be called by the owning thread. This is the same as unlock() except unlock will throw an exception if the calling thread is not the lock owner.

unlock

public void unlock()
            throws IllegalThreadStateException

Release the lock. This can only be called by the owning thread. This is the same as unlock() except unlock will throw an exception if the calling thread is not the lock owner.

Throws:

IllegalThreadStateException

wait

public boolean wait(TimeOut howLong)

Deprecated. - use waitOn(TimeOut howLong) instead.

This causes the current mThread, which must own the lock, to release it and wait until notify() is called on the lock. It returns true if it was notified before the TimeOut expired, false otherwise. Once it has been notified or the TimeOut has expired it will wait until it can reacquire the lock before returning.

This can ONLY be called by a Coroutine/mThread.

Parameters:

howLong - The length of time to wait. You can use TimeOut.Forever to wait indefinitely.

Returns:

true if it was notified before timing out, false if it timed out before being notified.

waitOn

public boolean waitOn(int milliSeconds)
               throws InterruptedException

This causes the current mThread, which must own the lock, to release it and wait until notifyWaiting() is called on the lock. Once it has been notified or the TimeOut has expired or it was interrupted it will wait until it can reacquire the lock before returning.

Parameters:

milliSeconds - The length of time to wait in milliseconds.

Returns:

true if it was notified, false if it timed out before being notified.

Throws:

InterruptedException - If the Thread was interrupted while waiting.

waitOn

public void waitOn()
            throws InterruptedException

This causes the current mThread, which must own the lock, to release it and wait indefinitely until notifyWaiting() is called on the lock. Once it has been notified or it was interrupted it will wait until it can reacquire the lock before returning.

Throws:

InterruptedException - If the Thread was interrupted while waiting.

waitOn

public boolean waitOn(TimeOut howLong)
               throws InterruptedException

This causes the current mThread, which must own the lock, to release it and wait until notifyWaiting() is called on the lock. Once it has been notified or the TimeOut has expired or it was interrupted it will wait until it can reacquire the lock before returning.

Parameters:

howLong - The length of time to wait. You can use TimeOut.Forever to wait indefinitely.

Returns:

true if it was notified, false if it timed out before being notified.

Throws:

InterruptedException - If the Thread was interrupted while waiting.

notifyWaiting

public void notifyWaiting()

This causes one Coroutine which is waiting on the lock to wakeup and reacquire ownership of the lock.

notifyAllWaiting

public void notifyAllWaiting()

This causes all Coroutines which are waiting on the lock to wakeup and attempt to reacquire ownership of the lock.

grabAndNotify

public boolean grabAndNotify(boolean doNotifyAll)

This grabs the lock, notifies waiting threads and then releases the lock. Since the grab() method is used, it will never block.

Parameters:

doNotifyAll - if this is true then a notifyAllWaiting() will be done, otherwise a notifyWaiting() will be done.

Returns:

true on success, false on failure.

holdAndNotify

public boolean holdAndNotify(TimeOut howLong,
                             boolean doNotifyAll)

This grabs the lock, notifies waiting threads and then releases the lock. This may block while the thread attempts to acquire the lock.

Parameters:

doNotifyAll - if this is true then a notifyAllWaiting() will be done, otherwise a notifyWaiting() will be done.

Returns:

true on success, false on failure.