EDU.oswego.cs.dl.util.concurrent

Class WaiterPreferenceSemaphore

Implemented Interfaces:
Sync

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.

[ Introduction to this package. ]

Field Summary

protected long
waits_
Number of waiting threads *

Fields inherited from class EDU.oswego.cs.dl.util.concurrent.Semaphore

permits_

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

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

Method Summary

void
acquire()
boolean
attempt(long msecs)
void
release()
void
release(long n)
Release N permits *

Methods inherited from class EDU.oswego.cs.dl.util.concurrent.Semaphore

acquire, attempt, permits, release, release

Field Details

waits_

protected long waits_
Number of waiting threads *

Constructor Details

WaiterPreferenceSemaphore

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

Method Details

acquire

public void acquire()
            throws InterruptedException
Specified by:
acquire in interface Sync
Overrides:
acquire in interface Semaphore

attempt

public boolean attempt(long msecs)
            throws InterruptedException
Specified by:
attempt in interface Sync
Overrides:
attempt in interface Semaphore

release

public void release()
Specified by:
release in interface Sync
Overrides:
release in interface Semaphore

release

public void release(long n)
Release N permits *
Overrides:
release in interface Semaphore