FileDocCategorySizeDatePackage
LockSupport.javaAPI DocJava SE 6 API13689Tue Jun 10 00:25:58 BST 2008java.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 {@link java.util.concurrent.Semaphore Semaphore} class). A call to {@code park} will return immediately if the permit is available, consuming it in the process; otherwise it may block. A call to {@code 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 {@code park} and {@code unpark} provide efficient means of blocking and unblocking threads that do not encounter the problems that cause the deprecated methods {@code Thread.suspend} and {@code Thread.resume} to be unusable for such purposes: Races between one thread invoking {@code park} and another thread trying to {@code unpark} it will preserve liveness, due to the permit. Additionally, {@code park} will return if the caller's thread was interrupted, and timeout versions are supported. The {@code 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 {@code park} serves as an optimization of a "busy wait" that does not waste as much time spinning, but must be paired with an {@code unpark} to be effective.

The three forms of {@code park} each also support a {@code blocker} object parameter. This object is recorded while the thread is blocked to permit monitoring and diagnostic tools to identify the reasons that threads are blocked. (Such tools may access blockers using method {@link #getBlocker}.) The use of these forms rather than the original forms without this parameter is strongly encouraged. The normal argument to supply as a {@code blocker} within a lock implementation is {@code this}.

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. The {@code park} method is designed for use only in constructions of the form: 

while (!canProceed()) { ... LockSupport.park(this); }
where neither {@code canProceed} nor any other actions prior to the call to {@code park} entail locking or blocking. Because only one permit is associated with each thread, any intermediary uses of {@code park} could interfere with its intended effects.

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

{@code
class FIFOMutex {
private final AtomicBoolean locked = new AtomicBoolean(false);
private final Queue waiters
= new ConcurrentLinkedQueue();

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

Fields Summary
private static final Unsafe
unsafe
private static final long
parkBlockerOffset
Constructors Summary
private LockSupport()

Methods Summary
public static java.lang.ObjectgetBlocker(java.lang.Thread t)
Returns the blocker object supplied to the most recent
invocation of a park method that has not yet unblocked, or null
if not blocked. The value returned is just a momentary
snapshot -- the thread may have since unblocked or blocked on a
different blocker object.
return
the blocker
since
1.6
        return unsafe.getObjectVolatile(t, parkBlockerOffset);
    
public static voidpark(java.lang.Object blocker)
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 {@link #unpark unpark} with the
current thread as the target; or


  • Some other thread {@linkplain Thread#interrupt 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.
param
blocker the synchronization object responsible for this
thread parking
since
1.6
        Thread t = Thread.currentThread();
        setBlocker(t, blocker);
        unsafe.park(false, 0L);
        setBlocker(t, null);
    
public static voidpark()
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 {@link #unpark unpark} with the
current thread as the target; or


  • Some other thread {@linkplain Thread#interrupt 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.
        unsafe.park(false, 0L);
    
public static voidparkNanos(java.lang.Object blocker, 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 {@link #unpark unpark} with the
current thread as the target; or


  • Some other thread {@linkplain Thread#interrupt 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.
param
blocker the synchronization object responsible for this
thread parking
param
nanos the maximum number of nanoseconds to wait
since
1.6
        if (nanos > 0) {
            Thread t = Thread.currentThread();
            setBlocker(t, blocker);
            unsafe.park(false, nanos);
            setBlocker(t, null);
        }
    
public static voidparkNanos(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 {@link #unpark unpark} with the
current thread as the target; or


  • Some other thread {@linkplain Thread#interrupt 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.
param
nanos the maximum number of nanoseconds to wait
        if (nanos > 0)
            unsafe.park(false, nanos);
    
public static voidparkUntil(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 {@link #unpark unpark} with the
current thread as the target; or


  • Some other thread {@linkplain Thread#interrupt 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.
param
deadline the absolute time, in milliseconds from the Epoch,
to wait until
        unsafe.park(true, deadline);
    
public static voidparkUntil(java.lang.Object blocker, 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 {@link #unpark unpark} with the
current thread as the target; or


  • Some other thread {@linkplain Thread#interrupt 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.
param
blocker the synchronization object responsible for this
thread parking
param
deadline the absolute time, in milliseconds from the Epoch,
to wait until
since
1.6
        Thread t = Thread.currentThread();
        setBlocker(t, blocker);
        unsafe.park(true, deadline);
        setBlocker(t, null);
    
private static voidsetBlocker(java.lang.Thread t, java.lang.Object arg)

     
        try {
            parkBlockerOffset = unsafe.objectFieldOffset
                (java.lang.Thread.class.getDeclaredField("parkBlocker"));
        } catch (Exception ex) { throw new Error(ex); }
    
        // Even though volatile, hotspot doesn't need a write barrier here.
        unsafe.putObject(t, parkBlockerOffset, arg);
    
public static voidunpark(java.lang.Thread thread)
Makes available the permit for the given thread, if it
was not already available. If the thread was blocked on
{@code park} then it will unblock. Otherwise, its next call
to {@code 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.
param
thread the thread to unpark, or {@code null}, in which case
this operation has no effect
        if (thread != null)
            unsafe.unpark(thread);