BlockingQueue 源码分析

阅读更多

public interface BlockingQueue extends Queue {
    /**
     * 插入指定元素到队列中，如果没有超出容量限制的话, 插入成功，返回 true. 如果没有空间的话，抛出 IllegalStateException.
     * 当使用有容量限制的队列(queue)时，通常最好是使用 offer(Object) 方法.
     *
     */
    boolean add(E e);

    /**
     * 插入指定元素到队列中，如果没有超出容量限制的话, 插入成功，返回 true, 如果没有空间的话返回 false.
     * 当使用有容量限制的队列时，这个方法比 add 方法更好(当插入失败的时候，抛异常).
     *
     */
    boolean offer(E e);

    /**
     * 插入指定元素到队列中，必要时等待空间可用.
     *
     */
    void put(E e) throws InterruptedException;

    /**
     * 插入指定元素到队列中，必要时等待指定的时间等待元素可用.
     *
     */
    boolean offer(E e, long timeout, TimeUnit unit)
        throws InterruptedException;

    /**
     * 检索并删除队列的头部，必要时等待直到元素可用.
     *
     */
    E take() throws InterruptedException;

    /**
     * 检索并移除队列的头部，必要时等待指定的时间等待元素可用.
     *
     */
    E poll(long timeout, TimeUnit unit)
        throws InterruptedException;

    /**
     *
     * 返回这个队列在理想状态下可以非阻塞接收的元素的个数。如果没有明确指定队列容量，那么就返回Integer.MAX_VALUE.
     * 注意：无法总是判断尝试插入一个元素是否成功通过检查 remainingCapacity 方法. 因为可能存在这么一种情况，另外一个线程
     * 即将插入或者移除一个元素.
     *
     */
    int remainingCapacity();

    /**
     *
     * 从队列中删除指定元素的单个实例，如果它存在的话. 更正式的说，删除元素 e(o.equals(e)), 如果队列
     * 中包含一个或者多个这样的元素. 如果此队列包含指定的元素，则返回 true(或者等效的说，如果此队列因调用
     * 这个方法而发生了更改).
     *
     */
    boolean remove(Object o);

    /**
     * 如果此队列包含指定元素，则返回 true. 更正式的说，如果这个队列中包含至少一个 e(o.equals(e))
     * 这种情况下才返回 true.
     *
     */
    public boolean contains(Object o);

    /**
     *
     * 删除此队列中的所有可用元素并将它们添加到给定的集合中. 这个操作比反复 polling 这个队列更加有效.
     * 当相关的异常抛出时，可能会导致将元素添加到集合c的过程中该元素不在任何一个集合中。尝试将一个队列中的
     * 元素批量保存到队列本身会抛出IllegalArgumentException.
     * 当在执行 drainTo 的过程中如果指定的集合 c 被修改了，那么这种情况产生的结果是未知的.
     *
     */
    int drainTo(Collection c);

    /**
     *
     * 将指定数量的元素从队列中删除，并保存到指定的集合中.
     * 当相关的异常抛出时，可能会导致将元素添加到集合 c 的过程中该元素不在任何一个集合中.
     * 尝试将一个队列中的元素批量保存到队列本身会抛出 IllegalArgumentException.
     * 当在执行 drainTo 的过程中如果指定的集合 c 被修改了，那么这种情况产生的结果是未知的.
     */
    int drainTo(Collection c, int maxElements);
}