Mutex (NetBeans Utilities API) - NetBeans API Javadoc 5.0.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

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

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

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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.

Mutex (NetBeans Utilities API) - NetBeans API Javadoc 5.0.0

org.openide.util Class Mutex

EVENT

Mutex

Mutex

Mutex

readAccess

readAccess

readAccess

writeAccess

writeAccess

writeAccess

isReadAccess

isWriteAccess

postReadRequest

postWriteRequest

toString

org.openide.util
Class Mutex