edu.emory.mathcs.backport.java.util.concurrent
Class SynchronousQueue
java.util.AbstractCollection
- BlockingQueue, Collection, Queue, java.io.Serializable
public class SynchronousQueue
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. Fairness
generally decreases throughput but reduces variability and avoids
starvation.
This class and its iterator implement all of the
optional methods of the
Collection
and
Iterator
interfaces.
This class is a member of the
../../../../../../../../guide/collections/index.html">
Java Collections Framework.
SynchronousQueue() - Creates a SynchronousQueue with nonfair access policy.
|
SynchronousQueue(boolean fair) - Creates a SynchronousQueue with specified fairness policy.
|
void | clear() - Does nothing.
|
boolean | contains(Object o) - Always returns false.
|
boolean | containsAll(Collection c) - Returns false unless the given collection is empty.
|
int | drainTo(Collection c)
|
int | drainTo(Collection c, int maxElements)
|
boolean | isEmpty() - Always returns true.
|
Iterator | iterator() - Returns an empty iterator in which hasNext always returns
false.
|
boolean | offer(Object e) - Inserts the specified element into this queue, if another thread is
waiting to receive it.
|
boolean | offer(Object e, 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.
|
Object | peek() - Always returns null.
|
Object | poll() - Retrieves and removes the head of this queue, if another thread
is currently making an element available.
|
Object | 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.
|
void | put(Object e) - Adds the specified element to this queue, waiting if necessary for
another thread to receive it.
|
int | remainingCapacity() - Always returns zero.
|
boolean | remove(Object o) - Always returns false.
|
boolean | removeAll(Collection c) - Always returns false.
|
boolean | retainAll(Collection c) - Always returns false.
|
int | size() - Always returns zero.
|
Object | 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.
|
Object[] | toArray(Object[] a) - Sets the zeroeth element of the specified array to null
(if the array has non-zero length) and returns it.
|
SynchronousQueue
public SynchronousQueue()
Creates a SynchronousQueue with nonfair access policy.
SynchronousQueue
public SynchronousQueue(boolean fair)
Creates a SynchronousQueue with specified fairness policy.
fair
- if true, threads contend in FIFO order for access;
otherwise the order is unspecified.
clear
public void clear()
Does nothing.
A SynchronousQueue has no internal capacity.
- clear in interface AbstractQueue
contains
public boolean contains(Object o)
Always returns false.
A SynchronousQueue has no internal capacity.
- contains in interface BlockingQueue
o
- object to be checked for containment in this queue
containsAll
public boolean containsAll(Collection c)
Returns false unless the given collection is empty.
A SynchronousQueue has no internal capacity.
- false unless the given collection is empty
isEmpty
public boolean isEmpty()
Always returns true.
A SynchronousQueue has no internal capacity.
iterator
public Iterator iterator()
Returns an empty iterator in which hasNext always returns
false.
offer
public boolean offer(Object e)
Inserts the specified element into this queue, if another thread is
waiting to receive it.
- offer in interface BlockingQueue
- offer in interface Queue
- true if the element was added to this queue, else
false
offer
public boolean offer(Object e,
long timeout,
TimeUnit unit)
throws InterruptedException
Inserts the specified element into this queue, waiting if necessary
up to the specified wait time for another thread to receive it.
- offer in interface BlockingQueue
- true if successful, or false if the
specified waiting time elapses before a consumer appears.
peek
public Object peek()
Always returns null.
A SynchronousQueue does not return elements
unless actively waited on.
- peek in interface Queue
poll
public Object poll()
Retrieves and removes the head of this queue, if another thread
is currently making an element available.
- poll in interface Queue
- the head of this queue, or null if no
element is available.
poll
public Object poll(long timeout,
TimeUnit unit)
throws InterruptedException
Retrieves and removes the head of this queue, waiting
if necessary up to the specified wait time, for another thread
to insert it.
- poll in interface BlockingQueue
- the head of this queue, or null if the
specified waiting time elapses before an element is present.
put
public void put(Object e)
throws InterruptedException
Adds the specified element to this queue, waiting if necessary for
another thread to receive it.
- put in interface BlockingQueue
remainingCapacity
public int remainingCapacity()
Always returns zero.
A SynchronousQueue has no internal capacity.
- remainingCapacity in interface BlockingQueue
remove
public boolean remove(Object o)
Always returns false.
A SynchronousQueue has no internal capacity.
- remove in interface BlockingQueue
o
- the element to remove
removeAll
public boolean removeAll(Collection c)
Always returns false.
A SynchronousQueue has no internal capacity.
retainAll
public boolean retainAll(Collection c)
Always returns false.
A SynchronousQueue has no internal capacity.
size
public int size()
Always returns zero.
A SynchronousQueue has no internal capacity.
take
public Object take()
throws InterruptedException
Retrieves and removes the head of this queue, waiting if necessary
for another thread to insert it.
- take in interface BlockingQueue
toArray
public Object[] toArray(Object[] a)
Sets the zeroeth element of the specified array to null
(if the array has non-zero length) and returns it.
- toArray in interface AbstractCollection