se.lth.cs.realtime.semaphore
Class CountingSem

java.lang.Object
  se.lth.cs.realtime.semaphore.CountingSem

All Implemented Interfaces:

Semaphore

public final class CountingSem

extends java.lang.Object

implements Semaphore

Basic type of semaphore containing a counter which is incremented by one fore each call to give, and decremented by one for each returning call of take. A counter value of zero prevents the caller of take to return by blocking it, until some other thread performs a give and the blocked thread is the first one in the waiting queue associated with the semaphore.

The order of the awakenings of the threads which called take depends on the underlying OS and/or VM, but for standard implementation in pure Java it will be the same as for the wait/notify mechanism.

The intended use of this class is signaling. By means of the semaphore methods, mutual exclusion can also be achieved. However, that is not the intended usage since (native) implementations of this class are not required to provide any priority inheritance.

See Also:

License, Semaphore, BinarySem, MutexSem, MultistepSem, SemInterrupted

Constructor Summary

CountingSem()
Creates a new CountingSem with the internal counter initialized to 0.

CountingSem(int init)
Creates a new CountingSem, initializing it to the specified (possibly negative) number.

Method Summary

void	give() Increments the internal counter by one and releases the first-in-queue blocked thread, if any.
void	take() Causes the calling thread to wait until the counter represented by this semaphore assumes a positive value.
boolean	tryTake(long timeout) Try to take the semaphore but give up waiting after the timeout number of milliseconds.

Methods inherited from class java.lang.Object

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

Constructor Detail

CountingSem

public CountingSem()

Creates a new CountingSem with the internal counter initialized to 0.

CountingSem

public CountingSem(int init)

Creates a new CountingSem, initializing it to the specified (possibly negative) number.

Parameters:

init - the initial value of the number represented by this semaphore.

Method Detail

give

public void give()

Increments the internal counter by one and releases the first-in-queue blocked thread, if any.

Specified by:

give in interface Semaphore

take

public void take()

Causes the calling thread to wait until the counter represented by this semaphore assumes a positive value. Before returning, this number is decremented by 1.

Specified by:

take in interface Semaphore

Throws:

SemInterrupted - (which is an error and not an exception) if the calling thread has been interrupted before or during blocking. The caller is not expected to catch it since it indicated severe violation in the handling of resources, concurrency, or time. Thus, you should not catch such an error, except for special cases like handling the termination of the application, since continuing execution after an interrupted resource allocation does normally result in the application not being concurrently correct.

tryTake

public boolean tryTake(long timeout)

Try to take the semaphore but give up waiting after the timeout number of milliseconds.

Specified by:

tryTake in interface Semaphore

Parameters:

timeout - specifies the time after which the calling thread should be unblocked and return even if the semaphore was not taken. Timeout values less than or equal to zero is legal and results in a wait-free call.

Returns:

true if the semaphore was successfully taken, and false if the timeout occurred which means that the semaphore was not taken.

Throws:

SemInterrupted - as when a call of take is interrupted.