net.jxta.impl.util
Class ConsumerBiasedQueue

java.lang.Object
  net.jxta.impl.util.UnbiasedQueue
      net.jxta.impl.util.ConsumerBiasedQueue

public class ConsumerBiasedQueue
extends UnbiasedQueue

A queue who's implementation is biased towards effciency in removing elements from the queue. FIXME 20020511 bondolo@jxta.org This could be more efficient with a circular queue implementation, but its a pain to write since we allow the queue to be resizable. FIXME 20020511 bondolo@jxta.org Exercise for the reader: Extend this class so that it does both LIFO and FIFO.

ConsumerBiasedQueue

public ConsumerBiasedQueue()

Default constructor. 100 element FIFO queue which drops oldest element when full.

ConsumerBiasedQueue

public ConsumerBiasedQueue(int size,
                           boolean dropOldest)

Full featured constructor for creating a new ConsumerBiasedQueue.

Parameters:

size - Queue will be not grow larger than this size. Use Integer.MAX_VALUE for "unbounded" queue size.

dropOldest - Controls behaviour of element insertion when the queue is full. If "true" and the queue is full upon a push operation then the oldest element will be dropped to be replaced with the element currently being pushed. If "false" then then newest item will be dropped.

clear

public void clear()

Flush the queue of all pending objects.

Overrides:

clear in class UnbiasedQueue

push

public boolean push(Object obj)

Description copied from class: UnbiasedQueue

Attempt to push an object onto the queue. If the queue is full then the object will not be pushed. This method does not use any synchronization and should not be used if other threads are using UnbiasedQueue.pop(long) to retrieve elements.

Overrides:

push in class UnbiasedQueue

Parameters:

obj - object to push

Returns:

true if the obj was pushed, otherwise false.

push

public boolean push(Object obj,
                    long timeout)
             throws InterruptedException

Push an object onto the queue. If the queue is full then the push will wait for up to "timeout" milliseconds to push the object. At the end of "timeout" milliseconds, the push will either return false or remove the oldest item from the queue and insert "obj". This behaviour is contolled by the constructor parameter "dropOldest". This method, unlike all others is synchronized. This creates a bottleneck for producers seperate from the primary lock on the "queue" member. This reduces contention on the primary lock which benefits users who are popping items from the queue (Consumers).

Overrides:

push in class UnbiasedQueue

Parameters:

obj - Object to be pushed onto the queue

timeout - Time in milliseconds to try to insert the item into a full queue. Per Java standards, a timeout of "0" (zero) will wait indefinitly. Negative values force no wait period at all.

Returns:

true if the object was intersted into the queue, otherwise false.

Throws:

InterruptedException - if the operation is interrupted before the timeout interval is completed.

pop

public Object pop()

Return next obj in the queue if there is one.

Overrides:

pop in class UnbiasedQueue

Returns:

Object, null if the queue is empty

popMulti

public Object[] popMulti(int maxObjs)

Returns an array of objects, possibly empty, from the queue.

Overrides:

popMulti in class UnbiasedQueue

Parameters:

maxObjs - the maximum number of items to return.

Returns:

an array of objects, possibly empty containing the returned queue elements.

setMaxQueueSize

public void setMaxQueueSize(int maxObjs)

Set how many objects this queue may store. Note that if there are more objects already in the queue than the specified amount then the queue will retain its current capacity.

Overrides:

setMaxQueueSize in class UnbiasedQueue

Parameters:

maxObjs - The number of objects which the queue must be able to store.

getCurrentInQueue

public int getCurrentInQueue()

Return the number of elements currently in the queue. This method is useful for statistical sampling, but should not be used to determine program logic due to the multi-threaded behaviour of these queues. You should use the return values and timeout behaviour of the push() and pop() methods to regulate how you use the queue.

Overrides:

getCurrentInQueue in class UnbiasedQueue

Returns:

the number of elements currently in the queue. Be warned that even two sequential calls to this method may return different answers due to activity on other threads.

getAvgInQueueAtEnqueue

public double getAvgInQueueAtEnqueue()

Return the average number of elements in the queue at Enqueue time.

Overrides:

getAvgInQueueAtEnqueue in class UnbiasedQueue

Returns:

average number of elements which were in the queue at during all of the "push" operations which returned a "true" result. Does not include the item being pushed. If no elements have ever been enqueued then "NaN" will be returned.

getAvgInQueueAtDequeue

public double getAvgInQueueAtDequeue()

Return the average number of elements in the queue at dequeue time.

Overrides:

getAvgInQueueAtDequeue in class UnbiasedQueue

Returns:

average number of elements which were in the queue at during all of the "pop" operations which returned a non-null result. Includes the item being "pop"ed in the average. If no elements have ever been dequeued then "NaN" will be returned.