Class LinkedBlockingDeque<E>
- Type Parameters:
E
- the type of elements held in this collection Note: This was copied from Apache Harmony and modified to suit the needs of Commons Pool.
- All Implemented Interfaces:
Serializable
,Iterable<E>
,Collection<E>
,Deque<E>
,Queue<E>
,SequencedCollection<E>
The optional capacity bound constructor argument serves as a
way to prevent excessive expansion. The capacity, if unspecified,
is equal to Integer.MAX_VALUE
. Linked nodes are
dynamically created upon each insertion unless this would bring the
deque above capacity.
Most operations run in constant time (ignoring time spent
blocking). Exceptions include remove
,
removeFirstOccurrence
, removeLastOccurrence
, contains
, iterator.remove()
, and the bulk
operations, all of which run in linear time.
This class and its iterator implement all of the
optional methods of the Collection
and Iterator
interfaces.
This class is a member of the Java Collections Framework.
- Since:
- 2.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate class
Base class for Iterators for LinkedBlockingDequeprivate class
Descending iteratorprivate class
Forward iteratorprivate static final class
Doubly-linked list node class. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final int
Maximum number of items in the dequeprivate int
Number of items in the dequeprivate LinkedBlockingDeque.Node
<E> Pointer to first node.private LinkedBlockingDeque.Node
<E> Pointer to last node.private final InterruptibleReentrantLock
Main lock guarding all accessprivate final Condition
Condition for waiting takesprivate final Condition
Condition for waiting putsprivate static final long
-
Constructor Summary
ConstructorsConstructorDescriptionCreates aLinkedBlockingDeque
with a capacity ofInteger.MAX_VALUE
.LinkedBlockingDeque
(boolean fairness) Creates aLinkedBlockingDeque
with a capacity ofInteger.MAX_VALUE
and the given fairness policy.LinkedBlockingDeque
(int capacity) Creates aLinkedBlockingDeque
with the given (fixed) capacity.LinkedBlockingDeque
(int capacity, boolean fairness) Creates aLinkedBlockingDeque
with the given (fixed) capacity and fairness policy.LinkedBlockingDeque
(Collection<? extends E> c) Creates aLinkedBlockingDeque
with a capacity ofInteger.MAX_VALUE
, initially containing the elements of the given collection, added in traversal order of the collection's iterator. -
Method Summary
Modifier and TypeMethodDescriptionboolean
void
void
void
clear()
Atomically removes all of the elements from this deque.boolean
Returnstrue
if this deque contains the specified element.int
drainTo
(Collection<? super E> c) Drains the queue to the specified collection.int
drainTo
(Collection<? super E> c, int maxElements) Drains no more than the specified number of elements from the queue to the specified collection.element()
Retrieves, but does not remove, the head of the queue represented by this deque.getFirst()
getLast()
int
Returns the length of the queue of threads waiting to take instances from this deque.boolean
Returns true if there are threads waiting to take instances from this deque.void
Interrupts the threads currently waiting to take an object from the pool.iterator()
Returns an iterator over the elements in this deque in proper sequence.private boolean
Links provided element as first element, or returns false if full.private boolean
Links provided element as last element, or returns false if full.boolean
boolean
Links the provided element as the last in the queue, waiting up to the specified time to do so if the queue is full.boolean
offerFirst
(E e) boolean
offerFirst
(E e, long timeout, TimeUnit unit) Links the provided element as the first in the queue, waiting up to the specified time to do so if the queue is full.boolean
boolean
Links the provided element as the last in the queue, waiting up to the specified time to do so if the queue is full.peek()
peekLast()
poll()
Unlinks the first element in the queue, waiting up to the specified time to do so if the queue is empty.Unlinks the first element in the queue, waiting up to the specified time to do so if the queue is empty.pollLast()
Unlinks the last element in the queue, waiting up to the specified time to do so if the queue is empty.pop()
void
void
Links the provided element as the last in the queue, waiting until there is space to do so if the queue is full.void
Links the provided element as the first in the queue, waiting until there is space to do so if the queue is full.void
Links the provided element as the last in the queue, waiting until there is space to do so if the queue is full.private void
Reconstitutes this deque from a stream (that is, deserialize it).int
Returns the number of additional elements that this deque can ideally (in the absence of memory or resource constraints) accept without blocking.remove()
Retrieves and removes the head of the queue represented by this deque.boolean
Removes the first occurrence of the specified element from this deque.boolean
boolean
int
size()
Returns the number of elements in this deque.take()
Unlinks the first element in the queue, waiting until there is an element to unlink if the queue is empty.Unlinks the first element in the queue, waiting until there is an element to unlink if the queue is empty.takeLast()
Unlinks the last element in the queue, waiting until there is an element to unlink if the queue is empty.Object[]
toArray()
Returns an array containing all of the elements in this deque, in proper sequence (from first to last element).<T> T[]
toArray
(T[] a) toString()
private void
Unlinks the provided node.private E
Removes and returns the first element, or null if empty.private E
Removes and returns the last element, or null if empty.private void
Saves the state of this deque to a stream (that is, serialize it).Methods inherited from class java.util.AbstractQueue
addAll
Methods inherited from class java.util.AbstractCollection
containsAll, isEmpty, removeAll, retainAll
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.util.Collection
containsAll, equals, hashCode, isEmpty, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray
-
Field Details
-
serialVersionUID
private static final long serialVersionUID- See Also:
-
first
Pointer to first node. Invariant: (first == null invalid input: '&'invalid input: '&' last == null) || (first.prev == null invalid input: '&'invalid input: '&' first.item != null) -
last
Pointer to last node. Invariant: (first == null invalid input: '&'invalid input: '&' last == null) || (last.next == null invalid input: '&'invalid input: '&' last.item != null) -
count
private transient int countNumber of items in the deque -
capacity
private final int capacityMaximum number of items in the deque -
lock
Main lock guarding all access -
notEmpty
Condition for waiting takes -
notFull
Condition for waiting puts
-
-
Constructor Details
-
LinkedBlockingDeque
public LinkedBlockingDeque()Creates aLinkedBlockingDeque
with a capacity ofInteger.MAX_VALUE
. -
LinkedBlockingDeque
public LinkedBlockingDeque(boolean fairness) Creates aLinkedBlockingDeque
with a capacity ofInteger.MAX_VALUE
and the given fairness policy.- Parameters:
fairness
- true means threads waiting on the deque should be served as if waiting in a FIFO request queue
-
LinkedBlockingDeque
public LinkedBlockingDeque(int capacity) Creates aLinkedBlockingDeque
with the given (fixed) capacity.- Parameters:
capacity
- the capacity of this deque- Throws:
IllegalArgumentException
- ifcapacity
is less than 1
-
LinkedBlockingDeque
public LinkedBlockingDeque(int capacity, boolean fairness) Creates aLinkedBlockingDeque
with the given (fixed) capacity and fairness policy.- Parameters:
capacity
- the capacity of this dequefairness
- true means threads waiting on the deque should be served as if waiting in a FIFO request queue- Throws:
IllegalArgumentException
- ifcapacity
is less than 1
-
LinkedBlockingDeque
Creates aLinkedBlockingDeque
with a capacity ofInteger.MAX_VALUE
, initially containing the elements of the given collection, added in traversal order of the collection's iterator.- Parameters:
c
- the collection of elements to initially contain- Throws:
NullPointerException
- if the specified collection or any of its elements are null
-
-
Method Details
-
linkFirst
Links provided element as first element, or returns false if full.- Parameters:
e
- The element to link as the first element.- Returns:
true
if successful, otherwisefalse
-
linkLast
Links provided element as last element, or returns false if full.- Parameters:
e
- The element to link as the last element.- Returns:
true
if successful, otherwisefalse
-
unlinkFirst
Removes and returns the first element, or null if empty.- Returns:
- The first element or
null
if empty
-
unlinkLast
Removes and returns the last element, or null if empty.- Returns:
- The first element or
null
if empty
-
unlink
Unlinks the provided node.- Parameters:
x
- The node to unlink
-
addFirst
-
addLast
-
offerFirst
- Specified by:
offerFirst
in interfaceDeque<E>
-
offerLast
-
putFirst
Links the provided element as the first in the queue, waiting until there is space to do so if the queue is full.- Parameters:
e
- element to link- Throws:
NullPointerException
- if e is nullInterruptedException
- if the thread is interrupted whilst waiting for space
-
putLast
Links the provided element as the last in the queue, waiting until there is space to do so if the queue is full.- Parameters:
e
- element to link- Throws:
NullPointerException
- if e is nullInterruptedException
- if the thread is interrupted whilst waiting for space
-
offerFirst
Links the provided element as the first in the queue, waiting up to the specified time to do so if the queue is full.- Parameters:
e
- element to linktimeout
- length of time to waitunit
- units that timeout is expressed in- Returns:
true
if successful, otherwisefalse
- Throws:
NullPointerException
- if e is nullInterruptedException
- if the thread is interrupted whilst waiting for space
-
offerLast
Links the provided element as the last in the queue, waiting up to the specified time to do so if the queue is full.- Parameters:
e
- element to linktimeout
- length of time to waitunit
- units that timeout is expressed in- Returns:
true
if successful, otherwisefalse
- Throws:
NullPointerException
- if e is nullInterruptedException
- if the thread is interrupted whist waiting for space
-
removeFirst
- Specified by:
removeFirst
in interfaceDeque<E>
- Specified by:
removeFirst
in interfaceSequencedCollection<E>
-
removeLast
- Specified by:
removeLast
in interfaceDeque<E>
- Specified by:
removeLast
in interfaceSequencedCollection<E>
-
pollFirst
-
pollLast
-
takeFirst
Unlinks the first element in the queue, waiting until there is an element to unlink if the queue is empty.- Returns:
- the unlinked element
- Throws:
InterruptedException
- if the current thread is interrupted
-
takeLast
Unlinks the last element in the queue, waiting until there is an element to unlink if the queue is empty.- Returns:
- the unlinked element
- Throws:
InterruptedException
- if the current thread is interrupted
-
pollFirst
Unlinks the first element in the queue, waiting up to the specified time to do so if the queue is empty.- Parameters:
timeout
- length of time to waitunit
- units that timeout is expressed in- Returns:
- the unlinked element
- Throws:
InterruptedException
- if the current thread is interrupted
-
pollLast
Unlinks the last element in the queue, waiting up to the specified time to do so if the queue is empty.- Parameters:
timeout
- length of time to waitunit
- units that timeout is expressed in- Returns:
- the unlinked element
- Throws:
InterruptedException
- if the current thread is interrupted
-
getFirst
-
getLast
-
peekFirst
-
peekLast
-
removeFirstOccurrence
- Specified by:
removeFirstOccurrence
in interfaceDeque<E>
-
removeLastOccurrence
- Specified by:
removeLastOccurrence
in interfaceDeque<E>
-
add
-
offer
-
put
Links the provided element as the last in the queue, waiting until there is space to do so if the queue is full.This method is equivalent to
putLast(Object)
.- Parameters:
e
- element to link- Throws:
NullPointerException
- if e is nullInterruptedException
- if the thread is interrupted whilst waiting for space
-
offer
Links the provided element as the last in the queue, waiting up to the specified time to do so if the queue is full.This method is equivalent to
offerLast(Object, long, TimeUnit)
- Parameters:
e
- element to linktimeout
- length of time to waitunit
- units that timeout is expressed in- Returns:
true
if successful, otherwisefalse
- Throws:
NullPointerException
- if e is nullInterruptedException
- if the thread is interrupted whilst waiting for space
-
remove
Retrieves and removes the head of the queue represented by this deque. This method differs frompoll
only in that it throws an exception if this deque is empty.This method is equivalent to
removeFirst
.- Specified by:
remove
in interfaceDeque<E>
- Specified by:
remove
in interfaceQueue<E>
- Overrides:
remove
in classAbstractQueue<E>
- Returns:
- the head of the queue represented by this deque
- Throws:
NoSuchElementException
- if this deque is empty
-
poll
-
take
Unlinks the first element in the queue, waiting until there is an element to unlink if the queue is empty.This method is equivalent to
takeFirst()
.- Returns:
- the unlinked element
- Throws:
InterruptedException
- if the current thread is interrupted
-
poll
Unlinks the first element in the queue, waiting up to the specified time to do so if the queue is empty.This method is equivalent to
pollFirst(long, TimeUnit)
.- Parameters:
timeout
- length of time to waitunit
- units that timeout is expressed in- Returns:
- the unlinked element
- Throws:
InterruptedException
- if the current thread is interrupted
-
element
Retrieves, but does not remove, the head of the queue represented by this deque. This method differs frompeek
only in that it throws an exception if this deque is empty.This method is equivalent to
getFirst
.- Specified by:
element
in interfaceDeque<E>
- Specified by:
element
in interfaceQueue<E>
- Overrides:
element
in classAbstractQueue<E>
- Returns:
- the head of the queue represented by this deque
- Throws:
NoSuchElementException
- if this deque is empty
-
peek
-
remainingCapacity
public int remainingCapacity()Returns the number of additional elements that this deque can ideally (in the absence of memory or resource constraints) accept without blocking. This is always equal to the initial capacity of this deque less the currentsize
of this deque.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.- Returns:
- The number of additional elements the queue is able to accept
-
drainTo
Drains the queue to the specified collection.- Parameters:
c
- The collection to add the elements to- Returns:
- number of elements added to the collection
- Throws:
UnsupportedOperationException
- if the add operation is not supported by the specified collectionClassCastException
- if the class of the elements held by this collection prevents them from being added to the specified collectionNullPointerException
- if c is nullIllegalArgumentException
- if c is this instance
-
drainTo
Drains no more than the specified number of elements from the queue to the specified collection.- Parameters:
c
- collection to add the elements tomaxElements
- maximum number of elements to remove from the queue- Returns:
- number of elements added to the collection
- Throws:
UnsupportedOperationException
- if the add operation is not supported by the specified collectionClassCastException
- if the class of the elements held by this collection prevents them from being added to the specified collectionNullPointerException
- if c is nullIllegalArgumentException
- if c is this instance
-
push
-
pop
-
remove
Removes the first occurrence of the specified element from this deque. If the deque does not contain the element, it is unchanged. More formally, removes the first elemente
such thato.equals(e)
(if such an element exists). Returnstrue
if this deque contained the specified element (or equivalently, if this deque changed as a result of the call).This method is equivalent to
removeFirstOccurrence
.- Specified by:
remove
in interfaceCollection<E>
- Specified by:
remove
in interfaceDeque<E>
- Overrides:
remove
in classAbstractCollection<E>
- Parameters:
o
- element to be removed from this deque, if present- Returns:
true
if this deque changed as a result of the call
-
size
public int size()Returns the number of elements in this deque.- Specified by:
size
in interfaceCollection<E>
- Specified by:
size
in interfaceDeque<E>
- Specified by:
size
in classAbstractCollection<E>
- Returns:
- the number of elements in this deque
-
contains
Returnstrue
if this deque contains the specified element. More formally, returnstrue
if and only if this deque contains at least one elemente
such thato.equals(e)
.- Specified by:
contains
in interfaceCollection<E>
- Specified by:
contains
in interfaceDeque<E>
- Overrides:
contains
in classAbstractCollection<E>
- Parameters:
o
- object to be checked for containment in this deque- Returns:
true
if this deque contains the specified element
-
toArray
Returns an array containing all of the elements in this deque, in proper sequence (from first to last element).The returned array will be "safe" in that no references to it are maintained by this deque. (In other words, this method must allocate a new array). The caller is thus free to modify the returned array.
This method acts as bridge between array-based and collection-based APIs.
- Specified by:
toArray
in interfaceCollection<E>
- Overrides:
toArray
in classAbstractCollection<E>
- Returns:
- an array containing all of the elements in this deque
-
toArray
public <T> T[] toArray(T[] a) - Specified by:
toArray
in interfaceCollection<E>
- Overrides:
toArray
in classAbstractCollection<E>
-
toString
- Overrides:
toString
in classAbstractCollection<E>
-
clear
public void clear()Atomically removes all of the elements from this deque. The deque will be empty after this call returns.- Specified by:
clear
in interfaceCollection<E>
- Overrides:
clear
in classAbstractQueue<E>
-
iterator
Returns an iterator over the elements in this deque in proper sequence. The elements will be returned in order from first (head) to last (tail). The returnedIterator
is a "weakly consistent" iterator that will never throwConcurrentModificationException
, and guarantees to traverse elements as they existed upon construction of the iterator, and may (but is not guaranteed to) reflect any modifications subsequent to construction. -
descendingIterator
- Specified by:
descendingIterator
in interfaceDeque<E>
-
writeObject
Saves the state of this deque to a stream (that is, serialize it).- Parameters:
s
- the stream- Throws:
IOException
-
readObject
Reconstitutes this deque from a stream (that is, deserialize it).- Parameters:
s
- the stream- Throws:
IOException
ClassNotFoundException
-
hasTakeWaiters
public boolean hasTakeWaiters()Returns true if there are threads waiting to take instances from this deque. See disclaimer on accuracy inReentrantLock.hasWaiters(Condition)
.- Returns:
- true if there is at least one thread waiting on this deque's notEmpty condition.
-
getTakeQueueLength
public int getTakeQueueLength()Returns the length of the queue of threads waiting to take instances from this deque. See disclaimer on accuracy inReentrantLock.getWaitQueueLength(Condition)
.- Returns:
- number of threads waiting on this deque's notEmpty condition.
-
interuptTakeWaiters
public void interuptTakeWaiters()Interrupts the threads currently waiting to take an object from the pool. See disclaimer on accuracy inReentrantLock.getWaitingThreads(Condition)
.
-