org.metasyntactic.thread.concurrent
Class WaiterPreferenceSemaphore

java.lang.Object
  |
  +--org.metasyntactic.thread.concurrent.Semaphore
        |
        +--org.metasyntactic.thread.concurrent.WaiterPreferenceSemaphore
All Implemented Interfaces:
Monitor

public final class WaiterPreferenceSemaphore
extends Semaphore

An implementation of counting Semaphores that enforces enough fairness for applications that need to avoid indefinite overtaking without necessarily requiring FIFO ordered access. Empirically, very little is paid for this property unless there is a lot of contention among threads or very unfair JVM scheduling. The acquire method waits even if there are permits available but have not yet been claimed by threads that have been notified but not yet resumed. This makes the semaphore almost as fair as the underlying Java primitives allow. So, if synch lock entry and notify are both fair so is the semaphore -- almost: Rewaits stemming from timeouts in attempt, along with potentials for interrupted threads to be notified can compromise fairness, possibly allowing later-arriving threads to pass before later arriving ones. However, in no case can a newly entering thread obtain a permit if there are still others waiting. Also, signalling order need not coincide with resumption order. Later-arriving threads might get permits and continue before other resumable threads are actually resumed. However, all of these potential fairness breaches are very rare in practice unless the underlying JVM performs strictly LIFO notifications (which has, sadly enough, been known to occur) in which case you need to use a FIFOSemaphore to maintain a reasonable approximation of fairness.


Field Summary
 
Fields inherited from class org.metasyntactic.thread.concurrent.Semaphore
permits
 
Fields inherited from interface org.metasyntactic.thread.concurrent.Monitor
ONE_CENTURY, ONE_DAY, ONE_HOUR, ONE_MINUTE, ONE_SECOND, ONE_WEEK, ONE_YEAR
 
Constructor Summary
WaiterPreferenceSemaphore(long initial)
          Create a Semaphore with the given initial number of permits.
 
Method Summary
 void acquire()
          Wait until a permit is available, and take one
 boolean attempt(long msecs)
          Wait at most msecs millisconds for a permit.
 void release()
          Release a permit
 void release(long n)
          Release N permits
 
Methods inherited from class org.metasyntactic.thread.concurrent.Semaphore
permits
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WaiterPreferenceSemaphore

public WaiterPreferenceSemaphore(long initial)
Create a Semaphore with the given initial number of permits.

Parameters:
initial -
Method Detail

acquire

public void acquire()
             throws java.lang.InterruptedException
Description copied from class: Semaphore
Wait until a permit is available, and take one

Specified by:
acquire in interface Monitor
Overrides:
acquire in class Semaphore
java.lang.InterruptedException

attempt

public boolean attempt(long msecs)
                throws java.lang.InterruptedException
Description copied from class: Semaphore
Wait at most msecs millisconds for a permit.

Specified by:
attempt in interface Monitor
Overrides:
attempt in class Semaphore
Parameters:
msecs - The number of milliseconds to wait for a permit
Returns:
True/False on whether or not the permit was granted
Throws:
java.lang.InterruptedException

release

public void release()
Description copied from class: Semaphore
Release a permit

Specified by:
release in interface Monitor
Overrides:
release in class Semaphore

release

public void release(long n)
Release N permits

Overrides:
release in class Semaphore
Parameters:
n -