se.lth.cs.realtime.semaphore
Class MutexSem

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

All Implemented Interfaces:

Semaphore

public final class MutexSem

extends java.lang.Object

implements Semaphore

A Semaphore with special support for MUTual EXclusion. Basically, this is equivalent with other semaphores, such as CountingSem or BinarySem, except for:

1. The implementation is required to provide priority inheritance in order to avoid priority inversion. Other semaphores are all allowed to provide priority inheritance but they are not required to do it.
2. It is required that a thread calling give already owns the semaphore. That is, the same thread has to call take (or tryTake returning true) first and then give. Violation of this rule results in a SemViolation error being thrown.

This class should map well onto the Mutex primitive In the POSIX standard.

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, which should provide priority inheritance (even if priorities are not strictly obeyed).

See Also:

License, Semaphore, MutexSem, CountingSem, MultistepSem, SemInterrupted, SemViolation

Constructor Summary

MutexSem()
Creates a new MutexSem with the internal (boolean) access flag set to true.

Method Summary

void	give() Sets the mutex to its unoccupied state and releases the first-in-queue blocked thread, if any.
void	take() Causes the calling thread to block until the mutex semaphore can be taken.
boolean	tryTake(long timeout) Try to take the semaphore but give up after a certain time.

Methods inherited from class java.lang.Object

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

Constructor Detail

MutexSem

public MutexSem()

Creates a new MutexSem with the internal (boolean) access flag set to true. To enforce the rule of calling take before give, this is the only way a MutexSem can be created.

Method Detail

give

public void give()

Sets the mutex to its unoccupied state and releases the first-in-queue blocked thread, if any. In some systems, this operation is referred to as unlock.

Specified by:

give in interface Semaphore

Throws:

SemViolation - if the calling thread tries to give away a lock that it does not own, that is, if the semaphore has not been taken first.

take

public void take()

Causes the calling thread to block until the mutex semaphore can be taken. When returning, the calling thread is registered as the owner of the semaphore. In some systems, this operation is referred to as lock since it is used to lock some resource. This mutex is recursive which means that a thread can take this mutex several times in a row without deadlocking. However a certain amount of take calls must be acompanied by an equal amount of give calls to make sure the mutex is freed properly.

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 an emergency stop.

tryTake

public boolean tryTake(long timeout)

Try to take the semaphore but give up after a certain time. Be careful not to neglect the returned value; the resource has been locked only if true is returned.

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. The time of the actual return depends on the underlaying OS/VM/scheduler etc., just like for the calls without a timeout argument.

Returns:

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

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 an emergency stop.