it.pixel.util.threads
Class Semaphore

java.lang.Object
  |
  +--it.pixel.util.threads.Semaphore

public class Semaphore

extends java.lang.Object

This class is the implementation of a semaphore.

The lock() and unlock() methods implement repectively what historically has been known as the WAIT() and SIGNAL() (or P() and V()) model.

A semaphore is a positive integer counter that can be modified only by one thread at a time, through its lock() and unlock() methods.

Each call to lock() waits for the counter value to become greater than zero. When it becomes greater than zero, or if it already is, lock() decreases by one the value of the counter and returns.

Each call to unlock() increases by one the value of the counter.

Java monitors can always be used instead of semaphores for the same pourposes, it's only a matter of taste.

Field Summary

protected int	maxValue The highest value this semaphore can grow.
protected int	value The current value of this semaphore.

Constructor Summary

Semaphore()
Same as Semaphore(0, Integer.MAX_VALUE)

Semaphore(int initialValue)
Same as Semaphore(initialValue, Integer.MAX_VALUE)

Semaphore(int initialValue, int maxValue)
Creates a new semaphore with specified values.

Method Summary

int	getApproximateValue() Returns the current value of the counter.
void	lock() Waits for the counter to be positive, then decreases it by one and returns
void	unlock() If the current value is less than the maximum value, it increases the counter by one, wakes up a thread waiting in the lock() method if there is one, and returns.

Methods inherited from class java.lang.Object

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

Field Detail

value

protected int value

The current value of this semaphore.

maxValue

protected int maxValue

The highest value this semaphore can grow.

Constructor Detail

Semaphore

public Semaphore(int initialValue,
                 int maxValue)

Creates a new semaphore with specified values. A Semaphore(1, 1) is a mutex.

Parameters:

initialValue - The initial value (0 creates a "initially locked" semaphore).

maxValue - The maximum value

Semaphore

public Semaphore(int initialValue)

Same as Semaphore(initialValue, Integer.MAX_VALUE)

Parameters:

initialValue -

Semaphore

public Semaphore()

Same as Semaphore(0, Integer.MAX_VALUE)

Method Detail

lock

public void lock()

Waits for the counter to be positive, then decreases it by one and returns

unlock

public void unlock()

If the current value is less than the maximum value, it increases the counter by one, wakes up a thread waiting in the lock() method if there is one, and returns. Otherwise it does nothing and simply returns.

getApproximateValue

public int getApproximateValue()

Returns the current value of the counter. It is approximate because it is always possible that some other thread calls lock() or unlock() after the value has been read but before the caller receives it. Don't use this method to infere anything about the locking status, but only for statistical pourposes.

Returns:

The value of the counter at the time the method executes.