GNU Classpath (0.98) | |
Frames | No Frames |
1: /* 2: * Written by Doug Lea with assistance from members of JCP JSR-166 3: * Expert Group and released to the public domain, as explained at 4: * http://creativecommons.org/licenses/publicdomain 5: */ 6: 7: package java.util.concurrent; 8: import java.util.*; 9: 10: /** 11: * A {@link Deque} that additionally supports blocking operations that wait 12: * for the deque to become non-empty when retrieving an element, and wait for 13: * space to become available in the deque when storing an element. 14: * 15: * <p><tt>BlockingDeque</tt> methods come in four forms, with different ways 16: * of handling operations that cannot be satisfied immediately, but may be 17: * satisfied at some point in the future: 18: * one throws an exception, the second returns a special value (either 19: * <tt>null</tt> or <tt>false</tt>, depending on the operation), the third 20: * blocks the current thread indefinitely until the operation can succeed, 21: * and the fourth blocks for only a given maximum time limit before giving 22: * up. These methods are summarized in the following table: 23: * 24: * <p> 25: * <table BORDER CELLPADDING=3 CELLSPACING=1> 26: * <tr> 27: * <td ALIGN=CENTER COLSPAN = 5> <b>First Element (Head)</b></td> 28: * </tr> 29: * <tr> 30: * <td></td> 31: * <td ALIGN=CENTER><em>Throws exception</em></td> 32: * <td ALIGN=CENTER><em>Special value</em></td> 33: * <td ALIGN=CENTER><em>Blocks</em></td> 34: * <td ALIGN=CENTER><em>Times out</em></td> 35: * </tr> 36: * <tr> 37: * <td><b>Insert</b></td> 38: * <td>{@link #addFirst addFirst(e)}</td> 39: * <td>{@link #offerFirst(Object) offerFirst(e)}</td> 40: * <td>{@link #putFirst putFirst(e)}</td> 41: * <td>{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)}</td> 42: * </tr> 43: * <tr> 44: * <td><b>Remove</b></td> 45: * <td>{@link #removeFirst removeFirst()}</td> 46: * <td>{@link #pollFirst pollFirst()}</td> 47: * <td>{@link #takeFirst takeFirst()}</td> 48: * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td> 49: * </tr> 50: * <tr> 51: * <td><b>Examine</b></td> 52: * <td>{@link #getFirst getFirst()}</td> 53: * <td>{@link #peekFirst peekFirst()}</td> 54: * <td><em>not applicable</em></td> 55: * <td><em>not applicable</em></td> 56: * </tr> 57: * <tr> 58: * <td ALIGN=CENTER COLSPAN = 5> <b>Last Element (Tail)</b></td> 59: * </tr> 60: * <tr> 61: * <td></td> 62: * <td ALIGN=CENTER><em>Throws exception</em></td> 63: * <td ALIGN=CENTER><em>Special value</em></td> 64: * <td ALIGN=CENTER><em>Blocks</em></td> 65: * <td ALIGN=CENTER><em>Times out</em></td> 66: * </tr> 67: * <tr> 68: * <td><b>Insert</b></td> 69: * <td>{@link #addLast addLast(e)}</td> 70: * <td>{@link #offerLast(Object) offerLast(e)}</td> 71: * <td>{@link #putLast putLast(e)}</td> 72: * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td> 73: * </tr> 74: * <tr> 75: * <td><b>Remove</b></td> 76: * <td>{@link #removeLast() removeLast()}</td> 77: * <td>{@link #pollLast() pollLast()}</td> 78: * <td>{@link #takeLast takeLast()}</td> 79: * <td>{@link #pollLast(long, TimeUnit) pollLast(time, unit)}</td> 80: * </tr> 81: * <tr> 82: * <td><b>Examine</b></td> 83: * <td>{@link #getLast getLast()}</td> 84: * <td>{@link #peekLast peekLast()}</td> 85: * <td><em>not applicable</em></td> 86: * <td><em>not applicable</em></td> 87: * </tr> 88: * </table> 89: * 90: * <p>Like any {@link BlockingQueue}, a <tt>BlockingDeque</tt> is thread safe, 91: * does not permit null elements, and may (or may not) be 92: * capacity-constrained. 93: * 94: * <p>A <tt>BlockingDeque</tt> implementation may be used directly as a FIFO 95: * <tt>BlockingQueue</tt>. The methods inherited from the 96: * <tt>BlockingQueue</tt> interface are precisely equivalent to 97: * <tt>BlockingDeque</tt> methods as indicated in the following table: 98: * 99: * <p> 100: * <table BORDER CELLPADDING=3 CELLSPACING=1> 101: * <tr> 102: * <td ALIGN=CENTER> <b><tt>BlockingQueue</tt> Method</b></td> 103: * <td ALIGN=CENTER> <b>Equivalent <tt>BlockingDeque</tt> Method</b></td> 104: * </tr> 105: * <tr> 106: * <td ALIGN=CENTER COLSPAN = 2> <b>Insert</b></td> 107: * </tr> 108: * <tr> 109: * <td>{@link #add(Object) add(e)}</td> 110: * <td>{@link #addLast(Object) addLast(e)}</td> 111: * </tr> 112: * <tr> 113: * <td>{@link #offer(Object) offer(e)}</td> 114: * <td>{@link #offerLast(Object) offerLast(e)}</td> 115: * </tr> 116: * <tr> 117: * <td>{@link #put(Object) put(e)}</td> 118: * <td>{@link #putLast(Object) putLast(e)}</td> 119: * </tr> 120: * <tr> 121: * <td>{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</td> 122: * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td> 123: * </tr> 124: * <tr> 125: * <td ALIGN=CENTER COLSPAN = 2> <b>Remove</b></td> 126: * </tr> 127: * <tr> 128: * <td>{@link #remove() remove()}</td> 129: * <td>{@link #removeFirst() removeFirst()}</td> 130: * </tr> 131: * <tr> 132: * <td>{@link #poll() poll()}</td> 133: * <td>{@link #pollFirst() pollFirst()}</td> 134: * </tr> 135: * <tr> 136: * <td>{@link #take() take()}</td> 137: * <td>{@link #takeFirst() takeFirst()}</td> 138: * </tr> 139: * <tr> 140: * <td>{@link #poll(long, TimeUnit) poll(time, unit)}</td> 141: * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td> 142: * </tr> 143: * <tr> 144: * <td ALIGN=CENTER COLSPAN = 2> <b>Examine</b></td> 145: * </tr> 146: * <tr> 147: * <td>{@link #element() element()}</td> 148: * <td>{@link #getFirst() getFirst()}</td> 149: * </tr> 150: * <tr> 151: * <td>{@link #peek() peek()}</td> 152: * <td>{@link #peekFirst() peekFirst()}</td> 153: * </tr> 154: * </table> 155: * 156: * <p>Memory consistency effects: As with other concurrent 157: * collections, actions in a thread prior to placing an object into a 158: * {@code BlockingDeque} 159: * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a> 160: * actions subsequent to the access or removal of that element from 161: * the {@code BlockingDeque} in another thread. 162: * 163: * <p>This interface is a member of the 164: * <a href="{@docRoot}/../technotes/guides/collections/index.html"> 165: * Java Collections Framework</a>. 166: * 167: * @since 1.6 168: * @author Doug Lea 169: * @param <E> the type of elements held in this collection 170: */ 171: public interface BlockingDeque<E> extends BlockingQueue<E>, Deque<E> { 172: /* 173: * We have "diamond" multiple interface inheritance here, and that 174: * introduces ambiguities. Methods might end up with different 175: * specs depending on the branch chosen by javadoc. Thus a lot of 176: * methods specs here are copied from superinterfaces. 177: */ 178: 179: /** 180: * Inserts the specified element at the front of this deque if it is 181: * possible to do so immediately without violating capacity restrictions, 182: * throwing an <tt>IllegalStateException</tt> if no space is currently 183: * available. When using a capacity-restricted deque, it is generally 184: * preferable to use {@link #offerFirst(Object) offerFirst}. 185: * 186: * @param e the element to add 187: * @throws IllegalStateException {@inheritDoc} 188: * @throws ClassCastException {@inheritDoc} 189: * @throws NullPointerException if the specified element is null 190: * @throws IllegalArgumentException {@inheritDoc} 191: */ 192: void addFirst(E e); 193: 194: /** 195: * Inserts the specified element at the end of this deque if it is 196: * possible to do so immediately without violating capacity restrictions, 197: * throwing an <tt>IllegalStateException</tt> if no space is currently 198: * available. When using a capacity-restricted deque, it is generally 199: * preferable to use {@link #offerLast(Object) offerLast}. 200: * 201: * @param e the element to add 202: * @throws IllegalStateException {@inheritDoc} 203: * @throws ClassCastException {@inheritDoc} 204: * @throws NullPointerException if the specified element is null 205: * @throws IllegalArgumentException {@inheritDoc} 206: */ 207: void addLast(E e); 208: 209: /** 210: * Inserts the specified element at the front of this deque if it is 211: * possible to do so immediately without violating capacity restrictions, 212: * returning <tt>true</tt> upon success and <tt>false</tt> if no space is 213: * currently available. 214: * When using a capacity-restricted deque, this method is generally 215: * preferable to the {@link #addFirst(Object) addFirst} method, which can 216: * fail to insert an element only by throwing an exception. 217: * 218: * @param e the element to add 219: * @throws ClassCastException {@inheritDoc} 220: * @throws NullPointerException if the specified element is null 221: * @throws IllegalArgumentException {@inheritDoc} 222: */ 223: boolean offerFirst(E e); 224: 225: /** 226: * Inserts the specified element at the end of this deque if it is 227: * possible to do so immediately without violating capacity restrictions, 228: * returning <tt>true</tt> upon success and <tt>false</tt> if no space is 229: * currently available. 230: * When using a capacity-restricted deque, this method is generally 231: * preferable to the {@link #addLast(Object) addLast} method, which can 232: * fail to insert an element only by throwing an exception. 233: * 234: * @param e the element to add 235: * @throws ClassCastException {@inheritDoc} 236: * @throws NullPointerException if the specified element is null 237: * @throws IllegalArgumentException {@inheritDoc} 238: */ 239: boolean offerLast(E e); 240: 241: /** 242: * Inserts the specified element at the front of this deque, 243: * waiting if necessary for space to become available. 244: * 245: * @param e the element to add 246: * @throws InterruptedException if interrupted while waiting 247: * @throws ClassCastException if the class of the specified element 248: * prevents it from being added to this deque 249: * @throws NullPointerException if the specified element is null 250: * @throws IllegalArgumentException if some property of the specified 251: * element prevents it from being added to this deque 252: */ 253: void putFirst(E e) throws InterruptedException; 254: 255: /** 256: * Inserts the specified element at the end of this deque, 257: * waiting if necessary for space to become available. 258: * 259: * @param e the element to add 260: * @throws InterruptedException if interrupted while waiting 261: * @throws ClassCastException if the class of the specified element 262: * prevents it from being added to this deque 263: * @throws NullPointerException if the specified element is null 264: * @throws IllegalArgumentException if some property of the specified 265: * element prevents it from being added to this deque 266: */ 267: void putLast(E e) throws InterruptedException; 268: 269: /** 270: * Inserts the specified element at the front of this deque, 271: * waiting up to the specified wait time if necessary for space to 272: * become available. 273: * 274: * @param e the element to add 275: * @param timeout how long to wait before giving up, in units of 276: * <tt>unit</tt> 277: * @param unit a <tt>TimeUnit</tt> determining how to interpret the 278: * <tt>timeout</tt> parameter 279: * @return <tt>true</tt> if successful, or <tt>false</tt> if 280: * the specified waiting time elapses before space is available 281: * @throws InterruptedException if interrupted while waiting 282: * @throws ClassCastException if the class of the specified element 283: * prevents it from being added to this deque 284: * @throws NullPointerException if the specified element is null 285: * @throws IllegalArgumentException if some property of the specified 286: * element prevents it from being added to this deque 287: */ 288: boolean offerFirst(E e, long timeout, TimeUnit unit) 289: throws InterruptedException; 290: 291: /** 292: * Inserts the specified element at the end of this deque, 293: * waiting up to the specified wait time if necessary for space to 294: * become available. 295: * 296: * @param e the element to add 297: * @param timeout how long to wait before giving up, in units of 298: * <tt>unit</tt> 299: * @param unit a <tt>TimeUnit</tt> determining how to interpret the 300: * <tt>timeout</tt> parameter 301: * @return <tt>true</tt> if successful, or <tt>false</tt> if 302: * the specified waiting time elapses before space is available 303: * @throws InterruptedException if interrupted while waiting 304: * @throws ClassCastException if the class of the specified element 305: * prevents it from being added to this deque 306: * @throws NullPointerException if the specified element is null 307: * @throws IllegalArgumentException if some property of the specified 308: * element prevents it from being added to this deque 309: */ 310: boolean offerLast(E e, long timeout, TimeUnit unit) 311: throws InterruptedException; 312: 313: /** 314: * Retrieves and removes the first element of this deque, waiting 315: * if necessary until an element becomes available. 316: * 317: * @return the head of this deque 318: * @throws InterruptedException if interrupted while waiting 319: */ 320: E takeFirst() throws InterruptedException; 321: 322: /** 323: * Retrieves and removes the last element of this deque, waiting 324: * if necessary until an element becomes available. 325: * 326: * @return the tail of this deque 327: * @throws InterruptedException if interrupted while waiting 328: */ 329: E takeLast() throws InterruptedException; 330: 331: /** 332: * Retrieves and removes the first element of this deque, waiting 333: * up to the specified wait time if necessary for an element to 334: * become available. 335: * 336: * @param timeout how long to wait before giving up, in units of 337: * <tt>unit</tt> 338: * @param unit a <tt>TimeUnit</tt> determining how to interpret the 339: * <tt>timeout</tt> parameter 340: * @return the head of this deque, or <tt>null</tt> if the specified 341: * waiting time elapses before an element is available 342: * @throws InterruptedException if interrupted while waiting 343: */ 344: E pollFirst(long timeout, TimeUnit unit) 345: throws InterruptedException; 346: 347: /** 348: * Retrieves and removes the last element of this deque, waiting 349: * up to the specified wait time if necessary for an element to 350: * become available. 351: * 352: * @param timeout how long to wait before giving up, in units of 353: * <tt>unit</tt> 354: * @param unit a <tt>TimeUnit</tt> determining how to interpret the 355: * <tt>timeout</tt> parameter 356: * @return the tail of this deque, or <tt>null</tt> if the specified 357: * waiting time elapses before an element is available 358: * @throws InterruptedException if interrupted while waiting 359: */ 360: E pollLast(long timeout, TimeUnit unit) 361: throws InterruptedException; 362: 363: /** 364: * Removes the first occurrence of the specified element from this deque. 365: * If the deque does not contain the element, it is unchanged. 366: * More formally, removes the first element <tt>e</tt> such that 367: * <tt>o.equals(e)</tt> (if such an element exists). 368: * Returns <tt>true</tt> if this deque contained the specified element 369: * (or equivalently, if this deque changed as a result of the call). 370: * 371: * @param o element to be removed from this deque, if present 372: * @return <tt>true</tt> if an element was removed as a result of this call 373: * @throws ClassCastException if the class of the specified element 374: * is incompatible with this deque (optional) 375: * @throws NullPointerException if the specified element is null (optional) 376: */ 377: boolean removeFirstOccurrence(Object o); 378: 379: /** 380: * Removes the last occurrence of the specified element from this deque. 381: * If the deque does not contain the element, it is unchanged. 382: * More formally, removes the last element <tt>e</tt> such that 383: * <tt>o.equals(e)</tt> (if such an element exists). 384: * Returns <tt>true</tt> if this deque contained the specified element 385: * (or equivalently, if this deque changed as a result of the call). 386: * 387: * @param o element to be removed from this deque, if present 388: * @return <tt>true</tt> if an element was removed as a result of this call 389: * @throws ClassCastException if the class of the specified element 390: * is incompatible with this deque (optional) 391: * @throws NullPointerException if the specified element is null (optional) 392: */ 393: boolean removeLastOccurrence(Object o); 394: 395: // *** BlockingQueue methods *** 396: 397: /** 398: * Inserts the specified element into the queue represented by this deque 399: * (in other words, at the tail of this deque) if it is possible to do so 400: * immediately without violating capacity restrictions, returning 401: * <tt>true</tt> upon success and throwing an 402: * <tt>IllegalStateException</tt> if no space is currently available. 403: * When using a capacity-restricted deque, it is generally preferable to 404: * use {@link #offer(Object) offer}. 405: * 406: * <p>This method is equivalent to {@link #addLast(Object) addLast}. 407: * 408: * @param e the element to add 409: * @throws IllegalStateException {@inheritDoc} 410: * @throws ClassCastException if the class of the specified element 411: * prevents it from being added to this deque 412: * @throws NullPointerException if the specified element is null 413: * @throws IllegalArgumentException if some property of the specified 414: * element prevents it from being added to this deque 415: */ 416: boolean add(E e); 417: 418: /** 419: * Inserts the specified element into the queue represented by this deque 420: * (in other words, at the tail of this deque) if it is possible to do so 421: * immediately without violating capacity restrictions, returning 422: * <tt>true</tt> upon success and <tt>false</tt> if no space is currently 423: * available. When using a capacity-restricted deque, this method is 424: * generally preferable to the {@link #add} method, which can fail to 425: * insert an element only by throwing an exception. 426: * 427: * <p>This method is equivalent to {@link #offerLast(Object) offerLast}. 428: * 429: * @param e the element to add 430: * @throws ClassCastException if the class of the specified element 431: * prevents it from being added to this deque 432: * @throws NullPointerException if the specified element is null 433: * @throws IllegalArgumentException if some property of the specified 434: * element prevents it from being added to this deque 435: */ 436: boolean offer(E e); 437: 438: /** 439: * Inserts the specified element into the queue represented by this deque 440: * (in other words, at the tail of this deque), waiting if necessary for 441: * space to become available. 442: * 443: * <p>This method is equivalent to {@link #putLast(Object) putLast}. 444: * 445: * @param e the element to add 446: * @throws InterruptedException {@inheritDoc} 447: * @throws ClassCastException if the class of the specified element 448: * prevents it from being added to this deque 449: * @throws NullPointerException if the specified element is null 450: * @throws IllegalArgumentException if some property of the specified 451: * element prevents it from being added to this deque 452: */ 453: void put(E e) throws InterruptedException; 454: 455: /** 456: * Inserts the specified element into the queue represented by this deque 457: * (in other words, at the tail of this deque), waiting up to the 458: * specified wait time if necessary for space to become available. 459: * 460: * <p>This method is equivalent to 461: * {@link #offerLast(Object,long,TimeUnit) offerLast}. 462: * 463: * @param e the element to add 464: * @return <tt>true</tt> if the element was added to this deque, else 465: * <tt>false</tt> 466: * @throws InterruptedException {@inheritDoc} 467: * @throws ClassCastException if the class of the specified element 468: * prevents it from being added to this deque 469: * @throws NullPointerException if the specified element is null 470: * @throws IllegalArgumentException if some property of the specified 471: * element prevents it from being added to this deque 472: */ 473: boolean offer(E e, long timeout, TimeUnit unit) 474: throws InterruptedException; 475: 476: /** 477: * Retrieves and removes the head of the queue represented by this deque 478: * (in other words, the first element of this deque). 479: * This method differs from {@link #poll poll} only in that it 480: * throws an exception if this deque is empty. 481: * 482: * <p>This method is equivalent to {@link #removeFirst() removeFirst}. 483: * 484: * @return the head of the queue represented by this deque 485: * @throws NoSuchElementException if this deque is empty 486: */ 487: E remove(); 488: 489: /** 490: * Retrieves and removes the head of the queue represented by this deque 491: * (in other words, the first element of this deque), or returns 492: * <tt>null</tt> if this deque is empty. 493: * 494: * <p>This method is equivalent to {@link #pollFirst()}. 495: * 496: * @return the head of this deque, or <tt>null</tt> if this deque is empty 497: */ 498: E poll(); 499: 500: /** 501: * Retrieves and removes the head of the queue represented by this deque 502: * (in other words, the first element of this deque), waiting if 503: * necessary until an element becomes available. 504: * 505: * <p>This method is equivalent to {@link #takeFirst() takeFirst}. 506: * 507: * @return the head of this deque 508: * @throws InterruptedException if interrupted while waiting 509: */ 510: E take() throws InterruptedException; 511: 512: /** 513: * Retrieves and removes the head of the queue represented by this deque 514: * (in other words, the first element of this deque), waiting up to the 515: * specified wait time if necessary for an element to become available. 516: * 517: * <p>This method is equivalent to 518: * {@link #pollFirst(long,TimeUnit) pollFirst}. 519: * 520: * @return the head of this deque, or <tt>null</tt> if the 521: * specified waiting time elapses before an element is available 522: * @throws InterruptedException if interrupted while waiting 523: */ 524: E poll(long timeout, TimeUnit unit) 525: throws InterruptedException; 526: 527: /** 528: * Retrieves, but does not remove, the head of the queue represented by 529: * this deque (in other words, the first element of this deque). 530: * This method differs from {@link #peek peek} only in that it throws an 531: * exception if this deque is empty. 532: * 533: * <p>This method is equivalent to {@link #getFirst() getFirst}. 534: * 535: * @return the head of this deque 536: * @throws NoSuchElementException if this deque is empty 537: */ 538: E element(); 539: 540: /** 541: * Retrieves, but does not remove, the head of the queue represented by 542: * this deque (in other words, the first element of this deque), or 543: * returns <tt>null</tt> if this deque is empty. 544: * 545: * <p>This method is equivalent to {@link #peekFirst() peekFirst}. 546: * 547: * @return the head of this deque, or <tt>null</tt> if this deque is empty 548: */ 549: E peek(); 550: 551: /** 552: * Removes the first occurrence of the specified element from this deque. 553: * If the deque does not contain the element, it is unchanged. 554: * More formally, removes the first element <tt>e</tt> such that 555: * <tt>o.equals(e)</tt> (if such an element exists). 556: * Returns <tt>true</tt> if this deque contained the specified element 557: * (or equivalently, if this deque changed as a result of the call). 558: * 559: * <p>This method is equivalent to 560: * {@link #removeFirstOccurrence(Object) removeFirstOccurrence}. 561: * 562: * @param o element to be removed from this deque, if present 563: * @return <tt>true</tt> if this deque changed as a result of the call 564: * @throws ClassCastException if the class of the specified element 565: * is incompatible with this deque (optional) 566: * @throws NullPointerException if the specified element is null (optional) 567: */ 568: boolean remove(Object o); 569: 570: /** 571: * Returns <tt>true</tt> if this deque contains the specified element. 572: * More formally, returns <tt>true</tt> if and only if this deque contains 573: * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>. 574: * 575: * @param o object to be checked for containment in this deque 576: * @return <tt>true</tt> if this deque contains the specified element 577: * @throws ClassCastException if the class of the specified element 578: * is incompatible with this deque (optional) 579: * @throws NullPointerException if the specified element is null (optional) 580: */ 581: public boolean contains(Object o); 582: 583: /** 584: * Returns the number of elements in this deque. 585: * 586: * @return the number of elements in this deque 587: */ 588: public int size(); 589: 590: /** 591: * Returns an iterator over the elements in this deque in proper sequence. 592: * The elements will be returned in order from first (head) to last (tail). 593: * 594: * @return an iterator over the elements in this deque in proper sequence 595: */ 596: Iterator<E> iterator(); 597: 598: // *** Stack methods *** 599: 600: /** 601: * Pushes an element onto the stack represented by this deque. In other 602: * words, inserts the element at the front of this deque unless it would 603: * violate capacity restrictions. 604: * 605: * <p>This method is equivalent to {@link #addFirst(Object) addFirst}. 606: * 607: * @throws IllegalStateException {@inheritDoc} 608: * @throws ClassCastException {@inheritDoc} 609: * @throws NullPointerException if the specified element is null 610: * @throws IllegalArgumentException {@inheritDoc} 611: */ 612: void push(E e); 613: }
GNU Classpath (0.98) |