|
Class ConsumerBiasedQueue
|
|
public class ConsumerBiasedQueue
Extends:
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.
| Field Summary |
private final static Logger |
Log4J |
| Constructor Summary |
public |
Default constructor. |
public |
Full featured constructor for creating a new ConsumerBiasedQueue. |
| Method Summary |
public void |
Flush the queue of all pending objects. |
public double |
Return the average number of elements in the queue at dequeue time. |
public double |
Return the average number of elements in the queue at Enqueue time. |
public int |
Return the number of elements currently in the queue. |
public Object |
Return next obj in the queue if there is one. |
public Object |
Returns an array of objects, possibly empty, from the queue. |
public synchronized boolean |
|
public synchronized boolean |
push(Object obj, long timeout) Push an object onto the queue. |
public void |
Set how many objects this queue may store. |
private final static Logger LOG = Logger.getLogger(ConsumerBiasedQueue.class.getName())
Log4J
public ConsumerBiasedQueue()
Default constructor. 100 element FIFO queue which drops oldest element
when full.
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.
public void clear()
Flush the queue of all pending objects.
public double getAvgInQueueAtDequeue()
Return the average number of elements in the queue at dequeue time.
Return:
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.
public double getAvgInQueueAtEnqueue()
Return the average number of elements in the queue at Enqueue time.
Return:
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.
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.
Return:
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.
public Object pop()
Return next obj in the queue if there is one.
Return:
Object, null if the queue is empty
public Object popMulti(int maxObjs)
Returns an array of objects, possibly empty, from the queue.
Parameters:
maxObjs the maximum number of items to return.
Return:
an array of objects, possibly empty containing the returned
queue elements.
public synchronized boolean push(Object obj)
public synchronized boolean push(Object obj, long timeout)
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).
Throws:
InterruptedException
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.
Return:
true if the object was intersted into the queue, otherwise false.
throws:
InterruptedException if the operation is interrupted before
the timeout interval is completed.
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.
Parameters:
maxObjs The number of objects which the queue must be able to
store.