Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Standard Ed. 5.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.util.concurrent.locks
Class LockSupport

    java.lang.Object
      java.util.concurrent.locks.LockSupport

    public class LockSupport

extends Object

Basic thread blocking primitives for creating locks and other synchronization classes.

This class associates with each thread that uses it, a permit (in the sense of the `Semaphore` class). A call to `park` will return immediately if the permit is available, consuming it in the process; otherwise it may block. A call to `unpark` makes the permit available, if it was not already available. (Unlike with Semaphores though, permits do not accumulate. There is at most one.)

Methods `park` and `unpark` provide efficient means of blocking and unblocking threads that do not encounter the problems that cause the deprecated methods `Thread.suspend` and `Thread.resume` to be unusable for such purposes: Races between one thread invoking `park` and another thread trying to `unpark` it will preserve liveness, due to the permit. Additionally, `park` will return if the caller's thread was interrupted, and timeout versions are supported. The `park` method may also return at any other time, for "no reason", so in general must be invoked within a loop that rechecks conditions upon return. In this sense `park` serves as an optimization of a "busy wait" that does not waste as much time spinning, but must be paired with an `unpark` to be effective.

These methods are designed to be used as tools for creating higher-level synchronization utilities, and are not in themselves useful for most concurrency control applications.

Sample Usage. Here is a sketch of a First-in-first-out non-reentrant lock class.

     class FIFOMutex {
       private AtomicBoolean locked = new AtomicBoolean(false);
       private Queue<Thread> waiters = new ConcurrentLinkedQueue<Thread>();

       public void lock() {
         boolean wasInterrupted = false;
         Thread current = Thread.currentThread();
         waiters.add(current);

         // Block while not first in queue or cannot acquire lock
         while (waiters.peek() != current ||
                !locked.compareAndSet(false, true)) {
            LockSupport.park();
            if (Thread.interrupted()) // ignore interrupts while waiting
              wasInterrupted = true;
         }

         waiters.remove();
         if (wasInterrupted)          // reassert interrupt status on exit
            current.interrupt();
       }

       public void unlock() {
         locked.set(false);
         LockSupport.unpark(waiters.peek());
       }
     }

Method Summary
`static void` | `park()` Disables the current thread for thread scheduling purposes unless the permit is available.
`static void` | `parkNanos(long nanos)` Disables the current thread for thread scheduling purposes, for up to the specified waiting time, unless the permit is available.
`static void` | `parkUntil(long deadline)` Disables the current thread for thread scheduling purposes, until the specified deadline, unless the permit is available.
`static void` | `unpark(Thread thread)` Make available the permit for the given thread, if it was not already available.

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

Method Detail

### unpark

    public static void unpark(Thread thread)

  Make available the permit for the given thread, if it was not already available. If the thread was blocked on `park` then it will unblock. Otherwise, its next call to `park` is guaranteed not to block. This operation is not guaranteed to have any effect at all if the given thread has not been started.

  Parameters:
    `thread` - the thread to unpark, or `null`, in which case this operation has no effect.

### park

    public static void park()

  Disables the current thread for thread scheduling purposes unless the permit is available.

  If the permit is available then it is consumed and the call returns immediately; otherwise the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens:

  - Some other thread invokes `unpark` with the current thread as the target; or
  - Some other thread `interrupts` the current thread; or
  - The call spuriously (that is, for no reason) returns.

  This method does not report which of these caused the method to return. Callers should re-check the conditions which caused the thread to park in the first place. Callers may also determine, for example, the interrupt status of the thread upon return.

### parkNanos

    public static void parkNanos(long nanos)

  Disables the current thread for thread scheduling purposes, for up to the specified waiting time, unless the permit is available.

  If the permit is available then it is consumed and the call returns immediately; otherwise the current thread becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:

  - Some other thread invokes `unpark` with the current thread as the target; or
  - Some other thread `interrupts` the current thread; or
  - The specified waiting time elapses; or
  - The call spuriously (that is, for no reason) returns.

  This method does not report which of these caused the method to return. Callers should re-check the conditions which caused the thread to park in the first place. Callers may also determine, for example, the interrupt status of the thread, or the elapsed time upon return.

  Parameters:
    `nanos` - the maximum number of nanoseconds to wait

### parkUntil

    public static void parkUntil(long deadline)

  Disables the current thread for thread scheduling purposes, until the specified deadline, unless the permit is available.

  If the permit is available then it is consumed and the call returns immediately; otherwise the current thread becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:

  - Some other thread invokes `unpark` with the current thread as the target; or
  - Some other thread `interrupts` the current thread; or
  - The specified deadline passes; or
  - The call spuriously (that is, for no reason) returns.

  This method does not report which of these caused the method to return. Callers should re-check the conditions which caused the thread to park in the first place. Callers may also determine, for example, the interrupt status of the thread, or the current time upon return.

  Parameters:
    `deadline` - the absolute time, in milliseconds from the Epoch, to wait until

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Standard Ed. 5.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.