org.ka2ddo.util

Class FastBlockingQueue<E>

java.lang.Object

java.util.AbstractCollection<E>

org.ka2ddo.util.FastBlockingQueue<E>

Type Parameters:

E - data type of queued records

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<E>, java.util.Collection<E>, java.util.concurrent.BlockingQueue<E>, java.util.Queue<E>

Direct Known Subclasses:

GenericTaggedQueue

public class FastBlockingQueue<E>
extends java.util.AbstractCollection<E>
implements java.util.concurrent.BlockingQueue<E>, java.io.Serializable

This attempts to make a simpler and faster FIFO queue than ArrayBlockingQueue with no guarantees regarding fairness, minimum execution time, and minimum transient memory allocations. Optimized for single producer and single consumer.

Author:

Andrew Pavlin, KA2DDO

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
FastBlockingQueue(int capacity) Create a FastBlockingQueue with the specified maximum queue backlog.

Method Summary

Modifier and Type	Method and Description
boolean	add(E e) Add an element to the queue, throwing an exception if the queue is full and has no more room.
void	clear() Remove everything from the queue.
boolean	contains(java.lang.Object o) Check if this queue contains the specified object (or at least an instance that matches by equals()).
int	drainTo(java.util.Collection<? super E> c) Removes all available elements from this queue and adds them to the given collection.
int	drainTo(java.util.Collection<? super E> c, int maxElements) Removes at most the given number of available elements from this queue and adds them to the given collection.
int	drainTo(E[] a) Removes at most the given number of available elements from this queue and adds them to the given array.
E	element() Retrieves, but does not remove, the head of this queue.
void	expandCapacity(int capacity) Enlarge the queue's backlog capacity.
boolean	fastOffer(E e) Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions.
int	fastSize() Returns the number of elements in this queue, not using synchronization to save time.
int	getCapacity() Report the total number of queue slots in the queue.
java.util.Iterator<E>	iterator() Returns an iterator over the elements contained in this collection.
boolean	offer(E e) Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions.
boolean	offer(E e, long timeout, java.util.concurrent.TimeUnit unit) Inserts the specified element into this queue, waiting up to the specified wait time if necessary for space to become available.
E	peek() Retrieves, but does not remove, the head of this queue, or returns null if this queue is empty.
E	poll() Retrieves and removes the head of this queue, or returns null if this queue is empty.
E	poll(long timeout, java.util.concurrent.TimeUnit unit) Retrieves and removes the head of this queue, waiting up to the specified wait time if necessary for an element to become available.
void	put(E e) Inserts the specified element into this queue, waiting if necessary for space to become available.
void	putAll(E[] e, int length) Inserts all the non-null elements in the specified array into this queue, waiting if necessary for sufficient space to become available.
int	remainingCapacity() Returns the number of additional elements that this queue can ideally (in the absence of memory or resource constraints) accept without blocking, or Integer.MAX_VALUE if there is no intrinsic limit.
E	remove() Retrieves and removes the head of this queue.
void	setCapacity(int capacity) Change the queue's backlog capacity.
int	size() Returns the number of elements in this queue.
E	take() Retrieves and removes the head of this queue, waiting if necessary until an element becomes available.

Methods inherited from class java.util.AbstractCollection

addAll, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.concurrent.BlockingQueue

remove

Methods inherited from interface java.util.Collection

addAll, containsAll, equals, hashCode, isEmpty, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray

Methods inherited from interface java.lang.Iterable

forEach

Constructor Detail

FastBlockingQueue

public FastBlockingQueue(int capacity)

Create a FastBlockingQueue with the specified maximum queue backlog.

Parameters:

capacity - int maximum capacity of queue

Method Detail

clear

public void clear()

Remove everything from the queue.

Specified by:

clear in interface java.util.Collection<E>

Overrides:

clear in class java.util.AbstractCollection<E>

drainTo

public int drainTo(java.util.Collection<? super E> c)

Removes all available elements from this queue and adds them to the given collection. A failure encountered while attempting to add elements to collection c may result in elements being in neither, either or both collections when the associated exception is thrown. Attempts to drain a queue to itself result in IllegalArgumentException. Further, the behavior of this operation is undefined if the specified collection is modified while the operation is in progress.

Specified by:

drainTo in interface java.util.concurrent.BlockingQueue<E>

Parameters:

c - the collection to transfer elements into

Returns:

the number of elements transferred

Throws:

java.lang.UnsupportedOperationException - if addition of elements is not supported by the specified collection

java.lang.ClassCastException - if the class of an element of this queue prevents it from being added to the specified collection

java.lang.NullPointerException - if the specified collection is null

java.lang.IllegalArgumentException - if the specified collection is this queue, or some property of an element of this queue prevents it from being added to the specified collection

iterator

public java.util.Iterator<E> iterator()

Returns an iterator over the elements contained in this collection. Note this iterator is not thread-safe and thereby an iterator instance should only be used by one thread.

Specified by:

iterator in interface java.lang.Iterable<E>

Specified by:

iterator in interface java.util.Collection<E>

Specified by:

iterator in class java.util.AbstractCollection<E>

Returns:

an iterator over the elements contained in this collection

size

public int size()

Returns the number of elements in this queue.

Specified by:

size in interface java.util.Collection<E>

Specified by:

size in class java.util.AbstractCollection<E>

Returns:

the number of elements in this collection

fastSize

public final int fastSize()

Returns the number of elements in this queue, not using synchronization to save time. As such, the answer may be inaccurate, but it will be obtained quicker.

Returns:

the number of elements in this collection

put

public void put(E e)
         throws java.lang.InterruptedException

Inserts the specified element into this queue, waiting if necessary for space to become available.

Specified by:

put in interface java.util.concurrent.BlockingQueue<E>

Parameters:

e - the element to add

Throws:

java.lang.InterruptedException - if interrupted while waiting

java.lang.ClassCastException - if the class of the specified element prevents it from being added to this queue

java.lang.NullPointerException - if the specified element is null

java.lang.IllegalArgumentException - if some property of the specified element prevents it from being added to this queue

putAll

public void putAll(E[] e,
                   int length)
            throws java.lang.InterruptedException

Inserts all the non-null elements in the specified array into this queue, waiting if necessary for sufficient space to become available.

Parameters:

e - the array of elements to add

length - the int length of the array to test (not all of array may be in use)

Throws:

java.lang.InterruptedException - if interrupted while waiting

java.lang.ClassCastException - if the class of the specified element prevents it from being added to this queue

java.lang.NullPointerException - if the specified element is null

java.lang.IllegalArgumentException - if some property of the specified element prevents it from being added to this queue

offer

public boolean offer(E e,
                     long timeout,
                     java.util.concurrent.TimeUnit unit)
              throws java.lang.InterruptedException

Inserts the specified element into this queue, waiting up to the specified wait time if necessary for space to become available.

Specified by:

offer in interface java.util.concurrent.BlockingQueue<E>

Parameters:

e - the element to add

timeout - how long to wait before giving up, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

true if successful, or false if the specified waiting time elapses before space is available

Throws:

java.lang.InterruptedException - if interrupted while waiting

java.lang.ClassCastException - if the class of the specified element prevents it from being added to this queue

java.lang.NullPointerException - if the specified element is null

java.lang.IllegalArgumentException - if some property of the specified element prevents it from being added to this queue

take

public E take()
       throws java.lang.InterruptedException

Retrieves and removes the head of this queue, waiting if necessary until an element becomes available.

Specified by:

take in interface java.util.concurrent.BlockingQueue<E>

Returns:

the head of this queue

Throws:

java.lang.InterruptedException - if interrupted while waiting

poll

public E poll(long timeout,
              java.util.concurrent.TimeUnit unit)
       throws java.lang.InterruptedException

Retrieves and removes the head of this queue, waiting up to the specified wait time if necessary for an element to become available.

Specified by:

poll in interface java.util.concurrent.BlockingQueue<E>

Parameters:

timeout - how long to wait before giving up, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

the head of this queue, or null if the specified waiting time elapses before an element is available

Throws:

java.lang.InterruptedException - if interrupted while waiting

remainingCapacity

public int remainingCapacity()

Returns the number of additional elements that this queue can ideally (in the absence of memory or resource constraints) accept without blocking, or Integer.MAX_VALUE if there is no intrinsic limit.

Note that you cannot always tell if an attempt to insert an element will succeed by inspecting remainingCapacity because it may be the case that another thread is about to insert or remove an element.

Specified by:

remainingCapacity in interface java.util.concurrent.BlockingQueue<E>

Returns:

the remaining capacity

drainTo

public int drainTo(java.util.Collection<? super E> c,
                   int maxElements)

Removes at most the given number of available elements from this queue and adds them to the given collection. A failure encountered while attempting to add elements to collection c may result in elements being in neither, either or both collections when the associated exception is thrown. Attempts to drain a queue to itself result in IllegalArgumentException. Further, the behavior of this operation is undefined if the specified collection is modified while the operation is in progress.

Specified by:

drainTo in interface java.util.concurrent.BlockingQueue<E>

Parameters:

c - the collection to transfer elements into

maxElements - the maximum number of elements to transfer

Returns:

the number of elements transferred

Throws:

java.lang.UnsupportedOperationException - if addition of elements is not supported by the specified collection

java.lang.ClassCastException - if the class of an element of this queue prevents it from being added to the specified collection

java.lang.NullPointerException - if the specified collection is null

java.lang.IllegalArgumentException - if the specified collection is this queue, or some property of an element of this queue prevents it from being added to the specified collection

drainTo

public int drainTo(E[] a)

Removes at most the given number of available elements from this queue and adds them to the given array. A failure encountered while attempting to add elements to array a may result in elements being in neither, either or both queue and array when the associated exception is thrown. Further, the behavior of this operation is undefined if the specified array is modified while the operation is in progress.

Parameters:

a - the array to transfer elements into

Returns:

the number of elements transferred

Throws:

java.lang.ClassCastException - if the class of an element of this queue prevents it from being added to the specified array

java.lang.NullPointerException - if the specified array is null

java.lang.IllegalArgumentException - if some property of an element of this queue prevents it from being added to the specified array

offer

public boolean offer(E e)

Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions. When using a capacity-restricted queue like this class, this method is generally preferable to add(E), which can fail to insert an element only by throwing an exception.

Specified by:

offer in interface java.util.concurrent.BlockingQueue<E>

Specified by:

offer in interface java.util.Queue<E>

Parameters:

e - the element to add

Returns:

true if the element was added to this queue, else false

Throws:

java.lang.ClassCastException - if the class of the specified element prevents it from being added to this queue

java.lang.NullPointerException - if the specified element is null and this queue does not permit null elements

java.lang.IllegalArgumentException - if some property of this element prevents it from being added to this queue

fastOffer

public boolean fastOffer(E e)

Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions. When using a capacity-restricted queue like this class, this method is generally preferable to add(E), which can fail to insert an element only by throwing an exception.

Note that this method should not be used and the offer(Object) method should be used instead if

1. the consumer of this queue will be using take() and
2. the consumer is faster than the producer thread and
3. the consumer does not confirm there is something in the queue (by calling size() or fastSize()) before calling take(),

as this method (to save CPU time) does not notify the consumer thread on each successful offer, but only when the queue is completely full.

Parameters:

e - the element to add

Returns:

true if the element was added to this queue, else false

Throws:

java.lang.ClassCastException - if the class of the specified element prevents it from being added to this queue

java.lang.NullPointerException - if the specified element is null and this queue does not permit null elements

java.lang.IllegalArgumentException - if some property of this element prevents it from being added to this queue

add

public boolean add(E e)

Add an element to the queue, throwing an exception if the queue is full and has no more room.

Specified by:

add in interface java.util.Collection<E>

Specified by:

add in interface java.util.concurrent.BlockingQueue<E>

Specified by:

add in interface java.util.Queue<E>

Overrides:

add in class java.util.AbstractCollection<E>

Throws:

java.lang.IllegalStateException - if queue is already full

poll

public E poll()

Retrieves and removes the head of this queue, or returns null if this queue is empty.

Specified by:

poll in interface java.util.Queue<E>

Returns:

the head of this queue, or null if this queue is empty

peek

public E peek()

Retrieves, but does not remove, the head of this queue, or returns null if this queue is empty.

Specified by:

peek in interface java.util.Queue<E>

Returns:

the head of this queue, or null if this queue is empty

element

public E element()

Retrieves, but does not remove, the head of this queue. This method differs from peek only in that it throws an exception if this queue is empty.

This implementation returns the result of peek unless the queue is empty.

Specified by:

element in interface java.util.Queue<E>

Returns:

the head of this queue

Throws:

java.util.NoSuchElementException - if this queue is empty

remove

public E remove()

Retrieves and removes the head of this queue. This method differs from poll only in that it throws an exception if this queue is empty.

This implementation returns the result of poll unless the queue is empty.

Specified by:

remove in interface java.util.Queue<E>

Returns:

the head of this queue

Throws:

java.util.NoSuchElementException - if this queue is empty

contains

public boolean contains(java.lang.Object o)

Check if this queue contains the specified object (or at least an instance that matches by equals()).

Specified by:

contains in interface java.util.Collection<E>

Specified by:

contains in interface java.util.concurrent.BlockingQueue<E>

Overrides:

contains in class java.util.AbstractCollection<E>

getCapacity

public int getCapacity()

Report the total number of queue slots in the queue.

Returns:

maximum backlog capacity of the queue

expandCapacity

public void expandCapacity(int capacity)

Enlarge the queue's backlog capacity. Note this is a no-op if the specified parameter is less than or equal to the current capacity of the queue.

Parameters:

capacity - the new backlog capacity for the queue

setCapacity

public void setCapacity(int capacity)
                 throws java.lang.IllegalArgumentException

Change the queue's backlog capacity. Note this will throw an exception if the specified parameter is less than the current contents of the queue.

Parameters:

capacity - the new backlog capacity for the queue

Throws:

java.lang.IllegalArgumentException - if new capacity is less than the number of entries still in the queue