## EDU.oswego.cs.dl.util.concurrent
Class Mutex

    java.lang.Object
      EDU.oswego.cs.dl.util.concurrent.Mutex

All Implemented Interfaces:
  Sync

    public class Mutex

extends java.lang.Object
implements Sync

A simple non-reentrant mutual exclusion lock. The lock is free upon construction. Each acquire gets the lock, and each release frees it. Releasing a lock that is already free has no effect.

This implementation makes no attempt to provide any fairness or ordering guarantees. If you need them, consider using one of the Semaphore implementations as a locking mechanism.

Sample usage

Mutex can be useful in constructions that cannot be expressed using java synchronized blocks because the acquire/release pairs do not occur in the same method or code block. For example, you can use them for hand-over-hand locking across the nodes of a linked list. This allows extremely fine-grained locking, and so increases potential concurrency, at the cost of additional complexity and overhead that would normally make this worthwhile only in cases of extreme contention.

     class Node {
       Object item;
       Node next;
       Mutex lock = new Mutex(); // each node keeps its own lock

       Node(Object x, Node n) { item = x; next = n; }
     }

     class List {
        protected Node head; // pointer to first node of list

        // Use plain java synchronization to protect head field.
        //  (We could instead use a Mutex here too but there is no
        //  reason to do so.)
        protected synchronized Node getHead() { return head; }

        boolean search(Object x) throws InterruptedException {
          Node p = getHead();
          if (p == null) return false;

          //  (This could be made more compact, but for clarity of illustration,
          //  all of the cases that can arise are handled separately.)

          p.lock.acquire();              // Prime loop by acquiring first lock.
                                         //    (If the acquire fails due to
                                         //    interrupt, the method will throw
                                         //    InterruptedException now,
                                         //    so there is no need for any
                                         //    further cleanup.)
          for (;;) {
            if (x.equals(p.item)) {
              p.lock.release();          // release current before return
              return true;
            }
            else {
              Node nextp = p.next;
              if (nextp == null) {
                p.lock.release();       // release final lock that was held
                return false;
              }
              else {
                try {
                  nextp.lock.acquire(); // get next lock before releasing current
                }
                catch (InterruptedException ex) {
                  p.lock.release();    // also release current if acquire fails
                  throw ex;
                }
                p.lock.release();      // release old lock now that new one held
                p = nextp;
              }
            }
          }
        }

        synchronized void add(Object x) { // simple prepend
          // The use of `synchronized'  here protects only head field.
          // The method does not need to wait out other traversers
          // who have already made it past head.

          head = new Node(x, head);
        }

        // ...  other similar traversal and update methods ...
     }

See Also:
  `

  [ Introduction to this package. ]

  `

Field Summary
`protected boolean` `inuse_` The lock status

Fields inherited from interface EDU.oswego.cs.dl.util.concurrent.Sync
`ONE_CENTURY, ONE_DAY, ONE_HOUR, ONE_MINUTE, ONE_SECOND, ONE_WEEK, ONE_YEAR`

Constructor Summary
`Mutex()`

Method Summary
`void` `acquire()` Wait (possibly forever) until successful passage.
`boolean` `attempt(long msecs)` Wait at most msecs to pass; report whether passed.
`void` `release()` Potentially enable others to pass.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### inuse_

    protected boolean inuse_

  The lock status

Constructor Detail

### Mutex

    public Mutex()

Method Detail

### acquire

    public void acquire()
                 throws java.lang.InterruptedException

  Description copied from interface: `Sync`
  Wait (possibly forever) until successful passage. Fail only upon interuption. Interruptions always result in `clean' failures. On failure, you can be sure that it has not been acquired, and that no corresponding release should be performed. Conversely, a normal return guarantees that the acquire was successful.

  Specified by:
    `acquire` in interface `Sync`
  Throws:
    `java.lang.InterruptedException`

### release

    public void release()

  Description copied from interface: `Sync`
  Potentially enable others to pass.

  Because release does not raise exceptions, it can be used in `finally' clauses without requiring extra embedded try/catch blocks. But keep in mind that as with any java method, implementations may still throw unchecked exceptions such as Error or NullPointerException when faced with uncontinuable errors. However, these should normally only be caught by higher-level error handlers.

  Specified by:
    `release` in interface `Sync`

### attempt

    public boolean attempt(long msecs)
                    throws java.lang.InterruptedException

  Description copied from interface: `Sync`
  Wait at most msecs to pass; report whether passed.

  The method has best-effort semantics: The msecs bound cannot be guaranteed to be a precise upper bound on wait time in Java. Implementations generally can only attempt to return as soon as possible after the specified bound. Also, timers in Java do not stop during garbage collection, so timeouts can occur just because a GC intervened. So, msecs arguments should be used in a coarse-grained manner. Further, implementations cannot always guarantee that this method will return at all without blocking indefinitely when used in unintended ways. For example, deadlocks may be encountered when called in an unintended context.

  Specified by:
    `attempt` in interface `Sync`
  Parameters:
    `msecs` - the number of milleseconds to wait. An argument less than or equal to zero means not to wait at all. However, this may still require access to a synchronization lock, which can impose unbounded delay if there is a lot of contention among threads.
  Returns:
    true if acquired
  Throws:
    `java.lang.InterruptedException`