|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.opennms.bb.common.components.PCQueueFixedArray
The fixed array queue is a definitively sized array of elements that follow producer/consumer rules. All elements are added and removed in a FIFO fashion, just like a standard queue. However, the queue is designed to be shared with one or more producers and one or more consumers.
Even though the queue is shared, the elements in the queue are not. If there are two consumers A and B and A removes an element from the queue. The next element removed by B will not be the same object as removed by A, but the object that was next in the queue.
Field Summary | |
private Object[] |
m_elements
The actual references to the objects in the queue. |
private int |
m_iConsumerPos
The position where the next object will be removed from the array. |
private int |
m_iCount
The number of objects currently in the PCQueue. |
private int |
m_iProducerPos
The position where the next object will be inserted into the array. |
private boolean |
m_isOpen
If true the queue is open, else the queue is closed. |
private List |
m_oneShotNotifyOnAdd
The list of objects that should be notified when the next add call succeeds! |
private List |
m_oneShotNotifyOnRead
The list of objects that should be notified when the next read call succeeds! |
Constructor Summary | |
private |
PCQueueFixedArray()
Set private to pervent the creation of a default constructor. |
|
PCQueueFixedArray(int size)
Constructs the Producer/Consumer queue with the given size. |
Method Summary | |
void |
add(Object obj)
Adds the specified object to the tail of the producer/consumer queue. |
void |
clear()
Clears all the elements currently in the producer/consumer queue. |
void |
close()
Close the current queue. |
int |
entries()
Returns current number of entries in the queue. |
boolean |
isClosed()
Returns true if the queue is closed. |
boolean |
isEmpty()
This method is provided as a convience check to determine if the queue currently contains any elements. |
boolean |
isFull()
This method is provided as a convience check to determine if the queue is currently full. |
boolean |
isOpen()
Returns true if the queue is opened. |
void |
oneShotNotifyAllOnAdd(Object recipient)
This method is designed to be used by classes that are waiting on new objects to be added to the queue. |
void |
oneShotNotifyAllOnRead(Object recipient)
This method is designed to be used by classes that are waiting on objects to be read from a full queue. |
void |
open()
Open the queue. |
Object |
read()
Attempts to read the next object from the head of the producer/ consumer queue and return it to the caller. |
int |
size()
Returns total capacity of the queue. |
Methods inherited from class java.lang.Object |
|
Field Detail |
private int m_iProducerPos
private int m_iConsumerPos
private int m_iCount
private boolean m_isOpen
private Object[] m_elements
private List m_oneShotNotifyOnAdd
The list of objects that should be notified when the next add call succeeds!
private List m_oneShotNotifyOnRead
The list of objects that should be notified when the next read call succeeds!
Constructor Detail |
private PCQueueFixedArray() throws UnsupportedOperationException
Set private to pervent the creation of a default constructor. This method ALWAYS throws an UnsupportedOperationException.
UnsupportedOperationException
- Always thrown.public PCQueueFixedArray(int size)
size
- The number of elements that may be placed
into the queue before it blocks.IllegalArgumentException
- Thrown if the
size if zero or less than zero. The actual size must
be greater than zero.Method Detail |
public boolean isOpen()
Returns true if the queue is opened.
isOpen
in interface PCQueue
public boolean isClosed()
Returns true if the queue is closed.
isClosed
in interface PCQueue
public void open()
Open the queue.
open
in interface PCQueue
public void close()
Close the current queue.
close
in interface PCQueue
public void add(Object obj) throws InterruptedException, QueueClosedException
Adds the specified object to the tail of the producer/consumer queue. If the queue is currently at it's predefined limit then the call blocks until there is room in the queue.
If the queue is closed while the thread is waiting to add the object then an exception is thrown. Likewise, if the adding thread is interruped then an exception is thrown by the add method.
add
in interface PCQueue
obj
- The object to be added to the queue.InterruptedException
- Thrown if the adding
thread is interrrupted prior to completing the
addition of the object.org.opennmms.bb.common.components.QueueClosedException
- Thrown
if the queue is closed before the object is added to the
producer/consumer queue.public Object read() throws InterruptedException, QueueClosedException
Attempts to read the next object from the head of the producer/ consumer queue and return it to the caller. If there are no object in the queue currently then the call blocks until there is an object available.
If the queue is closed while the thread is waiting for an object then an exception is thrown. Likewise, if the reading thread is interrupted prior to reading an object then an exception is also thrown.
read
in interface PCQueue
InterruptedException
- Thrown if the adding
thread is interrrupted prior to completing the
reading of an object.org.opennmms.bb.common.components.QueueClosedException
- Thrown
if the queue is closed before the object is recovered from the
producer/consumer queue.public void clear()
Clears all the elements currently in the producer/consumer queue.
clear
in interface PCQueue
public int entries()
Returns current number of entries in the queue.
entries
in interface PCQueue
public int size()
Returns total capacity of the queue.
size
in interface PCQueue
public void oneShotNotifyAllOnAdd(Object recipient)
This method is designed to be used by classes that are waiting on new objects to be added to the queue. When an object is added to the queue after this call, the recipient object will have its notifyAll method called. The recipient will only be notified once, all subsuquent adds to the queue will not cause the recipient to be signaled.
If a recipient needs to be called after each add then it must repeatly re-register after each notification, however this does not guarentee notification for each add. The one shot notification is designed to be used by classes that check check for elements and find the list empty, they then call wait() to pause until more elements are available.
Note: If the recipient is not well behavied and continues to hold its lock when the add method is called, it could cause a deadlock condition. Recipients must either unregister or release their lock to receive notifications. Care should be taken when using this method.
oneShotNotifyAllOnAdd
in interface PCQueue
recipient
- The object to be signaled when then next add succeeds.public void oneShotNotifyAllOnRead(Object recipient)
This method is designed to be used by classes that are waiting on objects to be read from a full queue. When an object is read from the queue after this call, the recipient object will have its notifyAll method called. The recipient will only be notified once, all subsuquent reads to the queue will not cause the recipient to be signaled.
If a recipient needs to be called after each read then it must repeatly re-register after each notification, however this does not guarentee notification for each read. The one shot notification is designed to be used by classes that check check for elements and find the list full, they then call wait() to pause until more elements are available.
Note: If the recipient is not well behavied and continues to hold its lock when the add method is called, it could cause a deadlock condition. Recipients must either unregister or release their lock to receive notifications. Care should be taken when using this method.
oneShotNotifyAllOnRead
in interface PCQueue
recipient
- The object to be signaled when then next read succeeds.public boolean isEmpty()
This method is provided as a convience check to determine if the queue currently contains any elements. If the method returns true then there are no entries currently in the queue and a call to read will block until an object is added.
isEmpty
in interface PCQueue
public boolean isFull()
This method is provided as a convience check to determine if the queue is currently full. If the method returns true then there is no more room to place any elements and the next call to add will block until an object is removed.
If the PCQueue is not bounded then this method will always return false. To determine if the queue is bounded see the size method.
isFull
in interface PCQueue
size()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |