java.util.concurrent
Class FairSemaphore

java.lang.Object
  java.util.concurrent.Semaphore
      java.util.concurrent.FairSemaphore

All Implemented Interfaces:

java.io.Serializable

public class FairSemaphore

extends Semaphore

A semaphore guaranteeing that threads invoking any of the acquire methods are allocated permits in the order in which their invocation of those methods was processed (first-in-first-out; FIFO). Note that FIFO ordering necessarily applies to specific internal points of execution within these methods. So, it is possible for one thread to invoke acquire before another, but reach the ordering point after the other, and similarly upon return from the method.

Because permits are allocated in-order, this class also provides convenience methods to acquire and release multiple permits at a time.

Since:

1.5

Author:

Doug Lea

See Also:

Serialized Form

Constructor Summary

FairSemaphore(long permits)
Construct a FairSemaphore with the given number of permits.

Method Summary

void	acquire() Acquires a permit from this semaphore, blocking until one is available, or the thread is interrupted.
void	acquire(long permits) Acquires the given number of permits from this semaphore, blocking until all are available, or the thread is interrupted.
void	acquireUninterruptibly() Acquires a permit from this semaphore, blocking until one is available.
void	acquireUninterruptibly(long permits) Acquires the given number of permits from this semaphore, blocking until all are available.
void	release() Releases a permit, returning it to the semaphore.
void	release(long permits) Releases the given number of permits, returning them to the semaphore.
boolean	tryAcquire() Acquires a permit from this semaphore, only if one is available at the time of invocation.
boolean	tryAcquire(long permits) Acquires the given number of permits from this semaphore, only if all are available at the time of invocation.
boolean	tryAcquire(long permits, long timeout, TimeUnit unit) Acquires the given number of permits from this semaphore, if all become available within the given waiting time and the current thread has not been interrupted.
boolean	tryAcquire(long timeout, TimeUnit unit) Acquires a permit from this semaphore, if one becomes available within the given waiting time and the current thread has not been interrupted.

Methods inherited from class java.util.concurrent.Semaphore

availablePermits

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FairSemaphore

public FairSemaphore(long permits)

Construct a FairSemaphore with the given number of permits.

Parameters:

permits - the initial number of permits available

Method Detail

acquire

public void acquire()
             throws java.lang.InterruptedException

Acquires a permit from this semaphore, blocking until one is available, or the thread is interrupted.

Acquires a permit, if one is available and returns immediately, reducing the number of available permits by one.

If no permit is available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happens:

• Some other thread invokes the release() method for this semaphore and the current thread is next to be assigned a permit; or
• Some other thread interrupts the current thread.

If the current thread:

• has its interrupted status set on entry to this method; or
• is interrupted while waiting for a permit,

then InterruptedException is thrown and the current thread's interrupted status is cleared.

Overrides:

acquire in class Semaphore

Throws:

java.lang.InterruptedException - if the current thread is interrupted

See Also:

Thread.interrupt()

acquireUninterruptibly

public void acquireUninterruptibly()

Acquires a permit from this semaphore, blocking until one is available.

Acquires a permit, if one is available and returns immediately, reducing the number of available permits by one.

If no permit is available then the current thread becomes disabled for thread scheduling purposes and lies dormant until some other thread invokes the release() method for this semaphore and the current thread is next to be assigned a permit.

If the current thread is interrupted while waiting for a permit then it will continue to wait, but the time at which the thread is assigned a permit may change compared to the time it would have received the permit had no interruption occurred. When the thread does return from this method its interrupt status will be set.

Overrides:

acquireUninterruptibly in class Semaphore

tryAcquire

public boolean tryAcquire()

Acquires a permit from this semaphore, only if one is available at the time of invocation.

Acquires a permit, if one is available and returns immediately, with the value true, reducing the number of available permits by one.

If no permit is available then this method will return immediately with the value false.

Overrides:

tryAcquire in class Semaphore

Returns:

true if a permit was acquired and false otherwise.

tryAcquire

public boolean tryAcquire(long timeout,
                          TimeUnit unit)
                   throws java.lang.InterruptedException

Acquires a permit from this semaphore, if one becomes available within the given waiting time and the current thread has not been interrupted.

Acquires a permit, if one is available and returns immediately, with the value true, reducing the number of available permits by one.

If no permit is available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens:

• Some other thread invokes the release() method for this semaphore and the current thread is next to be assigned a permit; or
• Some other thread interrupts the current thread; or
• The specified waiting time elapses.

If a permit is acquired then the value true is returned.

If the current thread:

• has its interrupted status set on entry to this method; or
• is interrupted while waiting to acquire a permit,

then InterruptedException is thrown and the current thread's interrupted status is cleared.

If the specified waiting time elapses then the value false is returned. If the time is less than or equal to zero, the method will not wait at all.

Overrides:

tryAcquire in class Semaphore

Parameters:

timeout - the maximum time to wait for a permit

unit - the time unit of the timeout argument.

Returns:

true if a permit was acquired and false if the waiting time elapsed before a permit was acquired.

Throws:

java.lang.InterruptedException - if the current thread is interrupted

See Also:

Thread.interrupt()

release

public void release()

Releases a permit, returning it to the semaphore.

Releases a permit, increasing the number of available permits by one. If any threads are blocking trying to acquire a permit, then one is selected and given the permit that was just released. That thread is re-enabled for thread scheduling purposes.

There is no requirement that a thread that releases a permit must have acquired that permit by calling acquire(). Correct usage of a semaphore is established by programming convention in the application.

Overrides:

release in class Semaphore

acquire

public void acquire(long permits)
             throws java.lang.InterruptedException

Acquires the given number of permits from this semaphore, blocking until all are available, or the thread is interrupted.

Acquires the given number of permits, if they are available, and returns immediately, reducing the number of available permits by the given amount.

If insufficient permits are available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happens:

• Some other thread invokes one of the release methods for this semaphore, the current thread is next to be assigned permits and the number of available permits satisfies this request; or
• Some other thread interrupts the current thread.

If the current thread:

• has its interrupted status set on entry to this method; or
• is interrupted while waiting for a permit,

then InterruptedException is thrown and the current thread's interrupted status is cleared. Any permits that were to be assigned to this thread, are instead assigned to the next waiting thread(s), as if they had been made available by a call to release().

Parameters:

permits - the number of permits to acquire

Throws:

java.lang.InterruptedException - if the current thread is interrupted

java.lang.IllegalArgumentException - if permits less than zero.

See Also:

Thread.interrupt()

acquireUninterruptibly

public void acquireUninterruptibly(long permits)

Acquires the given number of permits from this semaphore, blocking until all are available.

Acquires the given number of permits, if they are available, and returns immediately, reducing the number of available permits by the given amount.

If insufficient permits are available then the current thread becomes disabled for thread scheduling purposes and lies dormant until some other thread invokes one of the release methods for this semaphore, the current thread is next to be assigned permits and the number of available permits satisfies this request.

If the current thread is interrupted while waiting for permits then it will continue to wait and its position in the queue is not affected. When the thread does return from this method its interrupt status will be set.

Parameters:

permits - the number of permits to acquire

Throws:

java.lang.IllegalArgumentException - if permits less than zero.

tryAcquire

public boolean tryAcquire(long permits)

Acquires the given number of permits from this semaphore, only if all are available at the time of invocation.

Acquires the given number of permits, if they are available, and returns immediately, with the value true, reducing the number of available permits by the given amount.

If insufficient permits are available then this method will return immediately with the value false and the number of available permits is unchanged.

Parameters:

permits - the number of permits to acquire

Returns:

true if the permits were acquired and false otherwise.

Throws:

java.lang.IllegalArgumentException - if permits less than zero.

tryAcquire

public boolean tryAcquire(long permits,
                          long timeout,
                          TimeUnit unit)
                   throws java.lang.InterruptedException

Acquires the given number of permits from this semaphore, if all become available within the given waiting time and the current thread has not been interrupted.

Acquires the given number of permits, if they are available and returns immediately, with the value true, reducing the number of available permits by the given amount.

If insufficient permits are available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens:

• Some other thread invokes one of the release methods for this semaphore, the current thread is next to be assigned permits and the number of available permits satisfies this request; or
• Some other thread interrupts the current thread; or
• The specified waiting time elapses.

If the permits are acquired then the value true is returned.

If the current thread:

• has its interrupted status set on entry to this method; or
• is interrupted while waiting to acquire the permits,

then InterruptedException is thrown and the current thread's interrupted status is cleared. Any permits that were to be assigned to this thread, are instead assigned to the next waiting thread(s), as if they had been made available by a call to release().

If the specified waiting time elapses then the value false is returned. If the time is less than or equal to zero, the method will not wait at all. Any permits that were to be assigned to this thread, are instead assigned to the next waiting thread(s), as if they had been made available by a call to release().

Parameters:

permits - the number of permits to acquire

timeout - the maximum time to wait for the permits

unit - the time unit of the timeout argument.

Returns:

true if all permits were acquired and false if the waiting time elapsed before all permits were acquired.

Throws:

java.lang.InterruptedException - if the current thread is interrupted

java.lang.IllegalArgumentException - if permits less than zero.

See Also:

Thread.interrupt()

release

public void release(long permits)

Releases the given number of permits, returning them to the semaphore.

Releases the given number of permits, increasing the number of available permits by that amount. If any threads are blocking trying to acquire permits, then the one that has been waiting the longest is selected and given the permits that were just released. If the number of available permits satisfies that thread's request then that thread is re-enabled for thread scheduling purposes; otherwise the thread continues to wait. If there are still permits available after the first thread's request has been satisfied, then those permits are assigned to the next waiting thread. If it is satisfied then it is re-enabled for thread scheduling purposes. This continues until there are insufficient permits to satisfy the next waiting thread, or there are no more waiting threads.

There is no requirement that a thread that releases a permit must have acquired that permit by calling acquire. Correct usage of a semaphore is established by programming convention in the application.

Parameters:

permits - the number of permits to release

Throws:

java.lang.IllegalArgumentException - if permits less than zero.