java.util.concurrent.SynchronousQueue<E>
A blocking queue in which each
put must wait for a take, 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 take it; you
cannot add 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 thread is trying to add to the queue; if there are no
queued threads then no element is being added and the head is
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. Fairness
generally decreases throughput but reduces variability and avoids
starvation.
This class implements all of the optional methods
of the Collection and Iterator interfaces.
Summary
Public Constructors
Public Methods
add,
addAll,
clear,
contains,
containsAll,
isEmpty,
iterator,
remove,
removeAll,
retainAll,
size,
toArray,
toArray,
toString
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
add,
addAll,
clear,
contains,
containsAll,
equals,
hashCode,
isEmpty,
iterator,
remove,
removeAll,
retainAll,
size,
toArray,
toArray
Methods inherited
from interface
java.util.Queue
Details
Public Constructors
public
SynchronousQueue()
Creates a SynchronousQueue with nonfair access policy.
public
SynchronousQueue(boolean fair)
Creates a
SynchronousQueue with specified fairness policy.
Parameters
fair
| if true, threads contend in FIFO order for access;
otherwise the order is unspecified.
|
Public Methods
public
void
clear()
Does nothing.
A SynchronousQueue has no internal capacity.
public
boolean
contains(Object o)
Always returns
false.
A
SynchronousQueue has no internal capacity.
public
boolean
containsAll(Collection<?> c)
Returns
false unless given collection is empty.
A
SynchronousQueue has no internal capacity.
Returns
- false unless given collection is empty
public
int
drainTo(Collection<? super E> c, int maxElements)
Removes at most the given number of available elements from
this queue and adds them into 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.
public
int
drainTo(Collection<? super E> c)
Removes all available elements from this queue and adds them
into the given collection. This operation may be more
efficient than repeatedly polling this queue. 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.
public
boolean
isEmpty()
Always returns
true.
A
SynchronousQueue has no internal capacity.
public
Iterator<E>
iterator()
Returns an empty iterator in which
hasNext always returns
false.
public
boolean
offer(E o, long timeout, TimeUnit unit)
Inserts the specified element into this queue, waiting if necessary
up to the specified wait time for another thread to receive it.
Parameters
o
| 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 a consumer appears.
public
boolean
offer(E o)
Inserts the specified element into this queue, if another thread is
waiting to receive it.
Returns
- true if it was possible to add the element to
this queue, else false
public
E
peek()
Always returns
null.
A
SynchronousQueue does not return elements
unless actively waited on.
public
E
poll(long timeout, TimeUnit unit)
Retrieves and removes the head of this queue, waiting
if necessary up to the specified wait time, for another thread
to insert it.
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 present.
public
E
poll()
Retrieves and removes the head of this queue, if another thread
is currently making an element available.
Returns
- the head of this queue, or null if no
element is available.
public
void
put(E o)
Adds the specified element to this queue, waiting if necessary for
another thread to receive it.
public
int
remainingCapacity()
Always returns zero.
A
SynchronousQueue has no internal capacity.
public
boolean
remove(Object o)
Always returns
false.
A
SynchronousQueue has no internal capacity.
public
boolean
removeAll(Collection<?> c)
Always returns
false.
A
SynchronousQueue has no internal capacity.
public
boolean
retainAll(Collection<?> c)
Always returns
false.
A
SynchronousQueue has no internal capacity.
public
int
size()
Always returns zero.
A
SynchronousQueue has no internal capacity.
public
E
take()
Retrieves and removes the head of this queue, waiting if necessary
for another thread to insert it.
public
T[]
toArray(T[] a)
Sets the zeroeth element of the specified array to
null
(if the array has non-zero length) and returns it.
public
Object[]
toArray()
Returns a zero-length array.