Save This Page
Home » openjdk-7 » java » util » concurrent » [javadoc | source]
java.util.concurrent
public class: SynchronousQueue [javadoc | source]
java.lang.Object
   java.util.AbstractCollection
      java.util.AbstractQueue
         java.util.concurrent.SynchronousQueue

All Implemented Interfaces:
    BlockingQueue, Serializable, Queue, Collection

A {@linkplain BlockingQueue 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.

Nested Class Summary:
abstract static class  SynchronousQueue.Transferer  Shared internal API for dual stacks and queues. 
static final class  SynchronousQueue.TransferStack  Dual stack 
static final class  SynchronousQueue.TransferQueue  Dual Queue 
static class  SynchronousQueue.WaitQueue   
static class  SynchronousQueue.LifoWaitQueue   
static class  SynchronousQueue.FifoWaitQueue   
Field Summary
static final  int NCPUS    The number of CPUs, for spin control 
static final  int maxTimedSpins    The number of times to spin before blocking in timed waits. The value is empirically derived -- it works well across a variety of processors and OSes. Empirically, the best value seems not to vary with number of CPUs (beyond 2) so is just a constant. 
static final  int maxUntimedSpins    The number of times to spin before blocking in untimed waits. This is greater than timed value because untimed waits spin faster since they don't need to check times on each spin. 
static final  long spinForTimeoutThreshold    The number of nanoseconds for which it is faster to spin rather than to use timed park. A rough estimate suffices. 
Constructor:
 public SynchronousQueue() 
 public SynchronousQueue(boolean fair) 
Method from java.util.concurrent.SynchronousQueue Summary:
clear,   contains,   containsAll,   drainTo,   drainTo,   isEmpty,   iterator,   offer,   offer,   peek,   poll,   poll,   put,   remainingCapacity,   remove,   removeAll,   retainAll,   size,   take,   toArray,   toArray
Methods from java.util.AbstractQueue:
add,   addAll,   clear,   element,   remove
Methods from java.util.AbstractCollection:
add,   addAll,   clear,   contains,   containsAll,   isEmpty,   iterator,   remove,   removeAll,   retainAll,   size,   toArray,   toArray,   toString
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from java.util.concurrent.SynchronousQueue Detail:
 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 the given collection is empty. A SynchronousQueue has no internal capacity.
 public int drainTo(Collection c) 
 public int drainTo(Collection c,
    int maxElements) 
 public boolean isEmpty() 
    Always returns true. A SynchronousQueue has no internal capacity.
 public Iterator iterator() 
    Returns an empty iterator in which hasNext always returns false.
 public boolean offer(E e) 
    Inserts the specified element into this queue, if another thread is waiting to receive it.
 public boolean offer(E o,
    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.
 public E peek() 
    Always returns null. A SynchronousQueue does not return elements unless actively waited on.
 public E poll() 
    Retrieves and removes the head of this queue, if another thread is currently making an element available.
 public E 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.
 public  void put(E o) throws InterruptedException 
    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() throws InterruptedException 
    Retrieves and removes the head of this queue, waiting if necessary for another thread to insert it.
 public Object[] toArray() 
    Returns a zero-length array.
 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.