1   /*
    2     File: Takable.java
    3   
    4     Originally written by Doug Lea and released into the public domain.
    5     This may be used for any purposes whatsoever without acknowledgment.
    6     Thanks for the assistance and support of Sun Microsystems Labs,
    7     and everyone contributing, testing, and using this code.
    8   
    9     History:
   10     Date       Who                What
   11     11Jun1998  dl               Create public version
   12   */
   13   
   14   package EDU.oswego.cs.dl.util.concurrent;
   15   
   16   /** 
   17    * This interface exists to enable stricter type checking
   18    * for channels. A method argument or instance variable
   19    * in a consumer object can be declared as only a Takable
   20    * rather than a Channel, in which case a Java compiler
   21    * will disallow put operations.
   22    * <p>
   23    * Full method descriptions appear in the Channel interface.
   24    * <p>[<a href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html"> Introduction to this package. </a>]
   25    * @see Channel
   26    * @see Puttable
   27   **/
   28   
   29   public interface Takable {
   30   
   31     /** 
   32      * Return and remove an item from channel, 
   33      * possibly waiting indefinitely until
   34      * such an item exists.
   35      * @return  some item from the channel. Different implementations
   36      *  may guarantee various properties (such as FIFO) about that item
   37      * @exception InterruptedException if the current thread has
   38      * been interrupted at a point at which interruption
   39      * is detected, in which case state of the channel is unchanged.
   40      *
   41     **/
   42     public Object take() throws InterruptedException;
   43   
   44   
   45     /** 
   46      * Return and remove an item from channel only if one is available within
   47      * msecs milliseconds. The time bound is interpreted in a coarse
   48      * grained, best-effort fashion.
   49      * @param msecs the number of milliseconds to wait. If less than
   50      *  or equal to zero, the operation does not perform any timed waits,
   51      * but might still require
   52      * access to a synchronization lock, which can impose unbounded
   53      * delay if there is a lot of contention for the channel.
   54      * @return some item, or null if the channel is empty.
   55      * @exception InterruptedException if the current thread has
   56      * been interrupted at a point at which interruption
   57      * is detected, in which case state of the channel is unchanged
   58      * (i.e., equivalent to a false return).
   59     **/
   60   
   61     public Object poll(long msecs) throws InterruptedException;
   62   
   63   }