org.mmbase.util

Class DijkstraSemaphore

java.lang.Object

org.mmbase.util.DijkstraSemaphore

public class DijkstraSemaphore
extends Object

Also called counting semaphores, Dijkstra semaphores are used to control access to a set of resources. A Dijkstra semaphore has a count associated with it and each acquire() call reduces the count. A thread that tries to acquire() a Dijkstra semaphore with a zero count blocks until someone else calls release() thus increasing the count. When to use Recommended when applications require a counting semaphore. Implementing a counting semaphore using wait()/notify() and counters within your application code makes your code less readable and quickly increases the complexity (especially when you have the need for multiple counting semaphores). Can also be used to port code from POSIX environment.

Since:

MMBase-1.6

Version:

$Id$

Author:

Karthik Rangaraju, Michiel Meeuwissen

Constructor Summary

Constructors

Constructor and Description
DijkstraSemaphore(int pMaxCount) Creates a Dijkstra semaphore with the specified max count and initial count set to the max count (all resources released)
DijkstraSemaphore(int pMaxCount, int pInitialCount) Creates a Dijkstra semaphore with the specified max count and an initial count of acquire() operations that are assumed to have already been performed.

Method Summary

Modifier and Type	Method and Description
void	acquire() If the count is non-zero, acquires a semaphore and decrements the count by 1, otherwise blocks until a release() is executed by some other thread.
void	acquireAll() Tries to acquire all the semaphores thus bringing the count to zero.
void	release() Releases a previously acquires semaphore and increments the count by one.
void	release(int pCount) Same as release() except that the count is increased by pCount instead of 1.
void	releaseAll() Releases all semaphores setting the count to max count.
void	starvationCheck() This method blocks the calling thread until the count drops to zero.
boolean	tryAcquire() Non-blocking version of acquire().

Methods inherited from class java.lang.Object

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

Constructor Detail

DijkstraSemaphore

public DijkstraSemaphore(int pMaxCount)

Creates a Dijkstra semaphore with the specified max count and initial count set to the max count (all resources released)

Parameters:

pMaxCount - is the max semaphores that can be acquired

DijkstraSemaphore

public DijkstraSemaphore(int pMaxCount,
                         int pInitialCount)

Creates a Dijkstra semaphore with the specified max count and an initial count of acquire() operations that are assumed to have already been performed.

Parameters:

pMaxCount - is the max semaphores that can be acquired

pInitialCount - is the current count (setting it to zero means all semaphores have already been acquired). 0 <= pInitialCount <= pMaxCount

Method Detail

acquire

public void acquire()
             throws InterruptedException

If the count is non-zero, acquires a semaphore and decrements the count by 1, otherwise blocks until a release() is executed by some other thread.

Throws:

InterruptedException - if the thread is interrupted when blocked

See Also:

tryAcquire(), acquireAll()

tryAcquire

public boolean tryAcquire()

Non-blocking version of acquire().

Returns:

true if semaphore was acquired (count is decremented by 1), false otherwise

release

public void release()

Releases a previously acquires semaphore and increments the count by one. Does not check if the thread releasing the semaphore was a thread that acquired the semaphore previously. If more releases are performed than acquires, the count is not increased beyond the max count specified during construction.

See Also:

release(int pCount), releaseAll()

release

public void release(int pCount)

Same as release() except that the count is increased by pCount instead of 1. The resulting count is capped at max count specified in the constructor

Parameters:

pCount - is the amount by which the counter should be incremented

See Also:

release()

acquireAll

public void acquireAll()
                throws InterruptedException

Tries to acquire all the semaphores thus bringing the count to zero.

Throws:

InterruptedException - if the thread is interrupted when blocked on this call

See Also:

acquire(), releaseAll()

releaseAll

public void releaseAll()

Releases all semaphores setting the count to max count. Warning: If this method is called by a thread that did not make a corresponding acquireAll() call, then you better know what you are doing!

See Also:

acquireAll()

starvationCheck

public void starvationCheck()
                     throws InterruptedException

This method blocks the calling thread until the count drops to zero. The method is not stateful and hence a drop to zero will not be recognized if a release happens before this call. You can use this method to implement threads that dynamically increase the resource pool or that log occurences of resource starvation. Also called a reverse-sensing semaphore

Throws:

InterruptedException - if the thread is interrupted while waiting