| 20 |
|
* <p>This is a classic "bounded buffer", in which a |
| 21 |
|
* fixed-sized array holds elements inserted by producers and |
| 22 |
|
* extracted by consumers. Once created, the capacity cannot be |
| 23 |
< |
* increased. Attempts to <tt>put</tt> an element into a full queue |
| 24 |
< |
* will result in the operation blocking; attempts to <tt>take</tt> an |
| 23 |
> |
* changed. Attempts to {@code put} an element into a full queue |
| 24 |
> |
* will result in the operation blocking; attempts to {@code take} an |
| 25 |
|
* element from an empty queue will similarly block. |
| 26 |
|
* |
| 27 |
|
* <p> This class supports an optional fairness policy for ordering |
| 28 |
|
* waiting producer and consumer threads. By default, this ordering |
| 29 |
|
* is not guaranteed. However, a queue constructed with fairness set |
| 30 |
< |
* to <tt>true</tt> grants threads access in FIFO order. Fairness |
| 30 |
> |
* to {@code true} grants threads access in FIFO order. Fairness |
| 31 |
|
* generally decreases throughput but reduces variability and avoids |
| 32 |
|
* starvation. |
| 33 |
|
* |
| 161 |
|
} |
| 162 |
|
|
| 163 |
|
/** |
| 164 |
< |
* Creates an <tt>ArrayBlockingQueue</tt> with the given (fixed) |
| 164 |
> |
* Creates an {@code ArrayBlockingQueue} with the given (fixed) |
| 165 |
|
* capacity and default access policy. |
| 166 |
|
* |
| 167 |
|
* @param capacity the capacity of this queue |
| 168 |
< |
* @throws IllegalArgumentException if <tt>capacity</tt> is less than 1 |
| 168 |
> |
* @throws IllegalArgumentException if {@code capacity < 1} |
| 169 |
|
*/ |
| 170 |
|
public ArrayBlockingQueue(int capacity) { |
| 171 |
|
this(capacity, false); |
| 172 |
|
} |
| 173 |
|
|
| 174 |
|
/** |
| 175 |
< |
* Creates an <tt>ArrayBlockingQueue</tt> with the given (fixed) |
| 175 |
> |
* Creates an {@code ArrayBlockingQueue} with the given (fixed) |
| 176 |
|
* capacity and the specified access policy. |
| 177 |
|
* |
| 178 |
|
* @param capacity the capacity of this queue |
| 179 |
< |
* @param fair if <tt>true</tt> then queue accesses for threads blocked |
| 179 |
> |
* @param fair if {@code true} then queue accesses for threads blocked |
| 180 |
|
* on insertion or removal, are processed in FIFO order; |
| 181 |
< |
* if <tt>false</tt> the access order is unspecified. |
| 182 |
< |
* @throws IllegalArgumentException if <tt>capacity</tt> is less than 1 |
| 181 |
> |
* if {@code false} the access order is unspecified. |
| 182 |
> |
* @throws IllegalArgumentException if {@code capacity < 1} |
| 183 |
|
*/ |
| 184 |
|
public ArrayBlockingQueue(int capacity, boolean fair) { |
| 185 |
|
if (capacity <= 0) |
| 191 |
|
} |
| 192 |
|
|
| 193 |
|
/** |
| 194 |
< |
* Creates an <tt>ArrayBlockingQueue</tt> with the given (fixed) |
| 194 |
> |
* Creates an {@code ArrayBlockingQueue} with the given (fixed) |
| 195 |
|
* capacity, the specified access policy and initially containing the |
| 196 |
|
* elements of the given collection, |
| 197 |
|
* added in traversal order of the collection's iterator. |
| 198 |
|
* |
| 199 |
|
* @param capacity the capacity of this queue |
| 200 |
< |
* @param fair if <tt>true</tt> then queue accesses for threads blocked |
| 200 |
> |
* @param fair if {@code true} then queue accesses for threads blocked |
| 201 |
|
* on insertion or removal, are processed in FIFO order; |
| 202 |
< |
* if <tt>false</tt> the access order is unspecified. |
| 202 |
> |
* if {@code false} the access order is unspecified. |
| 203 |
|
* @param c the collection of elements to initially contain |
| 204 |
< |
* @throws IllegalArgumentException if <tt>capacity</tt> is less than |
| 205 |
< |
* <tt>c.size()</tt>, or less than 1. |
| 204 |
> |
* @throws IllegalArgumentException if {@code capacity} is less than |
| 205 |
> |
* {@code c.size()}, or less than 1. |
| 206 |
|
* @throws NullPointerException if the specified collection or any |
| 207 |
|
* of its elements are null |
| 208 |
|
*/ |
| 232 |
|
/** |
| 233 |
|
* Inserts the specified element at the tail of this queue if it is |
| 234 |
|
* possible to do so immediately without exceeding the queue's capacity, |
| 235 |
< |
* returning <tt>true</tt> upon success and throwing an |
| 236 |
< |
* <tt>IllegalStateException</tt> if this queue is full. |
| 235 |
> |
* returning {@code true} upon success and throwing an |
| 236 |
> |
* {@code IllegalStateException} if this queue is full. |
| 237 |
|
* |
| 238 |
|
* @param e the element to add |
| 239 |
< |
* @return <tt>true</tt> (as specified by {@link Collection#add}) |
| 239 |
> |
* @return {@code true} (as specified by {@link Collection#add}) |
| 240 |
|
* @throws IllegalStateException if this queue is full |
| 241 |
|
* @throws NullPointerException if the specified element is null |
| 242 |
|
*/ |
| 247 |
|
/** |
| 248 |
|
* Inserts the specified element at the tail of this queue if it is |
| 249 |
|
* possible to do so immediately without exceeding the queue's capacity, |
| 250 |
< |
* returning <tt>true</tt> upon success and <tt>false</tt> if this queue |
| 250 |
> |
* returning {@code true} upon success and {@code false} if this queue |
| 251 |
|
* is full. This method is generally preferable to method {@link #add}, |
| 252 |
|
* which can fail to insert an element only by throwing an exception. |
| 253 |
|
* |
| 388 |
|
* Returns the number of additional elements that this queue can ideally |
| 389 |
|
* (in the absence of memory or resource constraints) accept without |
| 390 |
|
* blocking. This is always equal to the initial capacity of this queue |
| 391 |
< |
* less the current <tt>size</tt> of this queue. |
| 391 |
> |
* less the current {@code size} of this queue. |
| 392 |
|
* |
| 393 |
|
* <p>Note that you <em>cannot</em> always tell if an attempt to insert |
| 394 |
< |
* an element will succeed by inspecting <tt>remainingCapacity</tt> |
| 394 |
> |
* an element will succeed by inspecting {@code remainingCapacity} |
| 395 |
|
* because it may be the case that another thread is about to |
| 396 |
|
* insert or remove an element. |
| 397 |
|
*/ |
| 407 |
|
|
| 408 |
|
/** |
| 409 |
|
* Removes a single instance of the specified element from this queue, |
| 410 |
< |
* if it is present. More formally, removes an element <tt>e</tt> such |
| 411 |
< |
* that <tt>o.equals(e)</tt>, if this queue contains one or more such |
| 410 |
> |
* if it is present. More formally, removes an element {@code e} such |
| 411 |
> |
* that {@code o.equals(e)}, if this queue contains one or more such |
| 412 |
|
* elements. |
| 413 |
< |
* Returns <tt>true</tt> if this queue contained the specified element |
| 413 |
> |
* Returns {@code true} if this queue contained the specified element |
| 414 |
|
* (or equivalently, if this queue changed as a result of the call). |
| 415 |
|
* |
| 416 |
|
* <p>Removal of interior elements in circular array based queues |
| 420 |
|
* threads. |
| 421 |
|
* |
| 422 |
|
* @param o element to be removed from this queue, if present |
| 423 |
< |
* @return <tt>true</tt> if this queue changed as a result of the call |
| 423 |
> |
* @return {@code true} if this queue changed as a result of the call |
| 424 |
|
*/ |
| 425 |
|
public boolean remove(Object o) { |
| 426 |
|
if (o == null) return false; |
| 441 |
|
} |
| 442 |
|
|
| 443 |
|
/** |
| 444 |
< |
* Returns <tt>true</tt> if this queue contains the specified element. |
| 445 |
< |
* More formally, returns <tt>true</tt> if and only if this queue contains |
| 446 |
< |
* at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>. |
| 444 |
> |
* Returns {@code true} if this queue contains the specified element. |
| 445 |
> |
* More formally, returns {@code true} if and only if this queue contains |
| 446 |
> |
* at least one element {@code e} such that {@code o.equals(e)}. |
| 447 |
|
* |
| 448 |
|
* @param o object to be checked for containment in this queue |
| 449 |
< |
* @return <tt>true</tt> if this queue contains the specified element |
| 449 |
> |
* @return {@code true} if this queue contains the specified element |
| 450 |
|
*/ |
| 451 |
|
public boolean contains(Object o) { |
| 452 |
|
if (o == null) return false; |
| 501 |
|
* <p>If this queue fits in the specified array with room to spare |
| 502 |
|
* (i.e., the array has more elements than this queue), the element in |
| 503 |
|
* the array immediately following the end of the queue is set to |
| 504 |
< |
* <tt>null</tt>. |
| 504 |
> |
* {@code null}. |
| 505 |
|
* |
| 506 |
|
* <p>Like the {@link #toArray()} method, this method acts as bridge between |
| 507 |
|
* array-based and collection-based APIs. Further, this method allows |
| 508 |
|
* precise control over the runtime type of the output array, and may, |
| 509 |
|
* under certain circumstances, be used to save allocation costs. |
| 510 |
|
* |
| 511 |
< |
* <p>Suppose <tt>x</tt> is a queue known to contain only strings. |
| 511 |
> |
* <p>Suppose {@code x} is a queue known to contain only strings. |
| 512 |
|
* The following code can be used to dump the queue into a newly |
| 513 |
< |
* allocated array of <tt>String</tt>: |
| 513 |
> |
* allocated array of {@code String}: |
| 514 |
|
* |
| 515 |
|
* <pre> |
| 516 |
|
* String[] y = x.toArray(new String[0]);</pre> |
| 517 |
|
* |
| 518 |
< |
* Note that <tt>toArray(new Object[0])</tt> is identical in function to |
| 519 |
< |
* <tt>toArray()</tt>. |
| 518 |
> |
* Note that {@code toArray(new Object[0])} is identical in function to |
| 519 |
> |
* {@code toArray()}. |
| 520 |
|
* |
| 521 |
|
* @param a the array into which the elements of the queue are to |
| 522 |
|
* be stored, if it is big enough; otherwise, a new array of the |
| 664 |
|
|
| 665 |
|
/** |
| 666 |
|
* Returns an iterator over the elements in this queue in proper |
| 667 |
< |
* sequence. The returned <tt>Iterator</tt> is "weakly |
| 667 |
> |
* sequence. The returned {@code Iterator} is "weakly |
| 668 |
|
* consistent" with respect to operations at the head and tail of |
| 669 |
|
* the queue, and will never throw {@link |
| 670 |
|
* ConcurrentModificationException}. It might return elements |
