org.objectweb.jac.util
Class Semaphore

java.lang.Object
  extended byorg.objectweb.jac.util.Semaphore

public class Semaphore
extends Object

This is a simple implementation of the well-known semaphore synchronization feature.

It allows a given number of thread to be blocked waiting for a resource to be freed by the threads that are currently using it.


Field Summary
protected  int count
          The available resources count.
 
Constructor Summary
Semaphore()
          The default constructor for this semaphore equivalent to Semaphore(0).
Semaphore(int n)
          The semaphore constructor that allows the programmer to assign a number of resources item that are greater than 0 or 1 (meaning that several threads (n exactly) can use the semaphore at the same time).
 
Method Summary
 boolean acquire()
          Acquires a resource on this semaphore with no timeout.
 boolean acquire(long timeout)
          Acquires a resource on this semaphore.
 int getCount()
           
 int getWaitingCount()
          Gets the number of threads that are currently blocked on this semaphore.
 void release()
          Releases a resource on this semaphore.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

count

protected int count
The available resources count.

Constructor Detail

Semaphore

public Semaphore(int n)
The semaphore constructor that allows the programmer to assign a number of resources item that are greater than 0 or 1 (meaning that several threads (n exactly) can use the semaphore at the same time).

Parameters:
n - the number of resource items

Semaphore

public Semaphore()
The default constructor for this semaphore equivalent to Semaphore(0).

This constructor means that no resources are available by default. Thus, the first thread (t1) that will acquire the semaphore will eventually by blocked until another thread (t2) releases a resource on this semaphore.

This use of the semaphore feature is quite strange regarding resources (since the deblocking thread (t2) releases a resource that it never acquired!!) but it can be very usefull for synchronization especially if t1 waits for a result that is being calculating by t2 and that is not yet available.

Method Detail

getWaitingCount

public int getWaitingCount()
Gets the number of threads that are currently blocked on this semaphore.

This method is an indication but is not safe since a thread can be released meantime you evaluate its result.

Returns:
the waiting threads number at the moment you have asked it

getCount

public int getCount()

acquire

public boolean acquire()
Acquires a resource on this semaphore with no timeout.

If no resources are available anymore (count == 0), then the thread that performed this call is blocked until another thread releases a resource.

Returns:
true if the resource could be aquired.
See Also:
acquire(long), release()

acquire

public boolean acquire(long timeout)
Acquires a resource on this semaphore.

If no resources are available anymore (count == 0), then the thread that performed this call is blocked until another thread releases a resource.

Parameters:
timeout - milliseconds to wait for. 0 means wait for ever.
Returns:
true if the resource could be aquired.
See Also:
acquire(), release()

release

public void release()
Releases a resource on this semaphore.

If one or several threads are blocked, waiting for a resource to be available, then this call will necessaraly makes one of them take the semaphore's monitor (the others, if any will block again). There is absolutly no way of knowing which thread will take the monitor first.

See Also:
acquire()