Java Doc for Mutex.java in  » IDE-Netbeans » openide » org » openide » util » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 can enter the mutex as a writer, but you'll be warned because it is very deadlock prone (two readers trying to get write access concurently).

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 ();
 }
 // check whether you are already in read access
 if (m.isReadAccess ()) {
 // do your work
 }
 

When the Mutex methods are invoked on this mutex, the methods' semantics change as follows:

• The Mutex.isReadAccess and Mutex.isWriteAccess methods return true if the current thread is the event dispatch thread and false otherwise.
• The Mutex.postReadRequest and Mutex.postWriteRequest methods asynchronously execute the java.lang.Runnable passed in their run parameter on the event dispatch thead.
• The Mutex.readAccess(java.lang.Runnable) and Mutex.writeAccess(java.lang.Runnable) methods asynchronously execute the java.lang.Runnable passed in their run parameter on the event dispatch thread, unless the current thread is the event dispatch thread, in which case run.run() is immediately executed.
• The Mutex.readAccess(Mutex.Action) , Mutex.readAccess(Mutex.ExceptionAction action) , Mutex.writeAccess(Mutex.Action action) and Mutex.writeAccess(Mutex.ExceptionAction action) methods synchronously execute the Mutex.ExceptionAction passed in their action parameter on the event dispatch thread, unless the current thread is the event dispatch thread, in which case action.run() is immediately executed.

The Executor.execute method shall return only when the passed in Runnable is finished, otherwise methods like Mutex.readAccess(Action) and co. might not return proper result.
Parameters:
  privileged - can enter privileged states of this Mutex
Parameters:
  executor - allows to wrap the work of the mutex with a custom code
since:
   7.12

Warning: since a thread with write access automatically has effective read access as well (whether or not explicitly requested), if you want to check whether a thread can read some data, you should check for either kind of access, e.g.:

assert myMutex.isReadAccess() || myMutex.isWriteAccess();

Warning: this method blocks.

Warning: this method blocks.

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