org.openide.util
Class Mutex

java.lang.Object
  |
  +--org.openide.util.Mutex

public final class Mutex
extends Object

Read-many/write-one lock. Allows control over resources that can be read by several readers at once but only written by one writer.

It is guaranteed that if you are a writer you can also enter the mutex as a reader. Conversely, if you are the only reader you are allowed to enter the mutex as a writer.

If the mutex is used only by one thread, the thread can repeatedly enter it as a writer or reader. So one thread can never deadlock itself, whichever order operations are performed in.

There is no strategy to prevent starvation. Even if there is a writer waiting to enter, another reader might enter the section instead.

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 ();
 }
 


Inner Class Summary
static interface Mutex.Action
          Action to be executed in a mutex without throwing any checked exceptions.
static interface Mutex.ExceptionAction
          Action to be executed in a mutex, possibly throwing checked exceptions.
 
Field Summary
static Mutex EVENT
          Mutex that allows code to be synchronized with the AWT event dispatch thread.
 
Constructor Summary
Mutex()
          Default constructor.
Mutex(Object lock)
          Enhanced constructor that permits specifying an object to use as a lock.
 
Method Summary
 void postReadRequest(Runnable run)
          Deprecated.  
 void postWriteRequest(Runnable run)
          Run an action with write access as soon as that is permitted.
 Object readAccess(Mutex.Action action)
          Run an action only with read access.
 Object readAccess(Mutex.ExceptionAction action)
          Run an action with read access and possibly throw a checked exception.
 void readAccess(Runnable action)
          Run an action with read access, returning no result.
 String toString()
          toString
 Object writeAccess(Mutex.Action action)
          Run an action with write access.
 Object writeAccess(Mutex.ExceptionAction action)
          Run an action with write access and possibly throw an exception.
 void writeAccess(Runnable action)
          Run an action with write access and return no result.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

EVENT

public static final Mutex EVENT
Mutex that allows code to be synchronized with the AWT event dispatch thread.
Constructor Detail

Mutex

public Mutex(Object lock)
Enhanced constructor that permits specifying an object to use as a lock. The lock is used on entry and exit to readAccess(org.openide.util.Mutex.Action) and during the whole execution of writeAccess(org.openide.util.Mutex.Action). The ability to specify locks allows several Mutexes to synchronize on one object or to synchronize a mutex with another critical section.
Parameters:
lock - lock to use

Mutex

public Mutex()
Default constructor.
Method Detail

readAccess

public Object readAccess(Mutex.Action action)
Run an action only with read access. See class description re. entering for write access within the dynamic scope.
Parameters:
action - the action to perform
Returns:
the object returned from Mutex.Action.run()

readAccess

public Object readAccess(Mutex.ExceptionAction action)
                  throws MutexException
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 ();
  }
 
Note that runtime exceptions are always passed through, and neither require this invocation style, nor are encapsulated.
Parameters:
action - the action to execute
Returns:
the object returned from Mutex.ExceptionAction.run()
Throws:
MutexException - encapsulates a user exception
RuntimeException - if any runtime exception is thrown from the run method
See Also:
readAccess(Mutex.Action)

readAccess

public void readAccess(Runnable action)
Run an action with read access, returning no result. It may be run asynchronously.
Parameters:
action - the action to perform
See Also:
readAccess(Mutex.Action)

writeAccess

public Object writeAccess(Mutex.Action action)
Run an action with write access. The same thread may meanwhile reenter the mutex; see the class description for details.
Parameters:
action - the action to perform
Returns:
the result of Mutex.Action.run()

writeAccess

public Object writeAccess(Mutex.ExceptionAction action)
                   throws MutexException
Run an action with write access and possibly throw an exception. Here is an example:

 try {
   mutex.writeAccess (new ExceptionAction () {
     public void run () throws IOException {
       throw new IOException ();
     }
   });
  } catch (MutexException ex) {
    throw (IOException) ex.getException ();
  }
 
Parameters:
action - the action to execute
Returns:
the result of Mutex.ExceptionAction.run()
Throws:
MutexException - an encapsulated checked exception, if any
RuntimeException - if a runtime exception is thrown in the action
See Also:
writeAccess(Mutex.Action), readAccess(Mutex.ExceptionAction)

writeAccess

public void writeAccess(Runnable action)
Run an action with write access and return no result. It may be run asynchronously.
Parameters:
action - the action to perform
See Also:
writeAccess(Mutex.Action), readAccess(Runnable)

postReadRequest

public void postReadRequest(Runnable run)
Deprecated.  

Not implemented
Parameters:
run - runnable to run

postWriteRequest

public void postWriteRequest(Runnable run)
Run an action with write access as soon as that is permitted. If there is no writer & reader, it will be run immediately; otherwise it will be run later when the last writer and/or reader finishes.
Parameters:
run - runnable to run

toString

public String toString()
toString
Overrides:
toString in class Object


Built on February 22 2001.  |  Portions Copyright 1997-2000 Sun Microsystems, Inc. All rights reserved.