01: /*
02: * Copyright (c) 2001 by Matt Welsh and The Regents of the University of
03: * California. All rights reserved.
04: *
05: * Permission to use, copy, modify, and distribute this software and its
06: * documentation for any purpose, without fee, and without written agreement is
07: * hereby granted, provided that the above copyright notice and the following
08: * two paragraphs appear in all copies of this software.
09: *
10: * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
11: * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
12: * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
13: * CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
14: *
15: * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
16: * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
17: * AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
18: * ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
19: * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
20: *
21: * Author: Matt Welsh <mdw@cs.berkeley.edu>
22: *
23: */
24:
25: package seda.sandStorm.api;
26:
27: /**
28: * A SourceIF implements the 'source side' of an event queue: it supports
29: * dequeue operations only.
30: *
31: * @author Matt Welsh
32: */
33:
34: public interface SourceIF {
35:
36: /**
37: * Dequeues the next element, or returns <code>null</code> if there is
38: * nothing left on the queue.
39: *
40: * @return the next <code>QueueElementIF</code> on the queue
41: */
42: public QueueElementIF dequeue();
43:
44: /**
45: * Dequeues all available elements, or returns <code>null</code> if there is
46: * nothing left on the queue.
47: *
48: * @return all pending <code>QueueElementIF</code>s on the queue
49: */
50: public QueueElementIF[] dequeue_all();
51:
52: /**
53: * Dequeues at most <code>num</code> available elements, or returns
54: * <code>null</code> if there is nothing left on the queue.
55: *
56: * @return At most <code>num</code> <code>QueueElementIF</code>s on the queue
57: */
58: public QueueElementIF[] dequeue(int num);
59:
60: /**
61: * Just like blocking_dequeue_all, but returns only a single element.
62: */
63: public QueueElementIF blocking_dequeue(int timeout_millis);
64:
65: /**
66: * This method blocks on the queue up until a timeout occurs or
67: * until an element appears on the queue. It returns all elements waiting
68: * on the queue at that time.
69: *
70: * @param timeout_millis if timeout_millis is <code>0</code>, this method
71: * will be non-blocking and will return right away, whether or not
72: * any elements are pending on the queue. If timeout_millis is
73: * <code>-1</code>, this method blocks forever until something is
74: * available. If timeout_millis is positive, this method will wait
75: * about that number of milliseconds before returning, but possibly a
76: * little more.
77: *
78: * @return an array of <code>QueueElementIF</code>'s. This array will
79: * be null if no elements were pending.
80: */
81: public QueueElementIF[] blocking_dequeue_all(int timeout_millis);
82:
83: /**
84: * This method blocks on the queue up until a timeout occurs or
85: * until an element appears on the queue. It returns at most
86: * <code>num</code> elements waiting on the queue at that time.
87: */
88: public QueueElementIF[] blocking_dequeue(int timeout_millis, int num);
89:
90: /**
91: * Returns the number of elements waiting in this queue.
92: */
93: public int size();
94:
95: }
|