org.mmbase.util
Class DijkstraSemaphore

java.lang.Object
  extended by 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: DijkstraSemaphore.java 41055 2010-02-15 23:59:16Z michiel $
Author:
Karthik Rangaraju, Michiel Meeuwissen

Constructor Summary
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
 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


MMBase 2.0-SNAPSHOT - null