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.
static class	Mutex.Privileged Provides access to Mutex's internal methods.

Field Summary

static Mutex

EVENT Mutex that allows code to be synchronized with the AWT event dispatch thread.

Constructor Summary

Mutex()
Default constructor.

Mutex(Mutex.Privileged privileged)

Mutex(Object lock)
Enhanced constructor that permits specifying an object to use as a lock.

Method Summary

void	postReadRequest(Runnable run) Posts a read request.
void	postWriteRequest(Runnable run) Posts a write request.
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.

Mutex

public Mutex(Mutex.Privileged privileged)

Parameters:

privileged - can enter privileged states of this Mutex This helps avoid creating of custom Runnables.

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)

Posts a read request. This request runs immediately iff this Mutex is in the shared mode or this Mutex is not contended at all. This request is delayed if this Mutex is in the exclusive mode and is held by this thread, until the exclusive is left. Finally, this request blocks, if this Mutex is in the exclusive mode and is held by another thread.

Parameters:

run - runnable to run

postWriteRequest

public void postWriteRequest(Runnable run)

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.

Parameters:

run - runnable to run

toString

public String toString()

toString

Overrides:

toString in class Object