Java ~ Collection/Executor ~ TransferQueue【源码】

前言

---

    文中的源码注释/结论是我个人学习过程中的理解/看法，多有漏误，后期的新看法/总结也不会再于本文中修正/添加，因此本文内容只可作为参考/提示使用，最新看法/总结以总结篇为准，链接在本文底部。

一 TransferQueue（迁移队列）接口源码及机制详解

---

 接口

    TransferQueue（迁移队列）接口（下文简称迁移队列）是BlockingQueue（阻塞队列）接口的两大子接口之一，在原本的操作定义上新增了迁移操作的定义。所谓的迁移是一种作用于操作本身（或者说作用于执行操作的线程）的操作，与插入/放置操作非常类似，但阻塞条件不是没有剩余容量，而是迁移队列中没有阻塞的拿取者（执行移除/拿取操作的线程）。当一个迁移者（执行迁移操作的线程）执行迁移操作时，如果迁移队列中存在阻塞的拿取者，则将自身携带的元素迁移至拿取者令其完成移除/拿取操作（与此同时也意味着迁移操作的完成）；否则将定时/永久阻塞至有拿取者可供元素迁移或直接返回false（迁移操作也存在多种形式的定义）。

    迁移队列的实现类不允许存null值，或者说BlockingQueue（阻塞队列）接口的所有的实现类都不允许存null值。null被poll()及peek()方法（两个方法由Queue（队列）接口定义）作为队列不存在元素的标记值，因此所有的BlockingQueue（阻塞队列）接口实现类都不允许存null值。

    迁移队列是线程安全的，或者说BlockingQueue（阻塞队列）接口的所有的实现类都是线程安全的（接口的定义中强制要求实现类必须线程安全）。

    迁移队列虽然与BlockingQueue（阻塞队列）接口一样都被纳入Executor（执行器）框架的范畴，但同时是Collection（集）框架的成员。

/**
 * A {@link BlockingQueue} in which producers may wait for consumers to receive elements.  A {@code TransferQueue} may be useful for
 * example in message passing applications in which producers sometimes (using method {@link #transfer}) await receipt of elements by
 * consumers invoking {@code take} or {@code poll}, while at other times enqueue elements (via method {@code put}) without waiting for
 * receipt. {@linkplain #tryTransfer(Object) Non-blocking} and {@linkplain #tryTransfer(Object, long, TimeUnit) time-out} versions of
 * {@code tryTransfer} are also available. A {@code TransferQueue} may also be queried, via {@link #hasWaitingConsumer}, whether there
 * are any threads waiting for items, which is a converse analogy to a {@code peek} operation.
 * 一个生产者可能等待消费者接收元素的阻塞队列。迁移队列可能很有用，例如在消息传递引用程序（比如消息队列）中生产者有时（使
 * 用transfer()方法）通过消费者调用take()方法或poll()方法等待元素的接收，在其它时间入队元素（通过put()方法）不等待接收（就
 * 是说通过transfer()方法入队的元素会一直等待到有拿取者将之移除/拿取为止，即使队列有容量也是一样。而通过put()方法入队的元
 * 素无需等待拿取者将之移除/拿取，只等待空余内存）。tryTransfer()方法的tryTransfer(Object o)方法和
 * tryTransfer(E e, long timeout, TimeUnit unit)方法版本同样有效。迁移队列也可查询，通过hasWaitingConsumer()方法，是否有任何
 * 线程等待项，其是一个peek()方法的相反类比。
 * <p>
 * Like other blocking queues, a {@code TransferQueue} may be capacity bounded.  If so, an attempted transfer operation may initially
 * block waiting for available space, and/or subsequently block waiting for reception by a consumer.  Note that in a queue with zero capacity,
 * such as {@link SynchronousQueue}, {@code put} and {@code transfer} are effectively synonymous.
 * 像其它阻塞队列，一个迁移队列可能容量有限。如果这样，一个未遂的迁移操作最初可能阻塞等待可用空间，并且/或随后通过消费者阻
 * 塞等待接待处。注意在容量为0的队列中，比如同步队列，put()方法和transfer()方法实际上是同义的（即两者的作用相同，在同步队列
 * 中，put()方法是通过transfer()方法实现的）。
 * <p>
 * This interface is a member of the <a href="{@docRoot}/../technotes/guides/collections/index.html"> Java Collections Framework</a>.
 * 该接口是Java集框架的成员。
 *
 * @param <E> the type of elements held in this collection 在集中约束的元素类型
 * @author Doug Lea
 * @Description: 迁移队列接口
 * @since 1.7
 */
public interface TransferQueue<E> extends BlockingQueue<E> {
    
    ...
    
}

 方法

    boolean tryTransfer(E e) —— 尝试迁移 —— 将元素迁移至等待中的拿取者。该方法是迁移操作"特殊值"形式的实现，如果迁移队列中已存在等待中的拿取者则将元素迁移并返回true；否则直接舍弃元素并返回false。

/**
 * Transfers the element to a waiting consumer immediately, if possible.
 * 如果可能，立即迁移元素至一个等待中的消费者。
 * <p>
 * More precisely, transfers the specified element immediately if there exists a consumer already waiting to receive it (in {@link #take} or
 * timed {@link #poll(long, TimeUnit) poll}), otherwise returning {@code false} without enqueuing the element.
 * 更精确地，如果已经存在一个消费者等待接收它（元素）（在take()方法中或定时poll()方法中）则立即传递指定元素，否则返回false
 * 不入队元素（如果已经有拿取者等待拿取则将元素传递过去，否则直接返回false，并且元素不会入队）。
 *
 * @param e the element to transfer 迁移的元素
 * @return {@code true} if the element was transferred, else {@code false} 如果元素已迁移则返回true；否则返回false。
 * @throws ClassCastException       if the class of the specified element prevents it from being added to this queue
 *                                  类转换异常：如果指定元素的类阻止它新增至队列
 * @throws NullPointerException     if the specified element is null
 *                                  空指针异常：如果指定元素为null
 * @throws IllegalArgumentException if some property of the specified element prevents it from being added to this queue
 *                                  非法参数异常：如果指定元素的特性阻止它新增至队列
 * @Description: 尝试迁移：将元素迁移至等待中的拿取者。该方法是迁移操作"特殊值"形式的实现，如果迁移队列中已存在等待中的拿取
 * @Description: 者则将元素迁移并返回true；否则直接舍弃元素并返回false。
 */
boolean tryTransfer(E e);

    void transfer(E e) —— 迁移 —— 将元素迁移至等待中的拿取者。该方法是迁移操作"阻塞"形式的实现，如果迁移队列中已存在等待中的拿取者则将元素迁移并返回true；否则等待至有拿取者可供迁移。

/**
 * Transfers the element to a consumer, waiting if necessary to do so.
 * 迁移元素至消费者，如果必要（迁移队列中不存在等待中的拿取者）则等待这样做。
 * <p>
 * More precisely, transfers the specified element immediately if there exists a consumer already waiting to receive it (in {@link #take} or
 * timed {@link #poll(long, TimeUnit) poll}), else waits until the element is received by a consumer.
 * 更精确地，如果已经存在一个消费者等待接收它（元素）（在take()方法中或定时poll()方法中）则立即传递指定元素，否则等待直到
 * 元素被一个消费者接收。
 *
 * @param e the element to transfer 迁移的元素
 * @throws InterruptedException     if interrupted while waiting, in which case the element is not left enqueued
 *                                  中断异常：如果在等待期间中断，在这种情况下元素不会左入队。
 * @throws ClassCastException       if the class of the specified element prevents it from being added to this queue
 *                                  类转换异常：如果指定元素的类阻止它新增至队列
 * @throws NullPointerException     if the specified element is null
 *                                  空指针异常：如果指定元素为null
 * @throws IllegalArgumentException if some property of the specified element prevents it from being added to this queue
 *                                  非法参数异常：如果指定元素的特性阻止它新增至队列
 * @Description: 迁移：将元素迁移至等待中的拿取者。该方法是迁移操作"阻塞"形式的实现，如果迁移队列中已存在等待中的拿取者则将
 * @Description: 元素迁移并返回true；否则等待至有拿取者可供迁移。
 */
void transfer(E e) throws InterruptedException;

    boolean tryTransfer(E e, long timeout, TimeUnit unit) —— 尝试迁移 —— 将元素迁移至等待中的拿取者。该方法是迁移操作"超时"形式的实现，如果迁移队列中已存在等待中的拿取者则将元素迁移并返回true；否则等待指定时间至有拿取者可供迁移，超出指定时间直接舍弃元素并返回false。

/**
 * Transfers the element to a consumer if it is possible to do so before the timeout elapses.
 * 如果可能在超时消逝之前将元素迁移至缴费者。
 * <p>
 * More precisely, transfers the specified element immediately if there exists a consumer already waiting to receive it (in {@link #take} or
 * timed {@link #poll(long, TimeUnit) poll}), else waits until the element is received by a consumer, returning {@code false} if the specified
 * wait time elapses before the element can be transferred.
 * 更精确地，如果已经存在一个消费者等待接收它（元素）（在take()方法中或定时poll()方法中）则立即传递指定元素，否则等待直到
 * 元素被一个消费者接收，如果指定等待时间在元素被迁移之前消逝则返回false。
 *
 * @param e       the element to transfer 迁移的元素
 * @param timeout how long to wait before giving up, in units of {@code unit}在放弃之前等待多久，单位根据unit
 * @param unit    a {@code TimeUnit} determining how to interpret the {@code timeout} parameter 时间单位确定如何解释超时参数
 * @return {@code true} if successful, or {@code false} if the specified waiting time elapses before completion, in which case the element
 * is not left enqueued 如果成功返回true，如果完成前指定等待时间消逝则返回false，在这种情况下元素不会左入队。
 * @throws InterruptedException     if interrupted while waiting, in which case the element is not left enqueued
 *                                  中断异常：如果在等待期间中断，在这种情况下元素不会左入队。
 * @throws ClassCastException       if the class of the specified element prevents it from being added to this queue
 *                                  类转换异常：如果指定元素的类阻止它新增至队列
 * @throws NullPointerException     if the specified element is null
 *                                  空指针异常：如果指定元素为null
 * @throws IllegalArgumentException if some property of the specified element prevents it from being added to this queue
 *                                  非法参数异常：如果指定元素的特性阻止它新增至队列
 * @Description: 尝试迁移：将元素迁移至等待中的拿取者。该方法是迁移操作"超时"形式的实现，如果迁移队列中已存在等待中的拿取
 * @Description: 者则将元素迁移并返回true；否则等待指定时间至有拿取者可供迁移，超出指定时间直接舍弃元素并返回false。
 */
boolean tryTransfer(E e, long timeout, TimeUnit unit) throws InterruptedException;

    boolean hasWaitingConsumer() —— 有等待中的消费者 —— 判断迁移队列中是否存在等待中的消费者，有则返回true；否则返回false。

/**
 * Returns {@code true} if there is at least one consumer waiting to receive an element via {@link #take} or timed {@link #poll(long, TimeUnit)
 * poll}. The return value represents a momentary state of affairs.
 * 如果有最少一个消费者通过take()方法或定时poll()方法等待接收一个元素则返回true。返回值代表一个事务的短暂状态（多线程的环境
 * 下，快照是不可靠的）。
 *
 * @return {@code true} if there is at least one waiting consumer 如果最少有一个等待中的消费者些返回true。
 * @Description: 有等待中的消费者：判断迁移队列中是否存在等待中的消费者，有则返回true；否则返回false。
 */
boolean hasWaitingConsumer();

    int getWaitingConsumerCount() —— 获取等待中的消费者总数 —— 获取迁移队列中等待中的消费者总数。</font>

/**
 * Returns an estimate of the number of consumers waiting to receive elements via {@link #take} or timed {@link #poll(long, TimeUnit) poll}.
 * The return value is an approximation of a momentary state of affairs, that may be inaccurate if consumers have completed or given up
 * waiting. The value may be useful for monitoring and heuristics, but not for synchronization control.  Implementations of this method are
 * likely to be noticeably slower than those for {@link #hasWaitingConsumer}.
 * 返回通过通过take()方法或定时poll()方法等待接收元素的消费者的数量的估计值。该返回值是一个事务的短暂状态的粗略值，如果消费
 * 者已完成或者放弃等待则可能是不精确的。该值可能在监视和启发中很有用，但是不能用于同步性控制。方法的实现有可能显著的慢于
 * hasWaitingConsumer()方法。
 *
 * @return the number of consumers waiting to receive elements 等待接收元素的消费者的数量
 * @Description: 获取等待中的消费者总数：获取迁移队列中等待中的消费者总数。
 */
int getWaitingConsumerCount();

三 相关系列

---

• 《Java ~ Collection【目录】》
• 《Java ~ Executor【目录】》
• 《Java ~ Collection/Executor ~ TransferQueue【总结】》