Module java.base
Package java.util.concurrent

Class SynchronousQueue<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractQueue<E>
java.util.concurrent.SynchronousQueue<E>
类型参数:
E - 此队列中保存的元素的类型
所有已实现的接口:
Serializable, Iterable<E>, Collection<E>, BlockingQueue<E>, Queue<E>
public class SynchronousQueue<E> extends AbstractQueue<E> implements BlockingQueue<E>, Serializable
一个阻塞队列，在这个队列中，每个插入操作都必须等待另一个线程的相应删除操作，反之亦然。同步队列没有任何内部容量，甚至没有一个容量。您不能在同步队列上执行peek操作，因为只有在尝试删除元素时才存在元素；除非另一个线程正在尝试删除元素，否则您无法插入元素（使用任何方法）；由于没有要迭代的内容，您无法进行迭代。队列的头部是第一个排队插入线程正在尝试添加到队列的元素；如果没有这样的排队线程，则没有元素可用于删除，poll()将返回null。对于其他Collection方法（例如contains），SynchronousQueue充当空集合。此队列不允许包含null元素。

同步队列类似于CSP和Ada中使用的会合通道。它们非常适合于交接设计，其中在一个线程中运行的对象必须与在另一个线程中运行的对象同步，以便将一些信息、事件或任务交给它。

此类支持可选的公平策略，用于对等待的生产者和消费者线程进行排序。默认情况下，此排序不被保证。但是，使用公平性设置为true构造的队列按照FIFO顺序授予线程访问权限。

此类及其迭代器实现了Collection和Iterator接口的所有可选方法。

此类是Java集合框架的成员。

自 JDK 版本:
1.5
参见:

  • Constructor Summary

    Constructors
    Constructor
    Description
    SynchronousQueue()
    创建一个具有非公平访问策略的SynchronousQueue。
    SynchronousQueue(boolean fair)
    创建一个具有指定公平性策略的SynchronousQueue。

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    什么也不做。
    boolean
    contains(Object o)
    总是返回false。
    boolean
    containsAll(Collection<?> c)
    除非给定的集合为空，否则返回false。
    int
    drainTo(Collection<? super E> c)
    从此队列中删除所有可用元素并将它们添加到给定的集合中。
    int
    drainTo(Collection<? super E> c, int maxElements)
    从此队列中最多删除给定数量的可用元素，并将它们添加到给定的集合中。
    boolean
    isEmpty()
    总是返回true。
    Iterator<E>
    iterator()
    返回一个空迭代器，其中hasNext始终返回false。
    boolean
    offer(E e)
    如果另一个线程正在等待接收指定的元素，则将指定的元素插入此队列。
    boolean
    offer(E e, long timeout, TimeUnit unit)
    如果需要，将指定的元素插入此队列，并等待指定的等待时间，直到另一个线程接收它。
    E
    peek()
    总是返回null。
    E
    poll()
    如果当前有另一个线程正在使元素可用，则检索并删除此队列的头部。
    E
    poll(long timeout, TimeUnit unit)
    如果需要，等待另一个线程将其插入，以检索并删除此队列的头部。
    void
    put(E e)
    将指定的元素添加到此队列中，如果需要，等待另一个线程接收它。
    int
    remainingCapacity()
    总是返回零。
    boolean
    remove(Object o)
    总是返回false。
    boolean
    removeAll(Collection<?> c)
    总是返回false。
    boolean
    retainAll(Collection<?> c)
    总是返回false。
    int
    size()
    总是返回零。
    Spliterator<E>
    spliterator()
    返回一个空的分割迭代器，其中对trySplit的调用始终返回null。
    E
    take()
    如果需要，等待另一个线程将其插入，以检索并删除此队列的头部。
    Object[]
    toArray()
    返回一个长度为零的数组。
    <T> T[]
    toArray(T[] a)
    将指定数组的第零个元素设置为null（如果数组的长度非零），并返回该数组。
    String
    toString()
    总是返回"[]"。

    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

    Methods declared in interface java.lang.Iterable

    forEach

    Methods declared in interface java.util.Queue

    element, remove

  • Constructor Details

    • SynchronousQueue

      public SynchronousQueue()
      创建一个具有非公平访问策略的SynchronousQueue。

    • SynchronousQueue

      public SynchronousQueue(boolean fair)
      创建一个具有指定公平性策略的SynchronousQueue。
      参数:
      fair - 如果为true，则等待线程按FIFO顺序竞争访问；否则顺序是未指定的。

  • Method Details

    • put

      public void put(E e) throws InterruptedException
      如果需要，等待另一个线程将其插入，以将指定的元素添加到此队列。
      指定者:
      put 在接口 BlockingQueue<E>中
      参数:
      e - 要添加的元素
      抛出:
      InterruptedException - 如果在等待时被中断
      NullPointerException - 如果指定的元素为null

    • offer

      public boolean offer(E e, long timeout, TimeUnit unit) throws InterruptedException
      如果需要，等待另一个线程将其插入，以将指定的元素添加到此队列，并等待指定的等待时间。
      指定者:
      offer 在接口 BlockingQueue<E>中
      参数:
      e - 要添加的元素
      timeout - 在unit单位内等待多长时间后放弃
      unit - 一个TimeUnit，用于解释timeout参数
      返回:
      如果成功，则返回true，如果指定的等待时间在消费者出现之前过去，则返回false
      抛出:
      InterruptedException - 如果在等待时被中断
      NullPointerException - 如果指定的元素为null

    • offer

      public boolean offer(E e)
      如果另一个线程正在等待接收指定的元素，则将指定的元素插入此队列。
      指定者:
      offer 在接口 BlockingQueue<E>中
      指定者:
      offer 在接口 Queue<E>中
      参数:
      e - 要添加的元素
      返回:
      如果元素已添加到此队列，则返回true，否则返回false
      抛出:
      NullPointerException - 如果指定的元素为null

    • take

      public E take() throws InterruptedException
      如果需要，等待另一个线程将其插入，以检索并删除此队列的头部。
      指定者:
      take 在接口 BlockingQueue<E>中
      返回:
      此队列的头部
      抛出:
      InterruptedException - 如果在等待时被中断

    • poll

      public E poll(long timeout, TimeUnit unit) throws InterruptedException
      如果需要，等待另一个线程将其插入，以检索并删除此队列的头部。
      指定者:
      poll 在接口 BlockingQueue<E>中
      参数:
      timeout - 在unit单位内等待多长时间后放弃
      unit - 一个TimeUnit，用于解释timeout参数
      返回:
      此队列的头部，如果指定的等待时间在元素出现之前过去，则返回null
      抛出:
      InterruptedException - 如果在等待时被中断

    • poll

      public E poll()
      如果另一个线程当前正在使元素可用，则检索并删除此队列的头部。
      指定者:
      poll 在接口 Queue<E>中
      返回:
      此队列的头部，如果没有元素可用，则返回null

    • isEmpty

      public boolean isEmpty()
      总是返回true。 SynchronousQueue没有内部容量。
      指定由:
      isEmpty 在接口 Collection<E>
      覆盖:
      isEmpty 在类 AbstractCollection<E>
      返回:
      true

    • size

      public int size()
      总是返回零。 SynchronousQueue 没有内部容量。
      指定由:
      size 在接口 Collection<E>
      返回:
      零

    • remainingCapacity

      public int remainingCapacity()
      总是返回零。 SynchronousQueue 没有内部容量。
      指定由:
      remainingCapacity 在接口 BlockingQueue<E>
      返回:
      零

    • clear

      public void clear()
      什么也不做。 SynchronousQueue 没有内部容量。
      指定由:
      clear 在接口 Collection<E>
      覆盖:
      clear 在类 AbstractQueue<E>

    • contains

      public boolean contains(Object o)
      总是返回 false。 SynchronousQueue 没有内部容量。
      指定由:
      contains 在接口 BlockingQueue<E>
      指定由:
      contains 在接口 Collection<E>
      覆盖:
      contains 在类 AbstractCollection<E>
      参数:
      o - 元素
      返回:
      false

    • remove

      public boolean remove(Object o)
      总是返回 false。 SynchronousQueue 没有内部容量。
      指定由:
      remove 在接口 BlockingQueue<E>
      指定由:
      remove 在接口 Collection<E>
      覆盖:
      remove 在类 AbstractCollection<E>
      参数:
      o - 要移除的元素
      返回:
      false

    • containsAll

      public boolean containsAll(Collection<?> c)
      返回 false，除非给定的集合为空。 SynchronousQueue 没有内部容量。
      指定由:
      containsAll 在接口 Collection<E>
      覆盖:
      containsAll 在类 AbstractCollection<E>
      参数:
      c - 集合
      返回:
      false，除非给定的集合为空
      参见:

    • removeAll

      public boolean removeAll(Collection<?> c)
      总是返回 false。 SynchronousQueue 没有内部容量。
      指定由:
      removeAll 在接口 Collection<E>
      覆盖:
      removeAll 在类 AbstractCollection<E>
      参数:
      c - 集合
      返回:
      false
      参见:

    • retainAll

      public boolean retainAll(Collection<?> c)
      总是返回 false。 SynchronousQueue 没有内部容量。
      指定由:
      retainAll 在接口 Collection<E>
      覆盖:
      retainAll 在类 AbstractCollection<E>
      参数:
      c - 集合
      返回:
      false
      参见:

    • peek

      public E peek()
      总是返回 null。 SynchronousQueue 除非主动等待，否则不会返回元素。
      指定由:
      peek 在接口 Queue<E>
      返回:
      null

    • iterator

      public Iterator<E> iterator()
      返回一个空的迭代器，其中 hasNext 总是返回 false。
      指定由:
      iterator 在接口 Collection<E>
      指定由:
      iterator 在接口 Iterable<E>
      指定由:
      iterator 在类 AbstractCollection<E>
      返回:
      一个空的迭代器

    • spliterator

      public Spliterator<E> spliterator()
      返回一个空的分割迭代器，其中调用 trySplit 总是返回 null。
      指定由:
      spliterator 在接口 Collection<E>
      指定由:
      spliterator 在接口 Iterable<E>
      返回:
      一个空的分割迭代器
      自1.8起:
      1.8

    • toArray

      public Object[] toArray()
      返回一个长度为零的数组。
      指定由:
      toArray 在接口 Collection<E>中
      覆盖:
      toArray 在类 AbstractCollection<E>中
      返回:
      长度为零的数组

    • toArray

      public <T> T[] toArray(T[] a)
      将指定数组的第零个元素设置为null（如果数组长度非零），然后返回它。
      指定由:
      toArray 在接口 Collection<E>中
      覆盖:
      toArray 在类 AbstractCollection<E>中
      类型参数:
      T - 包含集合的数组的组件类型
      参数:
      a - 数组
      返回:
      指定的数组
      抛出:
      NullPointerException - 如果指定的数组为null

    • toString

      public String toString()
      总是返回"[]"。
      覆盖:
      toString 在类 AbstractCollection<E>中
      返回:
      "[]"

    • drainTo

      public int drainTo(Collection<? super E> c)
      从接口复制的描述: BlockingQueue
      从此队列中移除所有可用元素并将它们添加到给定的集合中。此操作可能比重复轮询此队列更有效。在尝试将元素添加到集合c时遇到失败可能导致在抛出相关异常时元素既不在集合中，也不在队列中，或同时存在于两者中。尝试将队列排空到自身会导致IllegalArgumentException。此外，如果在操作进行中修改了指定的集合，则此操作的行为是未定义的。
      指定由:
      drainTo 在接口 BlockingQueue<E>中
      参数:
      c - 转移元素到的集合
      返回:
      转移的元素数量
      抛出:
      UnsupportedOperationException - 如果指定集合不支持添加元素
      ClassCastException - 如果此队列的元素类别阻止将其添加到指定集合中
      NullPointerException - 如果指定的集合为null
      IllegalArgumentException - 如果指定的集合为此队列，或者此队列的某个元素属性阻止将其添加到指定集合中

    • drainTo

      public int drainTo(Collection<? super E> c, int maxElements)
      从接口复制的描述: BlockingQueue
      从此队列中最多移除给定数量的可用元素，并将它们添加到给定的集合中。在尝试将元素添加到集合c时遇到失败可能导致在抛出相关异常时元素既不在集合中，也不在队列中，或同时存在于两者中。尝试将队列排空到自身会导致IllegalArgumentException。此外，如果在操作进行中修改了指定的集合，则此操作的行为是未定义的。
      指定由:
      drainTo 在接口 BlockingQueue<E>中
      参数:
      c - 转移元素到的集合
      maxElements - 要转移的最大元素数量
      返回:
      转移的元素数量
      抛出:
      UnsupportedOperationException - 如果指定集合不支持添加元素
      ClassCastException - 如果此队列的元素类别阻止将其添加到指定集合中
      NullPointerException - 如果指定的集合为null
      IllegalArgumentException - 如果指定的集合为此队列，或者此队列的某个元素属性阻止将其添加到指定集合中