Project JXTA

net.jxta.impl.util
Class ConsumerBiasedQueue

java.lang.Object
  extended by net.jxta.impl.util.UnbiasedQueue
      extended by 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.


Nested Class Summary
 
Nested classes/interfaces inherited from class net.jxta.impl.util.UnbiasedQueue
UnbiasedQueue.SynchronizedQueue
 
Field Summary
 
Fields inherited from class net.jxta.impl.util.UnbiasedQueue
closeFlag, DEFAULT_MAX_OBJECTS, DROP_OLDEST_OBJECT, dropOldestObject, DROPPED_OBJECT_WARNING_INTERVAL, maxObjects, nextDroppedWarn, numDequeued, numDropped, numEnqueued, queue, sumOfQueueSizesDequeue, sumOfQueueSizesEnqueue
 
Constructor Summary
ConsumerBiasedQueue()
          Default constructor. 100 element FIFO queue which drops oldest element when full.
ConsumerBiasedQueue(int size, boolean dropOldest)
          Full featured constructor for creating a new ConsumerBiasedQueue.
 
Method Summary
 void clear()
          Flush the queue of all pending objects.
 double getAvgInQueueAtDequeue()
          Return the average number of elements in the queue at dequeue time.
 double getAvgInQueueAtEnqueue()
          Return the average number of elements in the queue at Enqueue time.
 int getCurrentInQueue()
          Return the number of elements currently in the queue.
 Object pop()
          Return next obj in the queue if there is one.
 Object[] popMulti(int maxObjs)
          Returns an array of objects, possibly empty, from the queue.
 boolean push(Object obj)
          Attempt to push an object onto the queue.
 boolean push(Object obj, long timeout)
          Push an object onto the queue.
 void setMaxQueueSize(int maxObjs)
          Set how many objects this queue may store.
 
Methods inherited from class net.jxta.impl.util.UnbiasedQueue
close, getMaxQueueSize, getNumDequeued, getNumDropped, getNumEnqueued, interrupt, isClosed, peek, pop, pushBack, pushBack, synchronizedQueue, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

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.
Method Detail

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.

JXTA J2SE