## EDU.oswego.cs.dl.util.concurrent
Class WaiterPreferenceSemaphore

    java.lang.Object
      EDU.oswego.cs.dl.util.concurrent.Semaphore
          EDU.oswego.cs.dl.util.concurrent.WaiterPreferenceSemaphore

All 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()` 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 EDU.oswego.cs.dl.util.concurrent.Semaphore
`permits`

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

Field Detail

### waits_

    protected long waits_

  Number of waiting threads

Constructor Detail

### WaiterPreferenceSemaphore

    public WaiterPreferenceSemaphore(long initial)

  Create a Semaphore with the given initial number of permits.

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 `Sync`
  Overrides:
    `acquire` in class `Semaphore`
  Throws:
    `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 `Sync`
  Overrides:
    `attempt` in class `Semaphore`
  Parameters:
    `msecs` - the number of milleseconds to wait. An argument less than or equal to zero means not to wait at all. However, this may still require access to a synchronization lock, which can impose unbounded delay if there is a lot of contention among threads.
  Returns:
    true if acquired
  Throws:
    `java.lang.InterruptedException`

### release

    public void release()

  Description copied from class: `Semaphore`
  Release a permit

  Specified by:
    `release` in interface `Sync`
  Overrides:
    `release` in class `Semaphore`

### release

    public void release(long n)

  Release N permits

  Overrides:
    `release` in class `Semaphore`