01: /*
02: File: Puttable.java
03:
04: Originally written by Doug Lea and released into the public domain.
05: This may be used for any purposes whatsoever without acknowledgment.
06: Thanks for the assistance and support of Sun Microsystems Labs,
07: and everyone contributing, testing, and using this code.
08:
09: 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 producer object can be declared as only a Puttable
20: * rather than a Channel, in which case a Java compiler
21: * will disallow take 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 Takable
27: **/
28:
29: public interface Puttable {
30:
31: /**
32: * Place item in the channel, possibly waiting indefinitely until
33: * it can be accepted. Channels implementing the BoundedChannel
34: * subinterface are generally guaranteed to block on puts upon
35: * reaching capacity, but other implementations may or may not block.
36: * @param item the element to be inserted. Should be non-null.
37: * @exception InterruptedException if the current thread has
38: * been interrupted at a point at which interruption
39: * is detected, in which case the element is guaranteed not
40: * to be inserted. Otherwise, on normal return, the element is guaranteed
41: * to have been inserted.
42: **/
43: public void put(Object item) throws InterruptedException;
44:
45: /**
46: * Place item in channel only if it can be accepted within
47: * msecs milliseconds. The time bound is interpreted in
48: * a coarse-grained, best-effort fashion.
49: * @param item the element to be inserted. Should be non-null.
50: * @param msecs the number of milliseconds to wait. If less than
51: * or equal to zero, the method does not perform any timed waits,
52: * but might still require
53: * access to a synchronization lock, which can impose unbounded
54: * delay if there is a lot of contention for the channel.
55: * @return true if accepted, else false
56: * @exception InterruptedException if the current thread has
57: * been interrupted at a point at which interruption
58: * is detected, in which case the element is guaranteed not
59: * to be inserted (i.e., is equivalent to a false return).
60: **/
61: public boolean offer(Object item, long msecs)
62: throws InterruptedException;
63: }
|