Java集合类框架源码分析 之 TransferQueue接口源码解析 【12】

先看类简介：

/**
 * 生产者可以等待消费者接收元素，当消息在应用传递时，生产者通过 transfer()等待消费者调用 take()/poll()来接收元素，很有用。在其他时候，通过put()可以不等待接收。
 * tryTransfer()/tryTransfer(Object) Non-blocking()/tryTransfer(Object,long,TimeUnit) time-out版本也可用。
 * 也可以通过hasWaitingConsumer()来查询是否有线程在等待元素，这与peek()操作相反。 
 * 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.
 *
 * 就像其他的阻塞队列,TransferQueue也可能有容量限制.如果这样，尝试的传输操作可能首先阻塞对可用空间的等待，并且/或随后阻塞对消费者接收的等待。
 * 注意，在一个容量为零的队列中，例如{@link SynchronousQueue}， {@code put}和{@code transfer}实际上是同义的。 
 * <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.
 *
 * <p>This interface is a member of the
 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
 * Java Collections Framework</a>.
 *
 * @since 1.7
 * @author Doug Lea
 * @param <E> the type of elements held in this collection
 */

从类简介中可知两点：

1、生产者通过 transfer()等待消费者调用 take()/poll()来接收元素，如果消费者没有获取元素，那么当此入队操作就是一次失败的入队操作。

2、SynchronousQueue 是一个容量为0的BlockingQueue队列，并非是TransferQueue队列，但它的put()和TransferQueue中的transfer()操作是同义的。

看类源码实现：

public interface TransferQueue<E> extends BlockingQueue<E> {
    /**
     * 等待 consumer之后，立马开始传输一个文件。
     * Transfers the element to a waiting consumer immediately, if possible.
     *
     * 更严格来说，如果存在一个用户通过take()或者定时poll(),已经在等待接收,可以立马进行元素传输。否认元素没有入队列，并返回false.
     * 如果被添加的元素，阻止其被添加到队列中，返回false。
     * <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.
     *
     * @param e the element to transfer
     * @return {@code true} if the element was transferred, else
     *         {@code 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
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this queue
     */
    boolean tryTransfer(E e);

    /**
     * 如果需要的话，给消费者传递一个元素。
     * Transfers the element to a consumer, waiting if necessary to do so.
     *
     * 更严格来说，如果存在一个用户通过take()或者定时poll(),已经在等待接收,可以立马进行元素传输。否则一直等待直到元素被消费者接收。
     * <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.
     *
     * @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
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this queue
     */
    void transfer(E e) throws InterruptedException;

    /**
     * 在超时之前，如果可能的话，给消费者传递一个元素
     * Transfers the element to a consumer if it is possible to do so
     * before the timeout elapses.
     *
     * 在元素被传递之前，等待指定的时间，超时则返回false。
     * <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.
     *
     * @param e the element to transfer
     * @param timeout how long to wait before giving up, in units of
     *        {@code unit}
     * 等待时间的单位
     * @param unit a {@code TimeUnit} determining how to interpret the
     *        {@code timeout} parameter
     * 成功的话返回true，否则返回false，此时元素没有离开队列。
     * @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
     * 等待的时候被打断，抛出 InterruptedException异常，此时元素没有离开队列。
     * @throws InterruptedException if interrupted while waiting,
     *         in which case the element is not left enqueued
     * 如果指定的元素拒绝被插入队列，抛出 ClassCastException异常。
     * @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
     * 如果指定元素的部分属性，拒绝被插入队列，抛出 IllegalArgumentException异常。
     * @throws IllegalArgumentException if some property of the specified
     *         element prevents it from being added to this queue
     */
    boolean tryTransfer(E e, long timeout, TimeUnit unit)
        throws InterruptedException;

    /**
     * 如果至少有一个消费者通过take()/定时poll()在等待接收元素，返回事务瞬时状态值(true)
     * 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.
     *
     * @return {@code true} if there is at least one waiting consumer
     */
    boolean hasWaitingConsumer();

    /**
     * 返回正在通过take/定时poll接收元素的消费者预估数量。返回值是瞬时状态的预估值，如果消费者完成或放弃等待，该值可能不准确。
     * 该值作为监控和探索可能比较有用，但是不能作为同步控制。该方法实现，明显比 hasWaitingConsumer()慢。
     * 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}.
     *
     * @return the number of consumers waiting to receive elements
     */
    int getWaitingConsumerCount();
}

 tryTransfer()：会立马返回结果，如果成功，就返回true，失败返回false；

 transfer()：会等待元素被消费者取走

tryTransfer(E e, long timeout, TimeUnit unit)：在指定的时间内等待元素被消费者接收，否则返回false；

getWaitingConsumerCount()：该方法只是一个大概的估计值，作为监控比较有用，但是不能作为同步的依据，并且会比hasWaitingConsumer()慢。