org.mentaqueue
Interface BatchingQueue<E>

Type Parameters:

E -

All Known Implementing Classes:

AtomicQueue, BlockingArrayQueue, BlockingLinkedQueue, BlockingQueue, BrokenFastQueue, ConcurrentLinkedQueue, LockedQueue, NonBatchingQueue, PooledBlockingArrayQueue, PooledBlockingLinkedQueue, PooledBlockingQueue, PooledConcurrentLinkedQueue, SynchronizedQueue, VolatileQueue

public interface BatchingQueue<E>

A queue API that allows batching and pooling of objects. So to offer to the queue, you first get a mutable object from the queue by calling nextToDispatch(), alter this object and call flush(boolean lazySet). That allows the queue objects to be pooled, avoiding any garbage collection. And to poll you first call availableToPoll() to know how many objects you can safely poll, call poll() in a loop and when done call donePolling(boolean lazySet). That allows polling to be batched, so you pay a synchronization price only when you call available() and NOT when you call poll().

Author:

Sergio Oliveira Jr.

Method Summary

long	availableToPoll() Return the number of objects that can be safely polled from this queue.
void	donePolling() Called to indicate that all polling have been concluded.
void	donePolling(boolean lazySet) Called to indicate that all polling have been concluded.
void	flush() Dispatch *immediately* all previously obtained objects through the nextToDispatch() method to the queue.
void	flush(boolean lazySet) Dispatch all previously obtained objects through the nextToDispatch() method to the queue.
E	nextToDispatch() Return the next pooled mutable object that can be used by the producer to dispatch data to the queue.
E	poll() Poll a object from the queue.
void	rollback() Pretend you never polled the last object you polled since the last time you called donePolling().

Method Detail

nextToDispatch

E nextToDispatch()

Return the next pooled mutable object that can be used by the producer to dispatch data to the queue.

Returns:

the next mutable object that can be used by the producer.

flush

void flush(boolean lazySet)

Dispatch all previously obtained objects through the nextToDispatch() method to the queue.

Parameters:

lazySet - flush (i.e. notify the consumer) in a lazy way or flush immediately

flush

void flush()

Dispatch *immediately* all previously obtained objects through the nextToDispatch() method to the queue.

availableToPoll

long availableToPoll()

Return the number of objects that can be safely polled from this queue. It can return zero.

Returns:

number of objects that can be polled.

poll

E poll()

Poll a object from the queue. You can only call this method after calling available() so you know what is the maximum times you can call it. NOTE: You should NOT keep your own reference for this mutable object. Read what you need to get from it and release its reference.

Returns:

an object from the queue.

donePolling

void donePolling(boolean lazySet)

Called to indicate that all polling have been concluded.

Parameters:

lazySet - notify the producer in a lazy way or notify the producer immediately

donePolling

void donePolling()

Called to indicate that all polling have been concluded.

rollback

void rollback()

Pretend you never polled the last object you polled since the last time you called donePolling(). You can call this as many times as you want before you call donePolling() and rollback any poll() you have done. This is unaffected by availableToPoll(). Only donePolling() reset the counter of the last polled objects. Because rollback() reset the counter of the last polled objects, you can even call it twice in a row and the second rollbac() will have no effect since you have polled anything.