* It is guaranteed that if you are a writer you can also enter the * mutex as a reader. But you cannot enter the write mutex if you hold * the read mutex, since that can cause deadlocks. *
* This implementation will not starve a writer or reader indefinitely. *
* Examples of use: * *
* Mutex m = new Mutex ();
*
* // Grant write access, compute an integer and return it:
* return (Integer)m.writeAccess (new Mutex.Action () {
* public Object run () {
* return new Integer (1);
* }
* });
*
* // Obtain read access, do some computation, possibly throw an IOException:
* try {
* m.readAccess (new Mutex.ExceptionAction () {
* public Object run () throws IOException {
* if (...) throw new IOException ();
*
* return null;
* }
* });
* } catch (MutexException ex) {
* throw (IOException)ex.getException ();
* }
* Mutexes to synchronize on one object or to synchronize
* a mutex with another critical section.
*
* @param lock lock to use
*/
public Mutex (Object lock) {
this.lock = lock;
}
/** Default constructor.
*/
public Mutex() {
this(new InternalLock());
}
/** @param privileged can enter privileged states of this Mutex
* This helps avoid creating of custom Runnables.
*/
public Mutex(Privileged privileged) {
this();
if (privileged == null) {
throw new IllegalArgumentException("privileged == null"); //NOI18N
} else {
privileged.setParent(this);
}
}
/** Run an action only with read access.
* See class description re. entering for write access within the dynamic scope.
* @param action the action to perform
* @return the object returned from {@link Mutex.Action#run}
*/
public Object readAccess (Action action) {
if (this == EVENT) {
return eventAccess(action);
}
enterReadAccess();
try {
return action.run();
} finally {
exitReadAccess();
}
}
/** Run an action with read access and possibly throw a checked exception.
* The exception if thrown is then encapsulated
* in a MutexException and thrown from this method. One is encouraged
* to catch MutexException, obtain the inner exception, and rethrow it.
* Here is an example:
*
* try {
* mutex.readAccess (new ExceptionAction () {
* public void run () throws IOException {
* throw new IOException ();
* }
* });
* } catch (MutexException ex) {
* throw (IOException) ex.getException ();
* }
*
* try {
* mutex.writeAccess (new ExceptionAction () {
* public void run () throws IOException {
* throw new IOException ();
* }
* });
* } catch (MutexException ex) {
* throw (IOException) ex.getException ();
* }
*
Warning: this method blocks.
* * @param run runnable to run */ public void postReadRequest (final Runnable run) { if (this == EVENT) { eventAccess(run, false); return; } if (canWrite()) { synchronized (lock) { ThreadInfo ti = currentThreadInfo(); if (ti == null) throw new IllegalStateException(); if (!ti.writer) throw new IllegalStateException(); if (ti.lateReadActions == null) { ti.lateReadActions = new LinkedList(); } ti.lateReadActions.add(run); } } else { enterReadAccess(); try { run.run(); } finally { exitReadAccess(); } } } /** Posts a write request. This request runs immediately iff * this Mutex is in the "pure" exclusive mode, i.e. this Mutex * is not reentered in shared mode after the exclusive mode * was acquired. Otherwise it is delayed until all read requests * are executed. * * This request runs immediately if this Mutex is not contended at all. * * This request blocks if this Mutex is in the shared mode. * *Warning: this method blocks.
* @param run runnable to run */ public void postWriteRequest (Runnable run) { if (this == EVENT) { eventAccess(run, false); return; } if (canWrite()) { boolean synch; synchronized (lock) { ThreadInfo ti = currentThreadInfo(); if (ti == null) throw new IllegalStateException(); if (!ti.writer) throw new IllegalStateException(); synch = ti.extraReads == 0; if (!synch) { if (ti.lateWriteActions == null) { ti.lateWriteActions = new LinkedList(); } ti.lateWriteActions.add(run); } } if (synch) { run.run(); } } else if (canRead()) { throw new IllegalStateException("Cannot call postWriteRequest while holding a read mutex; consider using writeAccess(Runnable)"); // NOI18N } else { enterWriteAccess(); try { run.run(); } finally { exitWriteAccess(); } } } /** * Enter the read mutex. * @see Mutex.Privileged#enterReadAccess */ void enterReadAccess() { synchronized (lock) { ThreadInfo ti = currentThreadInfo(); if (ti != null) { // Already in read or write mutex, can certainly enter read. ti.extraReads++; } else { // ti == null, entering fresh. // Wait for any writers to exit. while (semaphore < 0) { try { lock.wait(); } catch (InterruptedException e) { throw new IllegalStateException(e.toString()); } } // Uncontended or shared, go ahead. new ThreadInfo(false).register(); semaphore++; } } } /** * Exit the read mutex. * @see Mutex.Privileged#exitReadAccess */ void exitReadAccess() { List lateWriteActions = null; synchronized (lock) { ThreadInfo ti = currentThreadInfo(); if (ti == null) throw new IllegalStateException(); if (ti.extraReads > 0) { // Just mark them off. ti.extraReads--; if (ti.extraReads == 0 && ti.writer && ti.lateWriteActions != null) { // We are a writer who has just finished nested reads and now can // run some late write actions. if (semaphore != -1) throw new IllegalStateException(); lateWriteActions = ti.lateWriteActions; ti.lateWriteActions = null; } } else { // Really exiting. if (ti.writer) throw new IllegalStateException(); if (semaphore <= 0) throw new IllegalStateException(); if (ti.extraWrites > 0) throw new IllegalStateException(); ti.unregister(); semaphore--; lock.notifyAll(); if (semaphore == 0 && !threads.isEmpty()) throw new IllegalStateException(threads.toString()); } } if (lateWriteActions != null) { // We exited the lock, but since are a writer no one else can enter // anything, so that is safe. Iterator it = lateWriteActions.iterator(); while (it.hasNext()) { Runnable r = (Runnable)it.next(); r.run(); } } } /** * Enter the write mutex. * @see Mutex.Privileged#enterWriteAccess */ void enterWriteAccess() { synchronized (lock) { ThreadInfo ti = currentThreadInfo(); if (ti != null) { if (ti.writer) { // Already in write mutex, can reenter freely. ti.extraWrites++; } else { throw new IllegalStateException("Illegal mutex upgrade from read to write"); // NOI18N } } else { // ti == null, entering fresh. // Wait for any readers or writers to exit. while (semaphore != 0) { try { lock.wait(); } catch (InterruptedException e) { throw new IllegalStateException(e.toString()); } } // Uncontended, go ahead. new ThreadInfo(true).register(); semaphore = -1; } } } /** * Exit the write mutex. * @see Mutex.Privileged#exitWriteAccess */ void exitWriteAccess() { List lateReadActions = null; ThreadInfo ti; synchronized (lock) { ti = currentThreadInfo(); if (ti == null) throw new IllegalStateException(); if (!ti.writer) throw new IllegalStateException(); if (semaphore != -1) throw new IllegalStateException(); if (ti.extraWrites > 0) { // Just mark them off. ti.extraWrites--; } else if (ti.lateReadActions != null) { if (ti.extraReads > 0) throw new IllegalStateException(); // Will exit after running these. lateReadActions = ti.lateReadActions; ti.lateReadActions = null; } else { // Really exiting. if (ti.extraReads > 0) throw new IllegalStateException(); ti.unregister(); semaphore = 0; lock.notifyAll(); if (!threads.isEmpty()) throw new IllegalStateException(threads.toString()); } } if (lateReadActions != null) { // No other threads can enter before this because we have not yet // released the semaphore. synchronized (lock) { semaphore = 1; ti.writer = false; lock.notifyAll(); // Now the semaphore is released, we are in plain read access. if (threads.size() != 1) throw new IllegalStateException(threads.toString()); } try { Iterator it = lateReadActions.iterator(); while (it.hasNext()) { Runnable r = (Runnable)it.next(); r.run(); } } finally { exitReadAccess(); } } } /** * Check if the current thread is holding a read or write mutex. * @since XXX */ public boolean canRead() { if (this == EVENT) { return isDispatchThread(); } synchronized (lock) { if (semaphore == 0) { // Uncontended, obviously not. Only a shortcut, // next clause would catch it anyway. return false; } return currentThreadInfo() != null; } } /** * Check if the current thread is holding the write mutex. * @since XXX */ public boolean canWrite() { if (this == EVENT) { return isDispatchThread(); } synchronized (lock) { if (semaphore != -1) { // Not in write mode, obviously not. Only a shortcut, // next clause would catch it anyway. return false; } ThreadInfo ti = currentThreadInfo(); if (ti != null) { if (!ti.writer) throw new IllegalStateException(); return true; } else { return false; } } } /** toString */ public String toString() { if (this == EVENT) { return "Mutex.EVENT"; // NOI18N } return "Mutex
* try {
* enterXAccess ();
* yourCustomMethod ();
* } finally {
* exitXAccess ();
* }
*
* can be used.
*
* You must, however, control the related Mutex, i.e. you must be creator of
* the Mutex.
*
* @since 1.17
*/
public static final class Privileged {
private Mutex parent;
final void setParent(Mutex parent) {
this.parent = parent;
}
public void enterReadAccess() {
parent.enterReadAccess();
}
public void enterWriteAccess() {
parent.enterWriteAccess();
}
public void exitReadAccess() {
parent.exitReadAccess();
}
public void exitWriteAccess() {
parent.exitWriteAccess();
}
}
}