IBM Branch Transformation Toolkit Javadoc

com.ibm.dse.base
Class Semaphore

java.lang.Object
  extended bycom.ibm.dse.base.Semaphore

public class Semaphore
extends java.lang.Object

This class provides a semaphore with timeOut option. SignalOn or signalOnAll must be used depending if processes are initiated one at a time or all at once. SignalOn method works with a signals counter, which is important to know if there are signals to be processed using hasSignals method. Then, reset signal does not make any sense in this case and the use of waitOnAndResetSignal methods must be forbbiden to ensure a good use of the semaphore in the application. Also the application must be consistent using the different options of the wait methods, so it is advised to be aware of merge waits with different values of waitEvenIfSignalAlreadyNotified parameter. SignalOnAll always must be used with waitOnAndResetSignal methods in order to grant consistency with the signals counter because in this case it is not needed.


Constructor Summary
Semaphore()
          This constructor creates a Semaphore object.
 
Method Summary
 void clearSignal()
          Clears signalsCounter property.
 boolean hasSignals()
          Returns true if a signal has already been notified when a process wants to enter the semaphore.
 boolean hasTimedOut()
          Returns true if a thread has been awakened by a time out.
 void signalOn()
          Wakes up a thread that is waiting on the Semaphore.
 void signalOnAll()
          Wakes up all threads that are waiting on the Semaphore.
 void waitOn()
          Unless a signal has already been notified, this method holds the process indefinitely until the Semaphore receives a signal.
 void waitOn(boolean waitEvenIfSignalAlreadyNotified, boolean resetSignal)
          Holds the process until the Semaphore receives the signal.
 void waitOn(long timeout)
          Unless a signal has already been notified, this method holds the process until the Semaphore receives a signal or until the timeout is reached.
 void waitOn(long timeout, boolean waitEvenIfSignalAlreadyNotified, boolean resetSignal)
          Holds the process until the Semaphore receives the signal or until the timeout is reached.
 void waitOnAndResetSignal()
          Unless a signal has already been notified, this method holds the process until the Semaphore receives a signal.
 void waitOnAndResetSignal(long timeout)
          Unless a signal has already been notified, this method holds the process until the Semaphore receives a signal or until the timeout is reached.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Semaphore

public Semaphore()
This constructor creates a Semaphore object.

Method Detail

clearSignal

public void clearSignal()
Clears signalsCounter property.


hasSignals

public boolean hasSignals()
Returns true if a signal has already been notified when a process wants to enter the semaphore.

Returns:
boolean

hasTimedOut

public boolean hasTimedOut()
Returns true if a thread has been awakened by a time out.

Returns:
boolean

signalOn

public void signalOn()
Wakes up a thread that is waiting on the Semaphore. WaitOn() and waitOn(timeout) methods are advised to use, although waitOn([timeout,] waitEvenIfSignalAlreadyNotified, resetSignal) also could be used but keeping in mind that resetSignal always must be FALSE and being carefully in the use of waitEvenIfSignalAlreadyNotified parameter to be consistent. Example: ---> signalOn(); ------> waitOn(waitEvenIfSignalAlreadyNotified=true, resetSignal=FALSE); ---> signalOn(); ======> awakes the last wait. ------> waitOn(waitEvenIfSignalAlreadyNotified=TRUE, resetSignal=FALSE); To be consistent waitEvenIfSignalAlreadyNotified has to be TRUE; otherwise this wait it will be awake for the last signal as well.


signalOnAll

public void signalOnAll()
Wakes up all threads that are waiting on the Semaphore. WaitOnAndResetSignal() and waitOnAndResetSignal(timeout) methods are advised to use, although waitOn([timeout,] waitEvenIfSignalAlreadyNotified, resetSignal) also could be used but keeping in mind that resetSignal always must be TRUE.


waitOn

public void waitOn()
Unless a signal has already been notified, this method holds the process indefinitely until the Semaphore receives a signal. Once the signal is received, the method then decreases the value of the signalsCounter attribute.


waitOn

public void waitOn(long timeout)
Unless a signal has already been notified, this method holds the process until the Semaphore receives a signal or until the timeout is reached. Once the signal is received or the timeout reached, the method then decreases the value of the signalsCounter attribute. The specified amount of real time has elapsed, more or less. If timeout is zero, however, then real time is not taken into consideration and the thread simply waits until notified. See comments on method wait(timeout) in Object class.

Parameters:
timeout - long - The maximum time to wait in milliseconds

waitOn

public void waitOn(long timeout,
                   boolean waitEvenIfSignalAlreadyNotified,
                   boolean resetSignal)
Holds the process until the Semaphore receives the signal or until the timeout is reached. Once the signal is received or the timeout reached, the method then decreases the value of the signalsCounter attribute. The specified amount of real time has elapsed, more or less. If timeout is zero, however, then real time is not taken into consideration and the thread simply waits until notified. See comments on method wait(timeout) in Object class.

Parameters:
timeout - long - The maximum time to wait in milliseconds
waitEvenIfSignalAlreadyNotified - - Boolean allows to choose to wait or no if a signal has already been notified
resetSignal - - Boolean allows to reset signalAlreadyNotified property.

waitOn

public void waitOn(boolean waitEvenIfSignalAlreadyNotified,
                   boolean resetSignal)
Holds the process until the Semaphore receives the signal.


waitOnAndResetSignal

public void waitOnAndResetSignal()
Unless a signal has already been notified, this method holds the process until the Semaphore receives a signal. Once the signal is received, the method then clears the signalsCounter attribute.


waitOnAndResetSignal

public void waitOnAndResetSignal(long timeout)
Unless a signal has already been notified, this method holds the process until the Semaphore receives a signal or until the timeout is reached. Once the signal is received or the timeout reached, the method then clears the signalsCounter attribute. The specified amount of real time has elapsed, more or less. If timeout is zero, however, then real time is not taken into consideration and the thread simply waits until notified. See comments on method wait(timeout) in Object class.

Parameters:
timeout - long - The maximum time to wait in milliseconds

IBM Branch Transformation Toolkit Javadoc

(c) Copyright IBM Corporation 1998, 2005