E
- the type of elements held in this collectionpublic interface TransferQueue<E> extends BlockingQueue<E>
BlockingQueue
in which producers may wait for consumers to receive elements. A
TransferQueue
may be useful for example in message passing applications in which
producers sometimes (using method transfer
) await receipt of elements by consumers
invoking take
or poll
, while at other times enqueue elements (via method
put
) without waiting for receipt. Non-blocking and time-out versions of
tryTransfer
are also available. A TransferQueue may also be queried via
hasWaitingConsumer
whether there are any threads waiting for items, which is a converse
analogy to a peek
operation.
Like any BlockingQueue
, a 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 SynchronousQueue
, put
and transfer
are effectively synonymous.
This interface is a member of the Java Collections Framework.
Modifier and Type | Method and Description |
---|---|
int |
getWaitingConsumerCount()
Returns an estimate of the number of consumers waiting to dequeue elements via
take or
poll . |
boolean |
hasWaitingConsumer()
Returns
true if there is at least one consumer waiting to dequeue an element via
take or poll . |
void |
transfer(E e)
Inserts the specified element into this queue, waiting if necessary for space to become
available and the element to be dequeued by a consumer invoking
take or poll . |
boolean |
tryTransfer(E e)
Transfers the specified element if there exists a consumer already waiting to receive it,
otherwise returning
false without enqueuing the element. |
boolean |
tryTransfer(E e,
long timeout,
TimeUnit unit)
Inserts the specified element into this queue, waiting up to the specified wait time if
necessary for space to become available and the element to be dequeued by a consumer invoking
take or poll . |
boolean tryTransfer(E e)
false
without enqueuing the element.e
- the element to transfertrue
if the element was transferred, else false
ClassCastException
- if the class of the specified element prevents it from being added
to this queueNullPointerException
- if the specified element is nullIllegalArgumentException
- if some property of the specified element prevents it from
being added to this queuevoid transfer(E e) throws InterruptedException
take
or poll
.e
- the element to transferInterruptedException
- if interrupted while waiting, in which case the element is not
enqueued.ClassCastException
- if the class of the specified element prevents it from being added
to this queueNullPointerException
- if the specified element is nullIllegalArgumentException
- if some property of the specified element prevents it from
being added to this queueboolean tryTransfer(E e, long timeout, TimeUnit unit) throws InterruptedException
take
or poll
.e
- the element to transfertimeout
- how long to wait before giving up, in units of unit
unit
- a TimeUnit
determining how to interpret the timeout
parametertrue
if successful, or false
if the specified waiting time elapses
before completion, in which case the element is not enqueued.InterruptedException
- if interrupted while waiting, in which case the element is not
enqueued.ClassCastException
- if the class of the specified element prevents it from being added
to this queueNullPointerException
- if the specified element is nullIllegalArgumentException
- if some property of the specified element prevents it from
being added to this queueboolean hasWaitingConsumer()
true
if there is at least one consumer waiting to dequeue an element via
take
or poll
. The return value represents a momentary state of affairs.true
if there is at least one waiting consumerint getWaitingConsumerCount()
take
or
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 hasWaitingConsumer()
.Copyright © 2021. All rights reserved.