Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.util 6.8.22
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 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
     }

Nested 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
`boolean` | `isReadAccess()` Tests whether this thread has already entered the mutex in read access.
`boolean` | `isWriteAccess()` Tests whether this thread has already entered the mutex in write access.
`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.

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

  - The `isReadAccess()` and `isWriteAccess()` methods return `true` if the current thread is the event dispatch thread and false otherwise.
  - The `postReadRequest(java.lang.Runnable)` and `postWriteRequest(java.lang.Runnable)` methods asynchronously execute the `Runnable` passed in their `run` parameter on the event dispatch thead.
  - The `readAccess(java.lang.Runnable)` and `writeAccess(java.lang.Runnable)` methods asynchronously execute the `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 `readAccess(Mutex.Action)`, `readAccess(Mutex.ExceptionAction action)`, `writeAccess(Mutex.Action action)` and `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.

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 `Mutex`es 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)`

### isReadAccess

    public boolean isReadAccess()

  Tests whether this thread has already entered the mutex in read access. If it returns true, calling `readAccess` will be executed immediatelly without any blocking. Calling `postWriteAccess` will delay the execution of its `Runnable` until a readAccess section is over and calling `writeAccess` is strongly prohibited and will result in a warning as a deadlock prone behaviour.

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

  Returns:
    true if the thread is in read access section
  Since:
    4.48

### isWriteAccess

    public boolean isWriteAccess()

  Tests whether this thread has already entered the mutex in write access. If it returns true, calling `writeAccess` will be executed immediatelly without any other blocking. `postReadAccess` will be delayed until a write access runnable is over.

  Returns:
    true if the thread is in write access section
  Since:
    4.48

### 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.

  Warning: this method blocks.

  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.

  Warning: this method blocks.

  Parameters:
    `run` - runnable to run

### toString

    public String toString()

  toString

  Overrides:
    `toString` in class `Object`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.util 6.8.22
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.