org.gscg.common
Class DijkstraSemaphore

java.lang.Object
  org.gscg.common.DijkstraSemaphore

public class DijkstraSemaphore

extends java.lang.Object

Also called counting semaphores, Dijkkstra 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.

Since:

1.1.3

Version:

$Revision: 1.1 $ $Date: 2005/06/16 12:33:54 $

Author:

Karthik Rangaraju

Constructor Summary

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

DijkstraSemaphore(int maxCount, int initialCount)
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

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.
int	getMaximumCount()
void	release() Releases a previously acquires semaphore and increments the count by one.
void	release(int count) 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	setMaximumCount(int maximumCount) sets the maximum 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 maxCount)

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

Parameters:

maxCount - is the max semaphores that can be acquired

DijkstraSemaphore

public DijkstraSemaphore(int maxCount,
                         int initialCount)

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:

maxCount - is the max semaphores that can be acquired

initialCount - 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 java.lang.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:

java.lang.InterruptedException - is 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 count)

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:

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

See Also:

release()

acquireAll

public void acquireAll()
                throws java.lang.InterruptedException

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

Throws:

java.lang.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()

setMaximumCount

public void setMaximumCount(int maximumCount)

sets the maximum count

Parameters:

maximumCount - the maximum count

getMaximumCount

public int getMaximumCount()

Returns:

returns the maximum count for the dijkstra semaphore

starvationCheck

public void starvationCheck()
                     throws java.lang.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:

java.lang.InterruptedException - if the thread is interrupted while waiting