Merge pull request #416 from Massive-Dynamics/non-reentrant-lock-doc

Add documentation to NonReentrantLock
This commit is contained in:
Norman Maurer 2012-06-28 05:07:17 -07:00
commit a12a99a3dc

View File

@ -20,48 +20,97 @@ import java.util.concurrent.locks.AbstractQueuedSynchronizer;
import java.util.concurrent.locks.Condition; import java.util.concurrent.locks.Condition;
import java.util.concurrent.locks.Lock; import java.util.concurrent.locks.Lock;
/**
* A custom implementation of a lock that does not allow reentry
*/
public final class NonReentrantLock extends AbstractQueuedSynchronizer public final class NonReentrantLock extends AbstractQueuedSynchronizer
implements Lock { implements Lock {
/**
* The serial version unique ID
*/
private static final long serialVersionUID = -833780837233068610L; private static final long serialVersionUID = -833780837233068610L;
/**
* The {@link Thread} that owns this {@link NonReentrantLock}
*/
private Thread owner; private Thread owner;
/**
* Locks this {@link NonReentrantLock}
*/
@Override @Override
public void lock() { public void lock() {
acquire(1); acquire(1);
} }
/**
* Locks this {@link NonReentrantLock}, but allow interruption
*
* @throws InterruptedException The lock was interrupted
*/
@Override @Override
public void lockInterruptibly() throws InterruptedException { public void lockInterruptibly() throws InterruptedException {
acquireInterruptibly(1); acquireInterruptibly(1);
} }
/**
* Try to lock this {@link NonReentrantLock}
*
* @return True if locking was successful, otherwise false
*/
@Override @Override
public boolean tryLock() { public boolean tryLock() {
return tryAcquire(1); return tryAcquire(1);
} }
/**
* Tries to lock this {@link NonReentrantLock} over a period of time
*
* @param time The maximum number of time units to attempt to get a lock for.
* @param unit The {@link TimeUnit} associated with the time parameter
* @return True if the lock was successful, otherwise false
* @throws InterruptedException The locking attempt was interrupted
*/
@Override @Override
public boolean tryLock(long time, TimeUnit unit) public boolean tryLock(long time, TimeUnit unit)
throws InterruptedException { throws InterruptedException {
return tryAcquireNanos(1, unit.toNanos(time)); return tryAcquireNanos(1, unit.toNanos(time));
} }
/**
* Unlocks this {@link NonReentrantLock}
*/
@Override @Override
public void unlock() { public void unlock() {
release(1); release(1);
} }
/**
* Checks to see if this {@link NonReentrantLock} is held by the current {@link Thread}
*
* @return True if held by the current thread, otherwise false
*/
public boolean isHeldByCurrentThread() { public boolean isHeldByCurrentThread() {
return isHeldExclusively(); return isHeldExclusively();
} }
/**
* Creates a new {@link Condition}
*
* @return The condition object
*/
@Override @Override
public Condition newCondition() { public Condition newCondition() {
return new ConditionObject(); return new ConditionObject();
} }
/**
* Try to acquire a lock
*
* @param acquires A number that is sent by acquiring methods
* @return True if a lock is acquired, otherwise false
*/
@Override @Override
protected boolean tryAcquire(int acquires) { protected boolean tryAcquire(int acquires) {
if (compareAndSetState(0, 1)) { if (compareAndSetState(0, 1)) {
@ -71,6 +120,12 @@ public final class NonReentrantLock extends AbstractQueuedSynchronizer
return false; return false;
} }
/**
* Tries to release the lock
*
* @param releases A number that is passed by the release methods
* @return True if a release is granted, otherwise false
*/
@Override @Override
protected boolean tryRelease(int releases) { protected boolean tryRelease(int releases) {
if (Thread.currentThread() != owner) { if (Thread.currentThread() != owner) {
@ -81,6 +136,11 @@ public final class NonReentrantLock extends AbstractQueuedSynchronizer
return true; return true;
} }
/**
* Checks to see if this {@link NonReentrantLock} is held exclusively by the current {@link Thread}
*
* @return True if held exclusively, otherwise false
*/
@Override @Override
protected boolean isHeldExclusively() { protected boolean isHeldExclusively() {
return getState() != 0 && owner == Thread.currentThread(); return getState() != 0 && owner == Thread.currentThread();