com.resilientedge.util.workerPool
Class WaitQueue

java.lang.Object
  |
  +--com.resilientedge.util.workerPool.WaitQueue

public class WaitQueue

extends java.lang.Object

This class provides a queuing mechanism so threads may wait for notification of an event, and are notified in FIFO order. A worker thread is 'added' to this queue with add(...) method. Notification is requested through notifyNext() method, and notification is provided only for the next item in the queue.

Logically the worker thread may be thought of as being in the queue, but actually a q-item is maintained in the queue. A worker thread that is added to the queue, has a q-item that is associated with the thread that is actually added to the queue. The thread waits for either notification its associated q-item has been removed from the queue, or its wait-time has expired.

It is possible for a worker thread to be 'added' to the queue, right after a notify has been tried for on an empty queue, because of the nature of multi-threaded programs. If no other notifications are attempted the 'added' worker thread will wait until the specified wait-time expires. Therefore if unlimited wait time is supported an external (outside of this class) mechanism must be implemented to ensure this scenario doesn't occur or the worker thread will be in an indefinite wait. Additionally, even if wait-times are used, the object returned when the worker thread completes the 'add' process should always be examined to determine if completion was the result of a wait-time expiration and appropriate action taken if true.

Queue statistics are maintained by an instance of WaitQStats. These statistics may be examined via getQStats .

Author:

jgardner

Constructor Summary

WaitQueue()
Default constructor.

WaitQueue(java.lang.String id)
Constructor to specify an identifier for the queue.

Method Summary

java.lang.Object	add() Add the current thread to the wait queue, and have it wait indefinitely for the resource to become available.
java.lang.Object	add(long waitTime) Add the current thread to the wait queue.
java.lang.Object	add(java.lang.Object evtObj, long waitTime) Add the current thread to the wait queue.
protected WaitQStats	createStats(java.lang.String id)
WaitQStats	getQStats()
boolean	notifyNext(java.lang.Object evtObj) Remove the next item in the queue and notify the corresponding thread the item has been removed.

Methods inherited from class java.lang.Object

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

Constructor Detail

WaitQueue

public WaitQueue()

Default constructor.

WaitQueue

public WaitQueue(java.lang.String id)

Constructor to specify an identifier for the queue.

Parameters:

id - a queue identifier

Method Detail

getQStats

public WaitQStats getQStats()

Returns:

a copy of the current statistics

add

public java.lang.Object add()

Add the current thread to the wait queue, and have it wait indefinitely for the resource to become available.

Returns:

the object that was provided when notifyNext() is requested. If time-out occurs this value is always null.

See Also:

add

public java.lang.Object add(long waitTime)

Add the current thread to the wait queue.

Parameters:

waitTime - the maximum time to wait in milliseconds, if the value is zero,the thread waits until notified

Returns:

the object that was provided when notifyNext() is requested. If time-out occurs this value is always null.

See Also:

add

public java.lang.Object add(java.lang.Object evtObj,
                            long waitTime)

Add the current thread to the wait queue. A queue item is created for the thread, and added to the queue. The thread is synchronized on the new item, and waits for the specified period of time for notification to occur. Notification is provided when the item is removed from the queue via the notifyNext() method.

Parameters:

evtObj - an object to be returned if the maximum wait time is exceeded (or the wait is interrupted), it may be null

waitTime - the maximum time to wait in milliseconds, it must be greater than or equal to zero. if the value is zero, the thread waits idefinitely until notification is provided.

Returns:

the object that was provided when notifyNext() is requested or the original event object if the the maximum wait time is exceeded.

notifyNext

public boolean notifyNext(java.lang.Object evtObj)

Remove the next item in the queue and notify the corresponding thread the item has been removed.

Parameters:

evtObj - the object that is to be given to the item when it is removed from the queue. This object is returned when the thread associated with the q-item awakens. This may be null.

Returns:

true if an item was available, false if the queue is empty and nothing notified

createStats

protected WaitQStats createStats(java.lang.String id)

Parameters:

id - Parameter Description

Returns:

a new instance of the queue statistics.