Class SynchronousQueue<E>
java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractQueue<E>
java.util.concurrent.SynchronousQueue<E>
- Type Parameters:
E
- the type of elements held in this queue
- All Implemented Interfaces:
Serializable
,Iterable<E>
,Collection<E>
,BlockingQueue<E>
,Queue<E>
A blocking queue in which each insert
operation must wait for a corresponding remove operation by another
thread, and vice versa. A synchronous queue does not have any
internal capacity, not even a capacity of one. You cannot
peek
at a synchronous queue because an element is only
present when you try to remove it; you cannot insert an element
(using any method) unless another thread is trying to remove it;
you cannot iterate as there is nothing to iterate. The
head of the queue is the element that the first queued
inserting thread is trying to add to the queue; if there is no such
queued thread then no element is available for removal and
poll()
will return null
. For purposes of other
Collection
methods (for example contains
), a
SynchronousQueue
acts as an empty collection. This queue
does not permit null
elements.
Synchronous queues are similar to rendezvous channels used in CSP and Ada. They are well suited for handoff designs, in which an object running in one thread must sync up with an object running in another thread in order to hand it some information, event, or task.
This class supports an optional fairness policy for ordering
waiting producer and consumer threads. By default, this ordering
is not guaranteed. However, a queue constructed with fairness set
to true
grants threads access in FIFO order.
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:
- 1.5
- See Also:
-
Constructor Summary
ConstructorDescriptionCreates aSynchronousQueue
with nonfair access policy.SynchronousQueue
(boolean fair) Creates aSynchronousQueue
with the specified fairness policy. -
Method Summary
Modifier and TypeMethodDescriptionvoid
clear()
Does nothing.boolean
Always returnsfalse
.boolean
containsAll
(Collection<?> c) Returnsfalse
unless the given collection is empty.int
drainTo
(Collection<? super E> c) Removes all available elements from this queue and adds them to the given collection.int
drainTo
(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.boolean
isEmpty()
Always returnstrue
.iterator()
Returns an empty iterator in whichhasNext
always returnsfalse
.boolean
Inserts the specified element into this queue, if another thread is waiting to receive it.boolean
Inserts the specified element into this queue, waiting if necessary up to the specified wait time for another thread to receive it.peek()
Always returnsnull
.poll()
Retrieves and removes the head of this queue, if another thread is currently making an element available.Retrieves and removes the head of this queue, waiting if necessary up to the specified wait time, for another thread to insert it.void
Adds the specified element to this queue, waiting if necessary for another thread to receive it.int
Always returns zero.boolean
Always returnsfalse
.boolean
removeAll
(Collection<?> c) Always returnsfalse
.boolean
retainAll
(Collection<?> c) Always returnsfalse
.int
size()
Always returns zero.Returns an empty spliterator in which calls totrySplit
always returnnull
.take()
Retrieves and removes the head of this queue, waiting if necessary for another thread to insert it.Object[]
toArray()
Returns a zero-length array.<T> T[]
toArray
(T[] a) Sets the zeroth element of the specified array tonull
(if the array has non-zero length) and returns it.toString()
Always returns"[]"
.Methods declared in class java.util.AbstractQueue
add, addAll, element, remove
Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods declared in interface java.util.concurrent.BlockingQueue
add
Methods declared in interface java.util.Collection
addAll, equals, hashCode, parallelStream, removeIf, stream, toArray
-
Constructor Details
-
SynchronousQueue
public SynchronousQueue()Creates aSynchronousQueue
with nonfair access policy. -
SynchronousQueue
public SynchronousQueue(boolean fair) Creates aSynchronousQueue
with the specified fairness policy.- Parameters:
fair
- if true, waiting threads contend in FIFO order for access; otherwise the order is unspecified.
-
-
Method Details
-
put
Adds the specified element to this queue, waiting if necessary for another thread to receive it.- Specified by:
put
in interfaceBlockingQueue<E>
- Parameters:
e
- the element to add- Throws:
InterruptedException
- if interrupted while waitingNullPointerException
- if the specified element is null
-
offer
Inserts the specified element into this queue, waiting if necessary up to the specified wait time for another thread to receive it.- Specified by:
offer
in interfaceBlockingQueue<E>
- Parameters:
e
- the element to addtimeout
- how long to wait before giving up, in units ofunit
unit
- aTimeUnit
determining how to interpret thetimeout
parameter- Returns:
true
if successful, orfalse
if the specified waiting time elapses before a consumer appears- Throws:
InterruptedException
- if interrupted while waitingNullPointerException
- if the specified element is null
-
offer
Inserts the specified element into this queue, if another thread is waiting to receive it.- Specified by:
offer
in interfaceBlockingQueue<E>
- Specified by:
offer
in interfaceQueue<E>
- Parameters:
e
- the element to add- Returns:
true
if the element was added to this queue, elsefalse
- Throws:
NullPointerException
- if the specified element is null
-
take
Retrieves and removes the head of this queue, waiting if necessary for another thread to insert it.- Specified by:
take
in interfaceBlockingQueue<E>
- Returns:
- the head of this queue
- Throws:
InterruptedException
- if interrupted while waiting
-
poll
Retrieves and removes the head of this queue, waiting if necessary up to the specified wait time, for another thread to insert it.- Specified by:
poll
in interfaceBlockingQueue<E>
- Parameters:
timeout
- how long to wait before giving up, in units ofunit
unit
- aTimeUnit
determining how to interpret thetimeout
parameter- Returns:
- the head of this queue, or
null
if the specified waiting time elapses before an element is present - Throws:
InterruptedException
- if interrupted while waiting
-
poll
-
isEmpty
public boolean isEmpty()Always returnstrue
. ASynchronousQueue
has no internal capacity.- Specified by:
isEmpty
in interfaceCollection<E>
- Overrides:
isEmpty
in classAbstractCollection<E>
- Returns:
true
-
size
public int size()Always returns zero. ASynchronousQueue
has no internal capacity.- Specified by:
size
in interfaceCollection<E>
- Returns:
- zero
-
remainingCapacity
public int remainingCapacity()Always returns zero. ASynchronousQueue
has no internal capacity.- Specified by:
remainingCapacity
in interfaceBlockingQueue<E>
- Returns:
- zero
-
clear
public void clear()Does nothing. ASynchronousQueue
has no internal capacity.- Specified by:
clear
in interfaceCollection<E>
- Overrides:
clear
in classAbstractQueue<E>
-
contains
Always returnsfalse
. ASynchronousQueue
has no internal capacity.- Specified by:
contains
in interfaceBlockingQueue<E>
- Specified by:
contains
in interfaceCollection<E>
- Overrides:
contains
in classAbstractCollection<E>
- Parameters:
o
- the element- Returns:
false
-
remove
Always returnsfalse
. ASynchronousQueue
has no internal capacity.- Specified by:
remove
in interfaceBlockingQueue<E>
- Specified by:
remove
in interfaceCollection<E>
- Overrides:
remove
in classAbstractCollection<E>
- Parameters:
o
- the element to remove- Returns:
false
-
containsAll
Returnsfalse
unless the given collection is empty. ASynchronousQueue
has no internal capacity.- Specified by:
containsAll
in interfaceCollection<E>
- Overrides:
containsAll
in classAbstractCollection<E>
- Parameters:
c
- the collection- Returns:
false
unless given collection is empty- See Also:
-
removeAll
Always returnsfalse
. ASynchronousQueue
has no internal capacity.- Specified by:
removeAll
in interfaceCollection<E>
- Overrides:
removeAll
in classAbstractCollection<E>
- Parameters:
c
- the collection- Returns:
false
- See Also:
-
retainAll
Always returnsfalse
. ASynchronousQueue
has no internal capacity.- Specified by:
retainAll
in interfaceCollection<E>
- Overrides:
retainAll
in classAbstractCollection<E>
- Parameters:
c
- the collection- Returns:
false
- See Also:
-
peek
-
iterator
-
spliterator
Returns an empty spliterator in which calls totrySplit
always returnnull
.- Specified by:
spliterator
in interfaceCollection<E>
- Specified by:
spliterator
in interfaceIterable<E>
- Returns:
- an empty spliterator
- Since:
- 1.8
-
toArray
Returns a zero-length array.- Specified by:
toArray
in interfaceCollection<E>
- Overrides:
toArray
in classAbstractCollection<E>
- Returns:
- a zero-length array
-
toArray
public <T> T[] toArray(T[] a) Sets the zeroth element of the specified array tonull
(if the array has non-zero length) and returns it.- Specified by:
toArray
in interfaceCollection<E>
- Overrides:
toArray
in classAbstractCollection<E>
- Type Parameters:
T
- the component type of the array to contain the collection- Parameters:
a
- the array- Returns:
- the specified array
- Throws:
NullPointerException
- if the specified array is null
-
toString
Always returns"[]"
.- Overrides:
toString
in classAbstractCollection<E>
- Returns:
"[]"
-
drainTo
Description copied from interface:BlockingQueue
Removes all available elements from this queue and adds them to the given collection. This operation may be more efficient than repeatedly polling this queue. A failure encountered while attempting to add elements to collectionc
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 inIllegalArgumentException
. Further, the behavior of this operation is undefined if the specified collection is modified while the operation is in progress.- Specified by:
drainTo
in interfaceBlockingQueue<E>
- Parameters:
c
- the collection to transfer elements into- Returns:
- the number of elements transferred
- Throws:
UnsupportedOperationException
- if addition of elements is not supported by the specified collectionClassCastException
- if the class of an element of this queue prevents it from being added to the specified collectionNullPointerException
- if the specified collection is nullIllegalArgumentException
- 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
Description copied from interface:BlockingQueue
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 collectionc
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 inIllegalArgumentException
. Further, the behavior of this operation is undefined if the specified collection is modified while the operation is in progress.- Specified by:
drainTo
in interfaceBlockingQueue<E>
- Parameters:
c
- the collection to transfer elements intomaxElements
- the maximum number of elements to transfer- Returns:
- the number of elements transferred
- Throws:
UnsupportedOperationException
- if addition of elements is not supported by the specified collectionClassCastException
- if the class of an element of this queue prevents it from being added to the specified collectionNullPointerException
- if the specified collection is nullIllegalArgumentException
- 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
-