ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/experimental/server/Queue/Queue.java
(Generate patch)

Comparing experimental/server/Queue/Queue.java (file contents):
Revision 1.1 by tdb, Thu Dec 28 00:58:43 2000 UTC vs.
Revision 1.7 by tdb, Mon Feb 12 02:27:56 2001 UTC

# Line 1 | Line 1
1 + //---PACKAGE DECLARATION---
2 + //package uk.ac.ukc.iscream.util;
3 +
4 + //---IMPORTS---
5   import java.util.LinkedList;
6   import java.util.NoSuchElementException;
7 + //import uk.ac.ukc.iscream.util.*;
8  
9 < class Queue {
9 > /**
10 > * A Queue class designed to operate in a multi-threaded environment, with
11 > * added support for multiple "consumer" threads. Also offers blocking on
12 > * the get() methods, which ensures the consumer waits until the queue
13 > * actually contains some elements.
14 > *
15 > * @author  $Author$
16 > * @version $Id$
17 > */
18 > public class Queue {
19 >
20 > //---FINAL ATTRIBUTES---
21 >
22 >    /**
23 >     * The current CVS revision of this class
24 >     */
25 >    public static final String REVISION = "$Revision$";
26      
27 <    public Queue() {
28 <        // Possible use this method instead ?
29 <        //_list = Collections.synchronizedList(new LinkedList(...));
30 <        _list = new LinkedList();
31 <    }
27 > //---STATIC METHODS---
28 >
29 > //---CONSTRUCTORS---  
30 >
31 > //---PUBLIC METHODS---
32      
33 <    public synchronized void add(Object o) {
34 <        int s = _list.size();
35 <        // add() does the same thing, but this ensures behaviour
36 <        _list.addLast(o);
37 <        if (s == 0) {
38 <            notifyAll();
33 >    /**
34 >     * This method adds a given object to every queue. It will notify
35 >     * any waiting consumers (on an empty queue) during this process.
36 >     *
37 >     * @param o An Object to be added to the queues.
38 >     */
39 >    public void add(Object o) {
40 >        for(int i=0; i < _lists.size(); i++) {
41 >            // skip over any gaps left in the list
42 >            if(_lists.get(i) != null) {
43 >                int s = ((LinkedList) _lists.get(i)).size();
44 >                synchronized(this) {
45 >                    // add() does the same thing, but this ensures behaviour
46 >                    ((LinkedList) _lists.get(i)).addLast(o);
47 >                }
48 >                // if the queue was empty before the add it is possible
49 >                // that a consumer is waiting... so we notify them
50 >                if (s == 0) {
51 >                    synchronized(((LinkedList) _lists.get(i))) {
52 >                        ((LinkedList) _lists.get(i)).notifyAll();
53 >                    }
54 >                }
55 >            }
56          }
57 +        // we keep track of the total additions for the status() method
58          _count++;
59      }
60      
61 <    public synchronized Object get() {
62 <        if (_list.size() == 0) {
63 <            try { wait(); } catch(Exception e) {}
61 >    /**
62 >     * This method returns an object from the front of a given queue.
63 >     * It will block until data exists in the queue if required.
64 >     *
65 >     * @param The queue to retrieve data from.
66 >     * @return The object from the front of the queue.
67 >     * @throws InvalidQueueException if the queue does not exist.
68 >     */
69 >    public Object get(int queue) throws InvalidQueueException {
70 >        // make sure queue exists
71 >        if (queue >= _lists.size() || _lists.get(queue) == null) {
72 >            throw new InvalidQueueException("Requested queue "+queue+" does not exist");
73          }
74 +        // block if the queue is empty
75 +        if (((LinkedList) _lists.get(queue)).size() == 0) {
76 +            synchronized(((LinkedList) _lists.get(queue))) {
77 +                try { ((LinkedList) _lists.get(queue)).wait(); } catch(Exception e) {}
78 +            }
79 +        }
80 +        // get an item, it should never be null due to the blocking above
81          Object o = null;
82 <        try {
83 <            o = _list.removeFirst();
82 >        synchronized(this) {
83 >            try {
84 >                o = ((LinkedList) _lists.get(queue)).removeFirst();
85 >            }
86 >            catch (NoSuchElementException e) {
87 >                // This should never happen !
88 >            }
89          }
30        catch (NoSuchElementException e) {
31            // no element... null already... so just leave
32        }
90          return o;
91      }
92      
93 <    public String status() {
94 <        String status = "";
95 <        status += "Current queue size = "+_list.size();
96 <        status += "\n";
97 <        status += "Queue-ometer = "+_count;
93 >    /**
94 >     * This method releases a get() method that's currently
95 >     * waiting on an empty queue. This was designed for
96 >     * shutdown() type methods that may have problems closing
97 >     * if the thread of control is waiting on a queue.
98 >     *
99 >     * @param queue the queue to release.
100 >     */
101 >    public void releaseQueue(int queue) {
102 >        synchronized(((LinkedList) _lists.get(queue))) {
103 >                ((LinkedList) _lists.get(queue)).notifyAll();
104 >        }
105 >    }
106 >
107 >    /**
108 >     * This method erases the contents of a given queue. This
109 >     * method should be used with care. It can only empty one
110 >     * internal queue, not all of them. This must be called
111 >     * multiple times to empty all queues.
112 >     *
113 >     * @param queue the queue to empty.
114 >     */
115 >    public void clearQueue(int queue) {
116 >        synchronized(this) {
117 >            ((LinkedList) _lists.get(queue)).clear();
118 >        }
119 >    }
120 >    
121 >    /**
122 >     * This method returns an XML textual status of the queues.
123 >     * It is merely for observation, and would most likely be
124 >     * used by a larger "monitoring" component. Information
125 >     * returned includes the current size of each queue, and
126 >     * the total items passed through.
127 >     *
128 >     * @return A String message containing status information in XML format
129 >     */
130 >    public String xmlStatus() {
131 >        String status = "<queue ";
132 >        for(int i=0; i < _lists.size(); i++) {
133 >            // check for null entries
134 >            if(_lists.get(i) != null) {
135 >                status += "queue"+i+"=\""+((LinkedList) _lists.get(i)).size()+"\" ";
136 >            }
137 >            else {
138 >                status += "queue"+i+"=\"null\" ";
139 >            }
140 >        }
141 >        status += "total=\""+_count+"\"></queue>";
142          return status;
143      }
144      
145 <    private LinkedList _list;
146 <    private int _count;
147 < }
145 >    /**
146 >     * Returns the size of a given queue. A consumer can use
147 >     * this to see how big their queue is at any given time.
148 >     * they should use their queue number as the parameter.
149 >     *
150 >     * @param queue The queue number to query.
151 >     * @return the current size of the queue.
152 >     * @throws InvalidQueueException if the queue does not exist.
153 >     */
154 >    public int queueSize(int queue) throws InvalidQueueException {
155 >        if (queue >= _lists.size() || _lists.get(queue) == null) {
156 >            throw new InvalidQueueException("Requested queue "+queue+" does not exist");
157 >        }
158 >        return ((LinkedList) _lists.get(queue)).size();
159 >    }
160 >    
161 >    /**
162 >     * Returns the total numer of elements to have passed
163 >     * through this queue (ie. a counter on the add method).
164 >     *
165 >     * @return the element-ometer.
166 >     */
167 >    public int elementCount() {
168 >        return _count;
169 >    }
170 >    
171 >    /**
172 >     * This method assigns a queue to a consumer. The idea behind
173 >     * this is to ensure that only 1 consumer can be associated with
174 >     * a given queue, otherwise the whole "blocking" thing fails
175 >     * miserably. Queues are created upon requested.
176 >     *
177 >     * It is IMPORTANT that removeQueue() is used when the queue is
178 >     * no longer required.
179 >     *
180 >     * @return An integer to be passed to the get() method.
181 >     */
182 >    public int getQueue() {
183 >        int pos = -1;
184 >        for(int i=0; i < _lists.size(); i++) {
185 >            if(_lists.get(i) == null) {
186 >                // found a gap, re-use it
187 >                pos = i;
188 >                _lists.set(i, new LinkedList());
189 >            }
190 >        }
191 >        if(pos == -1) {
192 >            //we didn't find a gap, add at end
193 >            pos = _lists.size();
194 >            _lists.add(pos, new LinkedList());
195 >        }
196 >        return pos;
197 >    }
198 >    
199 >    /**
200 >     * This method sets a entry to null in the list. This ensures
201 >     * that it will no longer be added to after it is no longer
202 >     * required be a consumer.
203 >     *
204 >     * @param queue The integer identifier for the queue, given by getQueue().
205 >     */
206 >    public void removeQueue(int queue) {
207 >        _lists.set(queue, null);
208 >    }
209 >    
210 >    /**
211 >     * Start a monitor on our own Queue. This will log XML
212 >     * statistics about our Queue to a given Queue (could be
213 >     * the one being monitored).
214 >     *
215 >     * @param interval The long interval, in milliseconds, at which to take samples
216 >     * @param destQueue The queue to monitor to
217 >     * @param name A name to identify this Queue with
218 >     * @return whether we succeeded
219 >     */
220 >    public boolean startMonitor(long interval, Queue destQueue, String name) {
221 >        if(_queueMon == null) {
222 >            // start a monitor
223 >            _queueMon = new QueueMonitor(this, destQueue, interval, name);
224 >            _queueMon.start();
225 >            return true;
226 >        }
227 >        else {
228 >            // already have a monitor running
229 >            return false;
230 >        }
231 >    }
232 >    
233 >    /**
234 >     * Start a monitor on our own Queue. This will log XML
235 >     * statistics about our Queue to this Queue.
236 >     *
237 >     * @param interval The long interval, in milliseconds, at which to take samples
238 >     * @param name A name to identify this Queue with
239 >     * @return whether we succeeded
240 >     */
241 >    public boolean startMonitor(long interval, String name) {
242 >        return startMonitor(interval, this, name);
243 >    }
244 >    
245 >    /**
246 >     * Stop a monitor on our Queue if we have on running.
247 >     *
248 >     * @return whether we succeeded
249 >     */
250 >    public boolean stopMonitor() {
251 >        if(_queueMon != null) {
252 >            // stop a monitor
253 >            _queueMon.shutdown();
254 >            _queueMon = null;
255 >            return true;
256 >        }
257 >        else {
258 >            // no monitor running
259 >            return false;
260 >        }
261 >    }
262 >    
263 >    /**
264 >     * Overrides the {@link java.lang.Object#toString() Object.toString()}
265 >     * method to provide clean logging (every class should have this).
266 >     *
267 >     * This uses the uk.ac.ukc.iscream.util.FormatName class
268 >     * to format the toString()
269 >     *
270 >     * @return the name of this class and its CVS revision.
271 >     */
272 >    public String toString() {
273 >        return FormatName.getName(
274 >            _name,
275 >            getClass().getName(),
276 >            REVISION);
277 >    }
278 >
279 > //---PRIVATE METHODS---
280 >
281 > //---ACCESSOR/MUTATOR METHODS---
282 >
283 > //---ATTRIBUTES---
284 >    
285 >    /**
286 >     * The LinkedLists of queues.
287 >     */
288 >    private LinkedList _lists = new LinkedList();
289 >    
290 >    /**
291 >     * A counter so we know how many data items have been
292 >     * passed through, for statistical purposes.
293 >     */
294 >    private int _count = 0;
295 >    
296 >    /**
297 >     * A reference to our QueueMonitor, if we have one.
298 >     */
299 >    private QueueMonitor _queueMon = null;
300 >    
301 >    /**
302 >     * This is the friendly identifier of the
303 >     * component this class is running in.
304 >     * eg, a Filter may be called "filter1",
305 >     * If this class does not have an owning
306 >     * component,  a name from the configuration
307 >     * can be placed here.  This name could also
308 >     * be changed to null for utility classes.
309 >     */
310 >    private String _name = null;
311 >
312 > //---STATIC ATTRIBUTES---
313 >
314 > }

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines